diff options
Diffstat (limited to 'Documentation')
1014 files changed, 25408 insertions, 8995 deletions
diff --git a/Documentation/ABI/stable/sysfs-driver-dma-idxd b/Documentation/ABI/stable/sysfs-driver-dma-idxd index b5bebf642db6..1af9c4175213 100644 --- a/Documentation/ABI/stable/sysfs-driver-dma-idxd +++ b/Documentation/ABI/stable/sysfs-driver-dma-idxd @@ -1,47 +1,47 @@ -What: sys/bus/dsa/devices/dsa<m>/version +What: /sys/bus/dsa/devices/dsa<m>/version Date: Apr 15, 2020 KernelVersion: 5.8.0 Contact: dmaengine@vger.kernel.org Description: The hardware version number. -What: sys/bus/dsa/devices/dsa<m>/cdev_major +What: /sys/bus/dsa/devices/dsa<m>/cdev_major Date: Oct 25, 2019 -KernelVersion: 5.6.0 +KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The major number that the character device driver assigned to this device. -What: sys/bus/dsa/devices/dsa<m>/errors +What: /sys/bus/dsa/devices/dsa<m>/errors Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The error information for this device. -What: sys/bus/dsa/devices/dsa<m>/max_batch_size +What: /sys/bus/dsa/devices/dsa<m>/max_batch_size Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The largest number of work descriptors in a batch. -What: sys/bus/dsa/devices/dsa<m>/max_work_queues_size +What: /sys/bus/dsa/devices/dsa<m>/max_work_queues_size Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The maximum work queue size supported by this device. -What: sys/bus/dsa/devices/dsa<m>/max_engines +What: /sys/bus/dsa/devices/dsa<m>/max_engines Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The maximum number of engines supported by this device. -What: sys/bus/dsa/devices/dsa<m>/max_groups +What: /sys/bus/dsa/devices/dsa<m>/max_groups Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The maximum number of groups can be created under this device. -What: sys/bus/dsa/devices/dsa<m>/max_tokens +What: /sys/bus/dsa/devices/dsa<m>/max_tokens Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org @@ -50,7 +50,7 @@ Description: The total number of bandwidth tokens supported by this device. implementation, and these resources are allocated by engines to support operations. -What: sys/bus/dsa/devices/dsa<m>/max_transfer_size +What: /sys/bus/dsa/devices/dsa<m>/max_transfer_size Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org @@ -58,57 +58,57 @@ Description: The number of bytes to be read from the source address to perform the operation. The maximum transfer size is dependent on the workqueue the descriptor was submitted to. -What: sys/bus/dsa/devices/dsa<m>/max_work_queues +What: /sys/bus/dsa/devices/dsa<m>/max_work_queues Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The maximum work queue number that this device supports. -What: sys/bus/dsa/devices/dsa<m>/numa_node +What: /sys/bus/dsa/devices/dsa<m>/numa_node Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The numa node number for this device. -What: sys/bus/dsa/devices/dsa<m>/op_cap +What: /sys/bus/dsa/devices/dsa<m>/op_cap Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The operation capability bit mask specify the operation types supported by the this device. -What: sys/bus/dsa/devices/dsa<m>/state +What: /sys/bus/dsa/devices/dsa<m>/state Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The state information of this device. It can be either enabled or disabled. -What: sys/bus/dsa/devices/dsa<m>/group<m>.<n> +What: /sys/bus/dsa/devices/dsa<m>/group<m>.<n> Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The assigned group under this device. -What: sys/bus/dsa/devices/dsa<m>/engine<m>.<n> +What: /sys/bus/dsa/devices/dsa<m>/engine<m>.<n> Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The assigned engine under this device. -What: sys/bus/dsa/devices/dsa<m>/wq<m>.<n> +What: /sys/bus/dsa/devices/dsa<m>/wq<m>.<n> Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The assigned work queue under this device. -What: sys/bus/dsa/devices/dsa<m>/configurable +What: /sys/bus/dsa/devices/dsa<m>/configurable Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: To indicate if this device is configurable or not. -What: sys/bus/dsa/devices/dsa<m>/token_limit +What: /sys/bus/dsa/devices/dsa<m>/token_limit Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org @@ -116,19 +116,19 @@ Description: The maximum number of bandwidth tokens that may be in use at one time by operations that access low bandwidth memory in the device. -What: sys/bus/dsa/devices/wq<m>.<n>/group_id +What: /sys/bus/dsa/devices/wq<m>.<n>/group_id Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The group id that this work queue belongs to. -What: sys/bus/dsa/devices/wq<m>.<n>/size +What: /sys/bus/dsa/devices/wq<m>.<n>/size Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The work queue size for this work queue. -What: sys/bus/dsa/devices/wq<m>.<n>/type +What: /sys/bus/dsa/devices/wq<m>.<n>/type Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org @@ -136,20 +136,20 @@ Description: The type of this work queue, it can be "kernel" type for work queue usages in the kernel space or "user" type for work queue usages by applications in user space. -What: sys/bus/dsa/devices/wq<m>.<n>/cdev_minor +What: /sys/bus/dsa/devices/wq<m>.<n>/cdev_minor Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The minor number assigned to this work queue by the character device driver. -What: sys/bus/dsa/devices/wq<m>.<n>/mode +What: /sys/bus/dsa/devices/wq<m>.<n>/mode Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The work queue mode type for this work queue. -What: sys/bus/dsa/devices/wq<m>.<n>/priority +What: /sys/bus/dsa/devices/wq<m>.<n>/priority Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org @@ -157,20 +157,20 @@ Description: The priority value of this work queue, it is a vlue relative to other work queue in the same group to control quality of service for dispatching work from multiple workqueues in the same group. -What: sys/bus/dsa/devices/wq<m>.<n>/state +What: /sys/bus/dsa/devices/wq<m>.<n>/state Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The current state of the work queue. -What: sys/bus/dsa/devices/wq<m>.<n>/threshold +What: /sys/bus/dsa/devices/wq<m>.<n>/threshold Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org Description: The number of entries in this work queue that may be filled via a limited portal. -What: sys/bus/dsa/devices/engine<m>.<n>/group_id +What: /sys/bus/dsa/devices/engine<m>.<n>/group_id Date: Oct 25, 2019 KernelVersion: 5.6.0 Contact: dmaengine@vger.kernel.org diff --git a/Documentation/ABI/stable/sysfs-driver-mlxreg-io b/Documentation/ABI/stable/sysfs-driver-mlxreg-io index b0d90cc696a8..fd9a8045bb0c 100644 --- a/Documentation/ABI/stable/sysfs-driver-mlxreg-io +++ b/Documentation/ABI/stable/sysfs-driver-mlxreg-io @@ -206,3 +206,20 @@ Description: This file exposes the firmware version of burnable voltage regulator devices. The file is read only. + +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld1_pn +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld2_pn +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld3_pn +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld4_pn +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld1_version_min +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld2_version_min +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld3_version_min +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/cpld4_version_min +Date: July 2020 +KernelVersion: 5.9 +Contact: Vadim Pasternak <vadimpmellanox.com> +Description: These files show with which CPLD part numbers and minor + versions have been burned CPLD devices equipped on a + system. + + The files are read only. diff --git a/Documentation/ABI/stable/sysfs-driver-speakup b/Documentation/ABI/stable/sysfs-driver-speakup new file mode 100644 index 000000000000..c6a32c434ce9 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-driver-speakup @@ -0,0 +1,375 @@ +What: /sys/accessibility/speakup/attrib_bleep +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Beeps the PC speaker when there is an attribute change such as + foreground or background color when using speakup review + commands. One = on, zero = off. + +What: /sys/accessibility/speakup/bell_pos +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This works much like a typewriter bell. If for example 72 is + echoed to bell_pos, it will beep the PC speaker when typing on + a line past character 72. + +What: /sys/accessibility/speakup/bleeps +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This controls whether one hears beeps through the PC speaker + when using speakup's review commands. + TODO: what values does it accept? + +What: /sys/accessibility/speakup/bleep_time +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This controls the duration of the PC speaker beeps speakup + produces. + TODO: What are the units? Jiffies? + +What: /sys/accessibility/speakup/cursor_time +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This controls cursor delay when using arrow keys. When a + connection is very slow, with the default setting, when moving + with the arrows, or backspacing etc. speakup says the incorrect + characters. Set this to a higher value to adjust for the delay + and better synchronisation between cursor position and speech. + +What: /sys/accessibility/speakup/delimiters +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Delimit a word from speakup. + TODO: add more info + +What: /sys/accessibility/speakup/ex_num +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: TODO: + +What: /sys/accessibility/speakup/key_echo +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Controls if speakup speaks keys when they are typed. One = on, + zero = off or don't echo keys. + +What: /sys/accessibility/speakup/keymap +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Speakup keymap remaps keys to Speakup functions. + It uses a binary + format. A special program called genmap is needed to compile a + textual keymap into the binary format which is then loaded into + /sys/accessibility/speakup/keymap. + +What: /sys/accessibility/speakup/no_interrupt +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Controls if typing interrupts output from speakup. With + no_interrupt set to zero, typing on the keyboard will interrupt + speakup if for example + the say screen command is used before the + entire screen is read. + With no_interrupt set to one, if the say + screen command is used, and one then types on the keyboard, + speakup will continue to say the whole screen regardless until + it finishes. + +What: /sys/accessibility/speakup/punc_all +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This is a list of all the punctuation speakup should speak when + punc_level is set to four. + +What: /sys/accessibility/speakup/punc_level +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Controls the level of punctuation spoken as the screen is + displayed, not reviewed. Levels range from zero no punctuation, + to four, all punctuation. One corresponds to punc_some, two + corresponds to punc_most, and three as well as four both + correspond to punc_all. Some hardware synthesizers may have + different levels each corresponding to three and four for + punc_level. Also note that if punc_level is set to zero, and + key_echo is set to one, typed punctuation is still spoken as it + is typed. + +What: /sys/accessibility/speakup/punc_most +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This is a list of all the punctuation speakup should speak when + punc_level is set to two. + +What: /sys/accessibility/speakup/punc_some +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This is a list of all the punctuation speakup should speak when + punc_level is set to one. + +What: /sys/accessibility/speakup/reading_punc +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Almost the same as punc_level, the differences being that + reading_punc controls the level of punctuation when reviewing + the screen with speakup's screen review commands. The other + difference is that reading_punc set to three speaks punc_all, + and reading_punc set to four speaks all punctuation, including + spaces. + +What: /sys/accessibility/speakup/repeats +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: A list of characters speakup repeats. Normally, when there are + more than three characters in a row, speakup + just reads three of + those characters. For example, "......" would be read as dot, + dot, dot. If a . is added to the list of characters in repeats, + "......" would be read as dot, dot, dot, times six. + +What: /sys/accessibility/speakup/say_control +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: If set to one, speakup speaks shift, alt and control when those + keys are pressed. If say_control is set to zero, shift, ctrl, + and alt are not spoken when they are pressed. + +What: /sys/accessibility/speakup/say_word_ctl +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: TODO: + +What: /sys/accessibility/speakup/silent +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: TODO: + +What: /sys/accessibility/speakup/spell_delay +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This controls how fast a word is spelled + when speakup's say word + review command is pressed twice quickly to speak the current + word being reviewed. Zero just speaks the letters one after + another, while values one through four + seem to introduce more of + a pause between the spelling of each letter by speakup. + +What: /sys/accessibility/speakup/synth +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Gets or sets the synthesizer driver currently in use. Reading + synth returns the synthesizer driver currently in use. Writing + synth switches to the given synthesizer driver, provided it is + either built into the kernel, or already loaded as a module. + +What: /sys/accessibility/speakup/synth_direct +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Sends whatever is written to synth_direct + directly to the speech synthesizer in use, bypassing speakup. + This could be used to make the synthesizer speak + a string, or to + send control sequences to the synthesizer to change how the + synthesizer behaves. + +What: /sys/accessibility/speakup/version +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Reading version returns the version of speakup, and the version + of the synthesizer driver currently in use. + +What: /sys/accessibility/speakup/i18n/announcements +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This file contains various general announcements, most of which + cannot be categorized. You will find messages such as "You + killed Speakup", "I'm alive", "leaving help", "parked", + "unparked", and others. You will also find the names of the + screen edges and cursor tracking modes here. + +What: /sys/accessibility/speakup/i18n/chartab +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: TODO + +What: /sys/accessibility/speakup/i18n/ctl_keys +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Here, you will find names of control keys. These are used with + Speakup's say_control feature. + +What: /sys/accessibility/speakup/i18n/function_names +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Here, you will find a list of names for Speakup functions. + These are used by the help system. For example, suppose that + you have activated help mode, and you pressed + keypad 3. Speakup + says: "keypad 3 is character, say next." + The message "character, say next" names a Speakup function, and + it comes from this function_names file. + +What: /sys/accessibility/speakup/i18n/states +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This file contains names for key states. + Again, these are part of the help system. For instance, if you + had pressed speakup + keypad 3, you would hear: + "speakup keypad 3 is go to bottom edge." + The speakup key is depressed, so the name of the key state is + speakup. + This part of the message comes from the states collection. + +What: /sys/accessibility/speakup/i18n/characters +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Through this sys entry, Speakup gives you the ability to change + how Speakup pronounces a given character. You could, for + example, change how some punctuation characters are spoken. You + can even change how Speakup will pronounce certain letters. For + further details see '12. Changing the Pronunciation of + Characters' in Speakup User's Guide (file spkguide.txt in + source). + +What: /sys/accessibility/speakup/i18n/colors +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: When you use the "say attributes" function, Speakup says the + name of the foreground and background colors. These names come + from the i18n/colors file. + +What: /sys/accessibility/speakup/i18n/formatted +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This group of messages contains embedded formatting codes, to + specify the type and width of displayed data. If you change + these, you must preserve all of the formatting codes, and they + must appear in the order used by the default messages. + +What: /sys/accessibility/speakup/i18n/key_names +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Again, key_names is used by Speakup's help system. In the + previous example, Speakup said that you pressed "keypad 3." + This name came from the key_names file. + +What: /sys/accessibility/speakup/<synth-name>/ +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: In `/sys/accessibility/speakup` is a directory corresponding to + the synthesizer driver currently in use (E.G) `soft` for the + soft driver. This directory contains files which control the + speech synthesizer itself, + as opposed to controlling the speakup + screen reader. The parameters in this directory have the same + names and functions across all + supported synthesizers. The range + of values for freq, pitch, rate, and vol is the same for all + supported synthesizers, with the given range being internally + mapped by the driver to more or less fit the range of values + supported for a given parameter by the individual synthesizer. + Below is a description of values and parameters for soft + synthesizer, which is currently the most commonly used. + +What: /sys/accessibility/speakup/soft/caps_start +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This is the string that is sent to the synthesizer to cause it + to start speaking uppercase letters. For the soft synthesizer + and most others, this causes the pitch of the voice to rise + above the currently set pitch. + +What: /sys/accessibility/speakup/soft/caps_stop +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This is the string sent to the synthesizer to cause it to stop + speaking uppercase letters. In the case of the soft synthesizer + and most others, this returns the pitch of the voice + down to the + currently set pitch. + +What: /sys/accessibility/speakup/soft/delay_time +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: TODO: + +What: /sys/accessibility/speakup/soft/direct +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Controls if punctuation is spoken by speakup, or by the + synthesizer. + For example, speakup speaks ">" as "greater", while + the espeak synthesizer used by the soft driver speaks "greater + than". Zero lets speakup speak the punctuation. One lets the + synthesizer itself speak punctuation. + +What: /sys/accessibility/speakup/soft/freq +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Gets or sets the frequency of the speech synthesizer. Range is + 0-9. + +What: /sys/accessibility/speakup/soft/full_time +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: TODO: + +What: /sys/accessibility/speakup/soft/jiffy_delta +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This controls how many jiffys the kernel gives to the + synthesizer. Setting this too high can make a system unstable, + or even crash it. + +What: /sys/accessibility/speakup/soft/pitch +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Gets or sets the pitch of the synthesizer. The range is 0-9. + +What: /sys/accessibility/speakup/soft/inflection +KernelVersion: 5.8 +Contact: speakup@linux-speakup.org +Description: Gets or sets the inflection of the synthesizer, i.e. the pitch + range. The range is 0-9. + +What: /sys/accessibility/speakup/soft/punct +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Gets or sets the amount of punctuation spoken by the + synthesizer. The range for the soft driver seems to be 0-2. + TODO: How is this related to speakup's punc_level, or + reading_punc. + +What: /sys/accessibility/speakup/soft/rate +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Gets or sets the rate of the synthesizer. Range is from zero + slowest, to nine fastest. + +What: /sys/accessibility/speakup/soft/tone +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Gets or sets the tone of the speech synthesizer. The range for + the soft driver seems to be 0-2. This seems to make no + difference if using espeak and the espeakup connector. + TODO: does espeakup support different tonalities? + +What: /sys/accessibility/speakup/soft/trigger_time +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: TODO: + +What: /sys/accessibility/speakup/soft/voice +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Gets or sets the voice used by the synthesizer if the + synthesizer can speak in more than one voice. The range for the + soft driver is 0-7. Note that while espeak supports multiple + voices, this parameter will not set the voice when the espeakup + connector is used between speakup and espeak. + +What: /sys/accessibility/speakup/soft/vol +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Gets or sets the volume of the speech synthesizer. Range is 0-9, + with zero being the softest, and nine being the loudest. + diff --git a/Documentation/ABI/testing/debugfs-driver-habanalabs b/Documentation/ABI/testing/debugfs-driver-habanalabs index f6d9c2a8d528..2e9ae311e02d 100644 --- a/Documentation/ABI/testing/debugfs-driver-habanalabs +++ b/Documentation/ABI/testing/debugfs-driver-habanalabs @@ -16,7 +16,16 @@ Description: Allow the root user to disable/enable in runtime the clock gating mechanism in Gaudi. Due to how Gaudi is built, the clock gating needs to be disabled in order to access the registers of the TPC and MME engines. This is sometimes needed - during debug by the user and hence the user needs this option + during debug by the user and hence the user needs this option. + The user can supply a bitmask value, each bit represents + a different engine to disable/enable its clock gating feature. + The bitmask is composed of 20 bits: + 0 - 7 : DMA channels + 8 - 11 : MME engines + 12 - 19 : TPC engines + The bit's location of a specific engine can be determined + using (1 << GAUDI_ENGINE_ID_*). GAUDI_ENGINE_ID_* values + are defined in uapi habanalabs.h file in enum gaudi_engine_id What: /sys/kernel/debug/habanalabs/hl<n>/command_buffers Date: Jan 2019 diff --git a/Documentation/ABI/testing/debugfs-turris-mox-rwtm b/Documentation/ABI/testing/debugfs-turris-mox-rwtm new file mode 100644 index 000000000000..2b3255ee68fd --- /dev/null +++ b/Documentation/ABI/testing/debugfs-turris-mox-rwtm @@ -0,0 +1,9 @@ +What: /sys/kernel/debug/turris-mox-rwtm/do_sign +Date: Jun 2020 +KernelVersion: 5.8 +Contact: Marek Behún <marek.behun@nic.cz> +Description: (W) Message to sign with the ECDSA private key stored in + device's OTP. The message must be exactly 64 bytes (since + this is intended for SHA-512 hashes). + (R) The resulting signature, 136 bytes. This contains the R and + S values of the ECDSA signature, both in big-endian format. diff --git a/Documentation/ABI/testing/dev-kmsg b/Documentation/ABI/testing/dev-kmsg index 1e6c28b1942b..3c0bb76e3417 100644 --- a/Documentation/ABI/testing/dev-kmsg +++ b/Documentation/ABI/testing/dev-kmsg @@ -56,10 +56,16 @@ Description: The /dev/kmsg character device node provides userspace access seek after the last record available at the time the last SYSLOG_ACTION_CLEAR was issued. - Due to the record nature of this interface with a "read all" - behavior and the specific positions each seek operation sets, - SEEK_CUR is not supported, returning -ESPIPE (invalid seek) to - errno whenever requested. + Other seek operations or offsets are not supported because of + the special behavior this device has. The device allows to read + or write only whole variable length messages (records) that are + stored in a ring buffer. + + Because of the non-standard behavior also the error values are + non-standard. -ESPIPE is returned for non-zero offset. -EINVAL + is returned for other operations, e.g. SEEK_CUR. This behavior + and values are historical and could not be modified without the + risk of breaking userspace. The output format consists of a prefix carrying the syslog prefix including priority and facility, the 64 bit message diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block index ed8c14f161ee..2322eb748b38 100644 --- a/Documentation/ABI/testing/sysfs-block +++ b/Documentation/ABI/testing/sysfs-block @@ -273,6 +273,24 @@ Description: device ("host-aware" or "host-managed" zone model). For regular block devices, the value is always 0. +What: /sys/block/<disk>/queue/max_active_zones +Date: July 2020 +Contact: Niklas Cassel <niklas.cassel@wdc.com> +Description: + For zoned block devices (zoned attribute indicating + "host-managed" or "host-aware"), the sum of zones belonging to + any of the zone states: EXPLICIT OPEN, IMPLICIT OPEN or CLOSED, + is limited by this value. If this value is 0, there is no limit. + +What: /sys/block/<disk>/queue/max_open_zones +Date: July 2020 +Contact: Niklas Cassel <niklas.cassel@wdc.com> +Description: + For zoned block devices (zoned attribute indicating + "host-managed" or "host-aware"), the sum of zones belonging to + any of the zone states: EXPLICIT OPEN or IMPLICIT OPEN, + is limited by this value. If this value is 0, there is no limit. + What: /sys/block/<disk>/queue/chunk_sectors Date: September 2016 Contact: Hannes Reinecke <hare@suse.com> diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 index e8698afcd952..f7e32f218f73 100644 --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 @@ -43,6 +43,13 @@ Description: read only This sysfs interface exposes the number of cores per chip present in the system. +What: /sys/devices/hv_24x7/interface/cpumask +Date: July 2020 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: read only + This sysfs file exposes the cpumask which is designated to make + HCALLs to retrieve hv-24x7 pmu event counter data. + What: /sys/bus/event_source/devices/hv_24x7/event_descs/<event-name> Date: February 2014 Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index d3e53a6d8331..5c62bfb0f3f5 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -1569,7 +1569,8 @@ What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_voc_raw KernelVersion: 4.3 Contact: linux-iio@vger.kernel.org Description: - Raw (unscaled no offset etc.) percentage reading of a substance. + Raw (unscaled no offset etc.) reading of a substance. Units + after application of scale and offset are percents. What: /sys/bus/iio/devices/iio:deviceX/in_resistance_raw What: /sys/bus/iio/devices/iio:deviceX/in_resistanceX_raw diff --git a/Documentation/ABI/testing/sysfs-bus-iio-icm42600 b/Documentation/ABI/testing/sysfs-bus-iio-icm42600 new file mode 100644 index 000000000000..0bf1fd4f5bf1 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-icm42600 @@ -0,0 +1,20 @@ +What: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias +KernelVersion: 5.8 +Contact: linux-iio@vger.kernel.org +Description: + Hardware applied calibration offset (assumed to fix production + inaccuracies). Values represent a real physical offset expressed + in SI units (m/s^2 for accelerometer and rad/s for gyroscope). + +What: /sys/bus/iio/devices/iio:deviceX/in_accel_calibbias_available +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_calibbias_available +KernelVersion: 5.8 +Contact: linux-iio@vger.kernel.org +Description: + Range of available values for hardware offset. Values in SI + units (m/s^2 for accelerometer and rad/s for gyroscope). diff --git a/Documentation/ABI/testing/sysfs-bus-iio-scd30 b/Documentation/ABI/testing/sysfs-bus-iio-scd30 new file mode 100644 index 000000000000..b9712f390bec --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-scd30 @@ -0,0 +1,34 @@ +What: /sys/bus/iio/devices/iio:deviceX/calibration_auto_enable +Date: June 2020 +KernelVersion: 5.8 +Contact: linux-iio@vger.kernel.org +Description: + Contaminants build-up in the measurement chamber or optical + elements deterioration leads to sensor drift. + + One can compensate for sensor drift by using automatic self + calibration procedure (asc). + + Writing 1 or 0 to this attribute will respectively activate or + deactivate asc. + + Upon reading current asc status is returned. + +What: /sys/bus/iio/devices/iio:deviceX/calibration_forced_value +Date: June 2020 +KernelVersion: 5.8 +Contact: linux-iio@vger.kernel.org +Description: + Contaminants build-up in the measurement chamber or optical + elements deterioration leads to sensor drift. + + One can compensate for sensor drift by using forced + recalibration (frc). This is useful in case there's known + co2 reference available nearby the sensor. + + Picking value from the range [400 1 2000] and writing it to the + sensor will set frc. + + Upon reading current frc value is returned. Note that after + power cycling default value (i.e 400) is returned even though + internally sensor had recalibrated itself. diff --git a/Documentation/ABI/testing/sysfs-bus-optee-devices b/Documentation/ABI/testing/sysfs-bus-optee-devices new file mode 100644 index 000000000000..0f58701367b6 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-optee-devices @@ -0,0 +1,8 @@ +What: /sys/bus/tee/devices/optee-ta-<uuid>/ +Date: May 2020 +KernelVersion 5.8 +Contact: op-tee@lists.trustedfirmware.org +Description: + OP-TEE bus provides reference to registered drivers under this directory. The <uuid> + matches Trusted Application (TA) driver and corresponding TA in secure OS. Drivers + are free to create needed API under optee-ta-<uuid> directory. diff --git a/Documentation/ABI/testing/sysfs-bus-papr-pmem b/Documentation/ABI/testing/sysfs-bus-papr-pmem new file mode 100644 index 000000000000..c1a67275c43f --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-papr-pmem @@ -0,0 +1,54 @@ +What: /sys/bus/nd/devices/nmemX/papr/flags +Date: Apr, 2020 +KernelVersion: v5.8 +Contact: linuxppc-dev <linuxppc-dev@lists.ozlabs.org>, linux-nvdimm@lists.01.org, +Description: + (RO) Report flags indicating various states of a + papr-pmem NVDIMM device. Each flag maps to a one or + more bits set in the dimm-health-bitmap retrieved in + response to H_SCM_HEALTH hcall. The details of the bit + flags returned in response to this hcall is available + at 'Documentation/powerpc/papr_hcalls.rst' . Below are + the flags reported in this sysfs file: + + * "not_armed" : Indicates that NVDIMM contents will not + survive a power cycle. + * "flush_fail" : Indicates that NVDIMM contents + couldn't be flushed during last + shut-down event. + * "restore_fail": Indicates that NVDIMM contents + couldn't be restored during NVDIMM + initialization. + * "encrypted" : NVDIMM contents are encrypted. + * "smart_notify": There is health event for the NVDIMM. + * "scrubbed" : Indicating that contents of the + NVDIMM have been scrubbed. + * "locked" : Indicating that NVDIMM contents cant + be modified until next power cycle. + +What: /sys/bus/nd/devices/nmemX/papr/perf_stats +Date: May, 2020 +KernelVersion: v5.9 +Contact: linuxppc-dev <linuxppc-dev@lists.ozlabs.org>, linux-nvdimm@lists.01.org, +Description: + (RO) Report various performance stats related to papr-scm NVDIMM + device. Each stat is reported on a new line with each line + composed of a stat-identifier followed by it value. Below are + currently known dimm performance stats which are reported: + + * "CtlResCt" : Controller Reset Count + * "CtlResTm" : Controller Reset Elapsed Time + * "PonSecs " : Power-on Seconds + * "MemLife " : Life Remaining + * "CritRscU" : Critical Resource Utilization + * "HostLCnt" : Host Load Count + * "HostSCnt" : Host Store Count + * "HostSDur" : Host Store Duration + * "HostLDur" : Host Load Duration + * "MedRCnt " : Media Read Count + * "MedWCnt " : Media Write Count + * "MedRDur " : Media Read Duration + * "MedWDur " : Media Write Duration + * "CchRHCnt" : Cache Read Hit Count + * "CchWHCnt" : Cache Write Hit Count + * "FastWCnt" : Fast Write Count
\ No newline at end of file diff --git a/Documentation/ABI/testing/sysfs-bus-platform b/Documentation/ABI/testing/sysfs-bus-platform index 5172a6124b27..194ca700e962 100644 --- a/Documentation/ABI/testing/sysfs-bus-platform +++ b/Documentation/ABI/testing/sysfs-bus-platform @@ -18,3 +18,13 @@ Description: devices to opt-out of driver binding using a driver_override name such as "none". Only a single driver may be specified in the override, there is no support for parsing delimiters. + +What: /sys/bus/platform/devices/.../numa_node +Date: June 2020 +Contact: Barry Song <song.bao.hua@hisilicon.com> +Description: + This file contains the NUMA node to which the platform device + is attached. It won't be visible if the node is unknown. The + value comes from an ACPI _PXM method or a similar firmware + source. Initial users for this file would be devices like + arm smmu which are populated by arm64 acpi_iort. diff --git a/Documentation/ABI/testing/sysfs-bus-thunderbolt b/Documentation/ABI/testing/sysfs-bus-thunderbolt index 82e80de78dd0..dd565c378b40 100644 --- a/Documentation/ABI/testing/sysfs-bus-thunderbolt +++ b/Documentation/ABI/testing/sysfs-bus-thunderbolt @@ -178,11 +178,18 @@ KernelVersion: 4.13 Contact: thunderbolt-software@lists.01.org Description: When new NVM image is written to the non-active NVM area (through non_activeX NVMem device), the - authentication procedure is started by writing 1 to - this file. If everything goes well, the device is + authentication procedure is started by writing to + this file. + If everything goes well, the device is restarted with the new NVM firmware. If the image verification fails an error code is returned instead. + This file will accept writing values "1" or "2" + - Writing "1" will flush the image to the storage + area and authenticate the image in one action. + - Writing "2" will run some basic validation on the image + and flush it to the storage area. + When read holds status of the last authentication operation if an error occurred during the process. This is directly the status value from the DMA configuration @@ -236,3 +243,49 @@ KernelVersion: 4.15 Contact: thunderbolt-software@lists.01.org Description: This contains XDomain service specific settings as bitmask. Format: %x + +What: /sys/bus/thunderbolt/devices/<device>:<port>.<index>/device +Date: Oct 2020 +KernelVersion: v5.9 +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> +Description: Retimer device identifier read from the hardware. + +What: /sys/bus/thunderbolt/devices/<device>:<port>.<index>/nvm_authenticate +Date: Oct 2020 +KernelVersion: v5.9 +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> +Description: When new NVM image is written to the non-active NVM + area (through non_activeX NVMem device), the + authentication procedure is started by writing 1 to + this file. If everything goes well, the device is + restarted with the new NVM firmware. If the image + verification fails an error code is returned instead. + + When read holds status of the last authentication + operation if an error occurred during the process. + Format: %x. + +What: /sys/bus/thunderbolt/devices/<device>:<port>.<index>/nvm_version +Date: Oct 2020 +KernelVersion: v5.9 +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> +Description: Holds retimer NVM version number. Format: %x.%x, major.minor. + +What: /sys/bus/thunderbolt/devices/<device>:<port>.<index>/vendor +Date: Oct 2020 +KernelVersion: v5.9 +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> +Description: Retimer vendor identifier read from the hardware. + +What: /sys/bus/thunderbolt/devices/.../nvm_authenticate_on_disconnect +Date: Oct 2020 +KernelVersion: v5.9 +Contact: Mario Limonciello <mario.limonciello@dell.com> +Description: For supported devices, automatically authenticate the new Thunderbolt + image when the device is disconnected from the host system. + + This file will accept writing values "1" or "2" + - Writing "1" will flush the image to the storage + area and prepare the device for authentication on disconnect. + - Writing "2" will run some basic validation on the image + and flush it to the storage area. diff --git a/Documentation/ABI/testing/sysfs-class-devfreq b/Documentation/ABI/testing/sysfs-class-devfreq index 9758eb85ade3..deefffb3bbe4 100644 --- a/Documentation/ABI/testing/sysfs-class-devfreq +++ b/Documentation/ABI/testing/sysfs-class-devfreq @@ -108,3 +108,15 @@ Description: frequency requested by governors and min_freq. The max_freq overrides min_freq because max_freq may be used to throttle devices to avoid overheating. + +What: /sys/class/devfreq/.../timer +Date: July 2020 +Contact: Chanwoo Choi <cw00.choi@samsung.com> +Description: + This ABI shows and stores the kind of work timer by users. + This work timer is used by devfreq workqueue in order to + monitor the device status such as utilization. The user + can change the work timer on runtime according to their demand + as following: + echo deferrable > /sys/class/devfreq/.../timer + echo delayed > /sys/class/devfreq/.../timer diff --git a/Documentation/ABI/testing/sysfs-class-devlink b/Documentation/ABI/testing/sysfs-class-devlink new file mode 100644 index 000000000000..64791b65c9a3 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-devlink @@ -0,0 +1,126 @@ +What: /sys/class/devlink/.../ +Date: May 2020 +Contact: Saravana Kannan <saravanak@google.com> +Description: + Provide a place in sysfs for the device link objects in the + kernel at any given time. The name of a device link directory, + denoted as ... above, is of the form <supplier>--<consumer> + where <supplier> is the supplier device name and <consumer> is + the consumer device name. + +What: /sys/class/devlink/.../auto_remove_on +Date: May 2020 +Contact: Saravana Kannan <saravanak@google.com> +Description: + This file indicates if the device link will ever be + automatically removed by the driver core when the consumer and + supplier devices themselves are still present. + + This will be one of the following strings: + + 'consumer unbind' + 'supplier unbind' + 'never' + + 'consumer unbind' means the device link will be removed when + the consumer's driver is unbound from the consumer device. + + 'supplier unbind' means the device link will be removed when + the supplier's driver is unbound from the supplier device. + + 'never' means the device link will not be automatically removed + when as long as the supplier and consumer devices themselves + are still present. + +What: /sys/class/devlink/.../consumer +Date: May 2020 +Contact: Saravana Kannan <saravanak@google.com> +Description: + This file is a symlink to the consumer device's sysfs directory. + +What: /sys/class/devlink/.../runtime_pm +Date: May 2020 +Contact: Saravana Kannan <saravanak@google.com> +Description: + This file indicates if the device link has any impact on the + runtime power management behavior of the consumer and supplier + devices. For example: Making sure the supplier doesn't enter + runtime suspend while the consumer is active. + + This will be one of the following strings: + + '0' - Does not affect runtime power management + '1' - Affects runtime power management + +What: /sys/class/devlink/.../status +Date: May 2020 +Contact: Saravana Kannan <saravanak@google.com> +Description: + This file indicates the status of the device link. The status + of a device link is affected by whether the supplier and + consumer devices have been bound to their corresponding + drivers. The status of a device link also affects the binding + and unbinding of the supplier and consumer devices with their + drivers and also affects whether the software state of the + supplier device is synced with the hardware state of the + supplier device after boot up. + See also: sysfs-devices-state_synced. + + This will be one of the following strings: + + 'not tracked' + 'dormant' + 'available' + 'consumer probing' + 'active' + 'supplier unbinding' + 'unknown' + + 'not tracked' means this device link does not track the status + and has no impact on the binding, unbinding and syncing the + hardware and software device state. + + 'dormant' means the supplier and the consumer devices have not + bound to their driver. + + 'available' means the supplier has bound to its driver and is + available to supply resources to the consumer device. + + 'consumer probing' means the consumer device is currently + trying to bind to its driver. + + 'active' means the supplier and consumer devices have both + bound successfully to their drivers. + + 'supplier unbinding' means the supplier devices is currently in + the process of unbinding from its driver. + + 'unknown' means the state of the device link is not any of the + above. If this is ever the value, there's a bug in the kernel. + +What: /sys/class/devlink/.../supplier +Date: May 2020 +Contact: Saravana Kannan <saravanak@google.com> +Description: + This file is a symlink to the supplier device's sysfs directory. + +What: /sys/class/devlink/.../sync_state_only +Date: May 2020 +Contact: Saravana Kannan <saravanak@google.com> +Description: + This file indicates if the device link is limited to only + affecting the syncing of the hardware and software state of the + supplier device. + + This will be one of the following strings: + + '0' + '1' - Affects runtime power management + + '0' means the device link can affect other device behaviors + like binding/unbinding, suspend/resume, runtime power + management, etc. + + '1' means the device link will only affect the syncing of + hardware and software state of the supplier device after boot + up and doesn't not affect other behaviors of the devices. diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia b/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia new file mode 100644 index 000000000000..795a5de12fc1 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia @@ -0,0 +1,14 @@ +What: /sys/class/leds/<led>/device/brightness +Date: July 2020 +KernelVersion: 5.9 +Contact: Marek Behún <marek.behun@nic.cz> +Description: (RW) On the front panel of the Turris Omnia router there is also + a button which can be used to control the intensity of all the + LEDs at once, so that if they are too bright, user can dim them. + + The microcontroller cycles between 8 levels of this global + brightness (from 100% to 0%), but this setting can have any + integer value between 0 and 100. It is therefore convenient to be + able to change this setting from software. + + Format: %i diff --git a/Documentation/ABI/testing/sysfs-class-led-multicolor b/Documentation/ABI/testing/sysfs-class-led-multicolor new file mode 100644 index 000000000000..eeeddcbdbbe3 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-led-multicolor @@ -0,0 +1,35 @@ +What: /sys/class/leds/<led>/brightness +Date: March 2020 +KernelVersion: 5.9 +Contact: Dan Murphy <dmurphy@ti.com> +Description: read/write + Writing to this file will update all LEDs within the group to a + calculated percentage of what each color LED intensity is set + to. The percentage is calculated for each grouped LED via the + equation below: + + led_brightness = brightness * multi_intensity/max_brightness + + For additional details please refer to + Documentation/leds/leds-class-multicolor.rst. + + The value of the LED is from 0 to + /sys/class/leds/<led>/max_brightness. + +What: /sys/class/leds/<led>/multi_index +Date: March 2020 +KernelVersion: 5.9 +Contact: Dan Murphy <dmurphy@ti.com> +Description: read + The multi_index array, when read, will output the LED colors + as an array of strings as they are indexed in the + multi_intensity file. + +What: /sys/class/leds/<led>/multi_intensity +Date: March 2020 +KernelVersion: 5.9 +Contact: Dan Murphy <dmurphy@ti.com> +Description: read/write + This file contains array of integers. Order of components is + described by the multi_index array. The maximum intensity should + not exceed /sys/class/leds/<led>/max_brightness. diff --git a/Documentation/ABI/testing/sysfs-class-mei b/Documentation/ABI/testing/sysfs-class-mei index e9dc110650ae..5c52372b43cb 100644 --- a/Documentation/ABI/testing/sysfs-class-mei +++ b/Documentation/ABI/testing/sysfs-class-mei @@ -90,3 +90,16 @@ Description: Display trc status register content The ME FW writes Glitch Detection HW (TRC) status information into trc status register for BIOS and OS to monitor fw health. + +What: /sys/class/mei/meiN/kind +Date: Jul 2020 +KernelVersion: 5.8 +Contact: Tomas Winkler <tomas.winkler@intel.com> +Description: Display kind of the device + + Generic devices are marked as "mei" + while special purpose have their own + names. + Available options: + - mei: generic mei device. + - itouch: itouch (ipts) mei device. diff --git a/Documentation/ABI/testing/sysfs-class-ocxl b/Documentation/ABI/testing/sysfs-class-ocxl index b5b1fa197592..ae1276efa45a 100644 --- a/Documentation/ABI/testing/sysfs-class-ocxl +++ b/Documentation/ABI/testing/sysfs-class-ocxl @@ -33,3 +33,14 @@ Date: January 2018 Contact: linuxppc-dev@lists.ozlabs.org Description: read/write Give access the global mmio area for the AFU + +What: /sys/class/ocxl/<afu name>/reload_on_reset +Date: February 2020 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read/write + Control whether the FPGA is reloaded on a link reset. Enabled + through a vendor-specific logic block on the FPGA. + 0 Do not reload FPGA image from flash + 1 Reload FPGA image from flash + unavailable + The device does not support this capability diff --git a/Documentation/ABI/testing/sysfs-devices-consumer b/Documentation/ABI/testing/sysfs-devices-consumer new file mode 100644 index 000000000000..1f06d74d1c3c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-consumer @@ -0,0 +1,8 @@ +What: /sys/devices/.../consumer:<consumer> +Date: May 2020 +Contact: Saravana Kannan <saravanak@google.com> +Description: + The /sys/devices/.../consumer:<consumer> are symlinks to device + links where this device is the supplier. <consumer> denotes the + name of the consumer in that device link. There can be zero or + more of these symlinks for a given device. diff --git a/Documentation/ABI/testing/sysfs-devices-mapping b/Documentation/ABI/testing/sysfs-devices-mapping new file mode 100644 index 000000000000..490ccfd67f12 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-mapping @@ -0,0 +1,33 @@ +What: /sys/devices/uncore_iio_x/dieX +Date: February 2020 +Contact: Roman Sudarikov <roman.sudarikov@linux.intel.com> +Description: + Each IIO stack (PCIe root port) has its own IIO PMON block, so + each dieX file (where X is die number) holds "Segment:Root Bus" + for PCIe root port, which can be monitored by that IIO PMON + block. + For example, on 4-die Xeon platform with up to 6 IIO stacks per + die and, therefore, 6 IIO PMON blocks per die, the mapping of + IIO PMON block 0 exposes as the following: + + $ ls /sys/devices/uncore_iio_0/die* + -r--r--r-- /sys/devices/uncore_iio_0/die0 + -r--r--r-- /sys/devices/uncore_iio_0/die1 + -r--r--r-- /sys/devices/uncore_iio_0/die2 + -r--r--r-- /sys/devices/uncore_iio_0/die3 + + $ tail /sys/devices/uncore_iio_0/die* + ==> /sys/devices/uncore_iio_0/die0 <== + 0000:00 + ==> /sys/devices/uncore_iio_0/die1 <== + 0000:40 + ==> /sys/devices/uncore_iio_0/die2 <== + 0000:80 + ==> /sys/devices/uncore_iio_0/die3 <== + 0000:c0 + + Which means: + IIO PMU 0 on die 0 belongs to PCI RP on bus 0x00, domain 0x0000 + IIO PMU 0 on die 1 belongs to PCI RP on bus 0x40, domain 0x0000 + IIO PMU 0 on die 2 belongs to PCI RP on bus 0x80, domain 0x0000 + IIO PMU 0 on die 3 belongs to PCI RP on bus 0xc0, domain 0x0000 diff --git a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu index ae9af984471a..a8daceb4a956 100644 --- a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu +++ b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu @@ -126,3 +126,39 @@ Description: 1 no action 0 firmware record the notify code defined in b[15:0]. + +What: /sys/devices/platform/stratix10-rsu.0/dcmf0 +Date: June 2020 +KernelVersion: 5.8 +Contact: Richard Gong <richard.gong@linux.intel.com> +Description: + (RO) Decision firmware copy 0 version information. + +What: /sys/devices/platform/stratix10-rsu.0/dcmf1 +Date: June 2020 +KernelVersion: 5.8 +Contact: Richard Gong <richard.gong@linux.intel.com> +Description: + (RO) Decision firmware copy 1 version information. + +What: /sys/devices/platform/stratix10-rsu.0/dcmf2 +Date: June 2020 +KernelVersion: 5.8 +Contact: Richard Gong <richard.gong@linux.intel.com> +Description: + (RO) Decision firmware copy 2 version information. + +What: /sys/devices/platform/stratix10-rsu.0/dcmf3 +Date: June 2020 +KernelVersion: 5.8 +Contact: Richard Gong <richard.gong@linux.intel.com> +Description: + (RO) Decision firmware copy 3 version information. + +What: /sys/devices/platform/stratix10-rsu.0/max_retry +Date: June 2020 +KernelVersion: 5.8 +Contact: Richard Gong <richard.gong@linux.intel.com> +Description: + (RO) max retry parameter is stored in the firmware + decision IO section, as a byte located at offset 0x18c. diff --git a/Documentation/ABI/testing/sysfs-devices-soc b/Documentation/ABI/testing/sysfs-devices-soc index ba3a3fac0ee1..ea999e292f11 100644 --- a/Documentation/ABI/testing/sysfs-devices-soc +++ b/Documentation/ABI/testing/sysfs-devices-soc @@ -26,6 +26,30 @@ Description: Read-only attribute common to all SoCs. Contains SoC family name (e.g. DB8500). + On many of ARM based silicon with SMCCC v1.2+ compliant firmware + this will contain the JEDEC JEP106 manufacturer’s identification + code. The format is "jep106:XXYY" where XX is identity code and + YY is continuation code. + + This manufacturer’s identification code is defined by one + or more eight (8) bit fields, each consisting of seven (7) + data bits plus one (1) odd parity bit. It is a single field, + limiting the possible number of vendors to 126. To expand + the maximum number of identification codes, a continuation + scheme has been defined. + + The specified mechanism is that an identity code of 0x7F + represents the "continuation code" and implies the presence + of an additional identity code field, and this mechanism + may be extended to multiple continuation codes followed + by the manufacturer's identity code. + + For example, ARM has identity code 0x7F 0x7F 0x7F 0x7F 0x3B, + which is code 0x3B on the fifth 'page'. This is shortened + as JEP106 identity code of 0x3B and a continuation code of + 0x4 to represent the four continuation codes preceding the + identity code. + What: /sys/devices/socX/serial_number Date: January 2019 contact: Bjorn Andersson <bjorn.andersson@linaro.org> @@ -40,6 +64,12 @@ Description: Read-only attribute supported by most SoCs. In the case of ST-Ericsson's chips this contains the SoC serial number. + On many of ARM based silicon with SMCCC v1.2+ compliant firmware + this will contain the SOC ID appended to the family attribute + to ensure there is no conflict in this namespace across various + vendors. The format is "jep106:XXYY:ZZZZ" where XX is identity + code, YY is continuation code and ZZZZ is the SOC ID. + What: /sys/devices/socX/revision Date: January 2012 contact: Lee Jones <lee.jones@linaro.org> diff --git a/Documentation/ABI/testing/sysfs-devices-state_synced b/Documentation/ABI/testing/sysfs-devices-state_synced new file mode 100644 index 000000000000..0c922d7d02fc --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-state_synced @@ -0,0 +1,24 @@ +What: /sys/devices/.../state_synced +Date: May 2020 +Contact: Saravana Kannan <saravanak@google.com> +Description: + The /sys/devices/.../state_synced attribute is only present for + devices whose bus types or driver provides the .sync_state() + callback. The number read from it (0 or 1) reflects the value + of the device's 'state_synced' field. A value of 0 means the + .sync_state() callback hasn't been called yet. A value of 1 + means the .sync_state() callback has been called. + + Generally, if a device has sync_state() support and has some of + the resources it provides enabled at the time the kernel starts + (Eg: enabled by hardware reset or bootloader or anything that + run before the kernel starts), then it'll keep those resources + enabled and in a state that's compatible with the state they + were in at the start of the kernel. The device will stop doing + this only when the sync_state() callback has been called -- + which happens only when all its consumer devices are registered + and have probed successfully. Resources that were left disabled + at the time the kernel starts are not affected or limited in + any way by sync_state() callbacks. + + diff --git a/Documentation/ABI/testing/sysfs-devices-supplier b/Documentation/ABI/testing/sysfs-devices-supplier new file mode 100644 index 000000000000..a919e0db5e90 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-supplier @@ -0,0 +1,8 @@ +What: /sys/devices/.../supplier:<supplier> +Date: May 2020 +Contact: Saravana Kannan <saravanak@google.com> +Description: + The /sys/devices/.../supplier:<supplier> are symlinks to device + links where this device is the consumer. <supplier> denotes the + name of the supplier in that device link. There can be zero or + more of these symlinks for a given device. diff --git a/Documentation/ABI/testing/sysfs-devices-waiting_for_supplier b/Documentation/ABI/testing/sysfs-devices-waiting_for_supplier new file mode 100644 index 000000000000..59d073d20db6 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-waiting_for_supplier @@ -0,0 +1,17 @@ +What: /sys/devices/.../waiting_for_supplier +Date: May 2020 +Contact: Saravana Kannan <saravanak@google.com> +Description: + The /sys/devices/.../waiting_for_supplier attribute is only + present when fw_devlink kernel command line option is enabled + and is set to something stricter than "permissive". It is + removed once a device probes successfully (because the + information is no longer relevant). The number read from it (0 + or 1) reflects whether the device is waiting for one or more + suppliers to be added and then linked to using device links + before the device can probe. + + A value of 0 means the device is not waiting for any suppliers + to be added before it can probe. A value of 1 means the device + is waiting for one or more suppliers to be added before it can + probe. diff --git a/Documentation/ABI/testing/sysfs-driver-ufs b/Documentation/ABI/testing/sysfs-driver-ufs index 016724ec26d5..d1a352194d2e 100644 --- a/Documentation/ABI/testing/sysfs-driver-ufs +++ b/Documentation/ABI/testing/sysfs-driver-ufs @@ -883,3 +883,139 @@ Contact: Subhash Jadavani <subhashj@codeaurora.org> Description: This entry shows the target state of an UFS UIC link for the chosen system power management level. The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_presv_us_en +Date: June 2020 +Contact: Asutosh Das <asutoshd@codeaurora.org> +Description: This entry shows if preserve user-space was configured + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_shared_alloc_units +Date: June 2020 +Contact: Asutosh Das <asutoshd@codeaurora.org> +Description: This entry shows the shared allocated units of WB buffer + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_type +Date: June 2020 +Contact: Asutosh Das <asutoshd@codeaurora.org> +Description: This entry shows the configured WB type. + 0x1 for shared buffer mode. 0x0 for dedicated buffer mode. + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_buff_cap_adj +Date: June 2020 +Contact: Asutosh Das <asutoshd@codeaurora.org> +Description: This entry shows the total user-space decrease in shared + buffer mode. + The value of this parameter is 3 for TLC NAND when SLC mode + is used as WriteBooster Buffer. 2 for MLC NAND. + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_max_alloc_units +Date: June 2020 +Contact: Asutosh Das <asutoshd@codeaurora.org> +Description: This entry shows the Maximum total WriteBooster Buffer size + which is supported by the entire device. + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_max_wb_luns +Date: June 2020 +Contact: Asutosh Das <asutoshd@codeaurora.org> +Description: This entry shows the maximum number of luns that can support + WriteBooster. + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_sup_red_type +Date: June 2020 +Contact: Asutosh Das <asutoshd@codeaurora.org> +Description: The supportability of user space reduction mode + and preserve user space mode. + 00h: WriteBooster Buffer can be configured only in + user space reduction type. + 01h: WriteBooster Buffer can be configured only in + preserve user space type. + 02h: Device can be configured in either user space + reduction type or preserve user space type. + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_sup_wb_type +Date: June 2020 +Contact: Asutosh Das <asutoshd@codeaurora.org> +Description: The supportability of WriteBooster Buffer type. + 00h: LU based WriteBooster Buffer configuration + 01h: Single shared WriteBooster Buffer + configuration + 02h: Supporting both LU based WriteBooster + Buffer and Single shared WriteBooster Buffer + configuration + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/flags/wb_enable +Date: June 2020 +Contact: Asutosh Das <asutoshd@codeaurora.org> +Description: This entry shows the status of WriteBooster. + 0: WriteBooster is not enabled. + 1: WriteBooster is enabled + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/flags/wb_flush_en +Date: June 2020 +Contact: Asutosh Das <asutoshd@codeaurora.org> +Description: This entry shows if flush is enabled. + 0: Flush operation is not performed. + 1: Flush operation is performed. + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/flags/wb_flush_during_h8 +Date: June 2020 +Contact: Asutosh Das <asutoshd@codeaurora.org> +Description: Flush WriteBooster Buffer during hibernate state. + 0: Device is not allowed to flush the + WriteBooster Buffer during link hibernate + state. + 1: Device is allowed to flush the + WriteBooster Buffer during link hibernate + state + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_avail_buf +Date: June 2020 +Contact: Asutosh Das <asutoshd@codeaurora.org> +Description: This entry shows the amount of unused WriteBooster buffer + available. + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_cur_buf +Date: June 2020 +Contact: Asutosh Das <asutoshd@codeaurora.org> +Description: This entry shows the amount of unused current buffer. + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_flush_status +Date: June 2020 +Contact: Asutosh Das <asutoshd@codeaurora.org> +Description: This entry shows the flush operation status. + 00h: idle + 01h: Flush operation in progress + 02h: Flush operation stopped prematurely. + 03h: Flush operation completed successfully + 04h: Flush operation general failure + The file is read only. + +What: /sys/bus/platform/drivers/ufshcd/*/attributes/wb_life_time_est +Date: June 2020 +Contact: Asutosh Das <asutoshd@codeaurora.org> +Description: This entry shows an indication of the WriteBooster Buffer + lifetime based on the amount of performed program/erase cycles + 01h: 0% - 10% WriteBooster Buffer life time used + ... + 0Ah: 90% - 100% WriteBooster Buffer life time used + The file is read only. + +What: /sys/class/scsi_device/*/device/unit_descriptor/wb_buf_alloc_units +Date: June 2020 +Contact: Asutosh Das <asutoshd@codeaurora.org> +Description: This entry shows the configured size of WriteBooster buffer. + 0400h corresponds to 4GB. + The file is read only. diff --git a/Documentation/ABI/testing/sysfs-driver-w1_therm b/Documentation/ABI/testing/sysfs-driver-w1_therm index 076659d506f2..9b488c0afdfa 100644 --- a/Documentation/ABI/testing/sysfs-driver-w1_therm +++ b/Documentation/ABI/testing/sysfs-driver-w1_therm @@ -8,7 +8,7 @@ Description: to device min/max capabilities. Values are integer as they are stored in a 8bit register in the device. Lowest value is automatically put to TL. Once set, alarms could be search at - master level, refer to Documentation/w1/w1_generic.rst for + master level, refer to Documentation/w1/w1-generic.rst for detailed information Users: any user space application which wants to communicate with w1_term device diff --git a/Documentation/ABI/testing/sysfs-platform-chipidea-usb-otg b/Documentation/ABI/testing/sysfs-platform-chipidea-usb-otg index 151c59578db4..f58cfb06b160 100644 --- a/Documentation/ABI/testing/sysfs-platform-chipidea-usb-otg +++ b/Documentation/ABI/testing/sysfs-platform-chipidea-usb-otg @@ -1,6 +1,6 @@ What: /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req Date: Feb 2014 -Contact: Li Jun <b47624@freescale.com> +Contact: Li Jun <jun.li@nxp.com> Description: Can be set and read. Set a_bus_req(A-device bus request) input to be 1 if @@ -17,7 +17,7 @@ Description: What: /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop Date: Feb 2014 -Contact: Li Jun <b47624@freescale.com> +Contact: Li Jun <jun.li@nxp.com> Description: Can be set and read The a_bus_drop(A-device bus drop) input is 1 when the @@ -32,7 +32,7 @@ Description: What: /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req Date: Feb 2014 -Contact: Li Jun <b47624@freescale.com> +Contact: Li Jun <jun.li@nxp.com> Description: Can be set and read. The b_bus_req(B-device bus request) input is 1 during the time @@ -47,7 +47,7 @@ Description: What: /sys/bus/platform/devices/ci_hdrc.0/inputs/a_clr_err Date: Feb 2014 -Contact: Li Jun <b47624@freescale.com> +Contact: Li Jun <jun.li@nxp.com> Description: Only can be set. The a_clr_err(A-device Vbus error clear) input is used to clear diff --git a/Documentation/PCI/endpoint/function/binding/pci-test.rst b/Documentation/PCI/endpoint/function/binding/pci-test.rst new file mode 100644 index 000000000000..57ee866fb165 --- /dev/null +++ b/Documentation/PCI/endpoint/function/binding/pci-test.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================== +PCI Test Endpoint Function +========================== + +name: Should be "pci_epf_test" to bind to the pci_epf_test driver. + +Configurable Fields: + +================ =========================================================== +vendorid should be 0x104c +deviceid should be 0xb500 for DRA74x and 0xb501 for DRA72x +revid don't care +progif_code don't care +subclass_code don't care +baseclass_code should be 0xff +cache_line_size don't care +subsys_vendor_id don't care +subsys_id don't care +interrupt_pin Should be 1 - INTA, 2 - INTB, 3 - INTC, 4 -INTD +msi_interrupts Should be 1 to 32 depending on the number of MSI interrupts + to test +msix_interrupts Should be 1 to 2048 depending on the number of MSI-X + interrupts to test +================ =========================================================== diff --git a/Documentation/PCI/endpoint/function/binding/pci-test.txt b/Documentation/PCI/endpoint/function/binding/pci-test.txt deleted file mode 100644 index cd76ba47394b..000000000000 --- a/Documentation/PCI/endpoint/function/binding/pci-test.txt +++ /dev/null @@ -1,19 +0,0 @@ -PCI TEST ENDPOINT FUNCTION - -name: Should be "pci_epf_test" to bind to the pci_epf_test driver. - -Configurable Fields: -vendorid : should be 0x104c -deviceid : should be 0xb500 for DRA74x and 0xb501 for DRA72x -revid : don't care -progif_code : don't care -subclass_code : don't care -baseclass_code : should be 0xff -cache_line_size : don't care -subsys_vendor_id : don't care -subsys_id : don't care -interrupt_pin : Should be 1 - INTA, 2 - INTB, 3 - INTC, 4 -INTD -msi_interrupts : Should be 1 to 32 depending on the number of MSI interrupts - to test -msix_interrupts : Should be 1 to 2048 depending on the number of MSI-X - interrupts to test diff --git a/Documentation/PCI/endpoint/index.rst b/Documentation/PCI/endpoint/index.rst index d114ea74b444..4ca7439fbfc9 100644 --- a/Documentation/PCI/endpoint/index.rst +++ b/Documentation/PCI/endpoint/index.rst @@ -11,3 +11,5 @@ PCI Endpoint Framework pci-endpoint-cfs pci-test-function pci-test-howto + + function/binding/pci-test diff --git a/Documentation/PCI/endpoint/pci-endpoint-cfs.rst b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst index b6d39cdec56e..1bbd81ed06c8 100644 --- a/Documentation/PCI/endpoint/pci-endpoint-cfs.rst +++ b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst @@ -24,7 +24,7 @@ Directory Structure The pci_ep configfs has two directories at its root: controllers and functions. Every EPC device present in the system will have an entry in -the *controllers* directory and and every EPF driver present in the system +the *controllers* directory and every EPF driver present in the system will have an entry in the *functions* directory. :: diff --git a/Documentation/PCI/endpoint/pci-endpoint.rst b/Documentation/PCI/endpoint/pci-endpoint.rst index 7536be445db8..4f5622a65555 100644 --- a/Documentation/PCI/endpoint/pci-endpoint.rst +++ b/Documentation/PCI/endpoint/pci-endpoint.rst @@ -214,7 +214,7 @@ pci-ep-cfs.c can be used as reference for using these APIs. * pci_epf_create() Create a new PCI EPF device by passing the name of the PCI EPF device. - This name will be used to bind the the EPF device to a EPF driver. + This name will be used to bind the EPF device to a EPF driver. * pci_epf_destroy() diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst index ccd713423133..84ceebb08cac 100644 --- a/Documentation/PCI/pci-error-recovery.rst +++ b/Documentation/PCI/pci-error-recovery.rst @@ -248,7 +248,7 @@ STEP 4: Slot Reset ------------------ In response to a return value of PCI_ERS_RESULT_NEED_RESET, the -the platform will perform a slot reset on the requesting PCI device(s). +platform will perform a slot reset on the requesting PCI device(s). The actual steps taken by a platform to perform a slot reset will be platform-dependent. Upon completion of slot reset, the platform will call the device slot_reset() callback. diff --git a/Documentation/PCI/pci.rst b/Documentation/PCI/pci.rst index 281d8a241eae..814b40f8360b 100644 --- a/Documentation/PCI/pci.rst +++ b/Documentation/PCI/pci.rst @@ -209,7 +209,7 @@ the PCI device by calling pci_enable_device(). This will: OS BUG: we don't check resource allocations before enabling those resources. The sequence would make more sense if we called pci_request_resources() before calling pci_enable_device(). - Currently, the device drivers can't detect the bug when when two + Currently, the device drivers can't detect the bug when two devices have been allocated the same range. This is not a common problem and unlikely to get fixed soon. @@ -265,7 +265,7 @@ Set the DMA mask size --------------------- .. note:: If anything below doesn't make sense, please refer to - Documentation/DMA-API.txt. This section is just a reminder that + :doc:`/core-api/dma-api`. This section is just a reminder that drivers need to indicate DMA capabilities of the device and is not an authoritative source for DMA interfaces. @@ -291,7 +291,7 @@ Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are Setup shared control data ------------------------- Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared) -memory. See Documentation/DMA-API.txt for a full description of +memory. See :doc:`/core-api/dma-api` for a full description of the DMA APIs. This section is just a reminder that it needs to be done before enabling DMA on the device. @@ -421,7 +421,7 @@ owners if there is one. Then clean up "consistent" buffers which contain the control data. -See Documentation/DMA-API.txt for details on unmapping interfaces. +See :doc:`/core-api/dma-api` for details on unmapping interfaces. Unregister from other subsystems diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst index 75b8ca007a11..8f41ad0aa753 100644 --- a/Documentation/RCU/Design/Requirements/Requirements.rst +++ b/Documentation/RCU/Design/Requirements/Requirements.rst @@ -463,7 +463,7 @@ again without disrupting RCU readers. This guarantee was only partially premeditated. DYNIX/ptx used an explicit memory barrier for publication, but had nothing resembling ``rcu_dereference()`` for subscription, nor did it have anything -resembling the ``smp_read_barrier_depends()`` that was later subsumed +resembling the dependency-ordering barrier that was later subsumed into ``rcu_dereference()`` and later still into ``READ_ONCE()``. The need for these operations made itself known quite suddenly at a late-1990s meeting with the DEC Alpha architects, back in the days when @@ -2583,7 +2583,12 @@ not work to have these markers in the trampoline itself, because there would need to be instructions following ``rcu_read_unlock()``. Although ``synchronize_rcu()`` would guarantee that execution reached the ``rcu_read_unlock()``, it would not be able to guarantee that execution -had completely left the trampoline. +had completely left the trampoline. Worse yet, in some situations +the trampoline's protection must extend a few instructions *prior* to +execution reaching the trampoline. For example, these few instructions +might calculate the address of the trampoline, so that entering the +trampoline would be pre-ordained a surprisingly long time before execution +actually reached the trampoline itself. The solution, in the form of `Tasks RCU <https://lwn.net/Articles/607117/>`__, is to have implicit read-side diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.rst index e98ff261a438..2efed9926c3f 100644 --- a/Documentation/RCU/checklist.txt +++ b/Documentation/RCU/checklist.rst @@ -1,4 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================ Review Checklist for RCU Patches +================================ This document contains a checklist for producing and reviewing patches @@ -411,18 +415,21 @@ over a rather long period of time, but improvements are always welcome! __rcu sparse checks to validate your RCU code. These can help find problems as follows: - CONFIG_PROVE_LOCKING: check that accesses to RCU-protected data + CONFIG_PROVE_LOCKING: + check that accesses to RCU-protected data structures are carried out under the proper RCU read-side critical section, while holding the right combination of locks, or whatever other conditions are appropriate. - CONFIG_DEBUG_OBJECTS_RCU_HEAD: check that you don't pass the + CONFIG_DEBUG_OBJECTS_RCU_HEAD: + check that you don't pass the same object to call_rcu() (or friends) before an RCU grace period has elapsed since the last time that you passed that same object to call_rcu() (or friends). - __rcu sparse checks: tag the pointer to the RCU-protected data + __rcu sparse checks: + tag the pointer to the RCU-protected data structure with __rcu, and sparse will warn you if you access that pointer without the services of one of the variants of rcu_dereference(). @@ -442,8 +449,8 @@ over a rather long period of time, but improvements are always welcome! You instead need to use one of the barrier functions: - o call_rcu() -> rcu_barrier() - o call_srcu() -> srcu_barrier() + - call_rcu() -> rcu_barrier() + - call_srcu() -> srcu_barrier() However, these barrier functions are absolutely -not- guaranteed to wait for a grace period. In fact, if there are no call_rcu() diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst index 81a0a1e5f767..e703d3dbe60c 100644 --- a/Documentation/RCU/index.rst +++ b/Documentation/RCU/index.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. _rcu_concepts: ============ @@ -8,10 +10,17 @@ RCU concepts :maxdepth: 3 arrayRCU + checklist + lockdep + lockdep-splat rcubarrier rcu_dereference whatisRCU rcu + rculist_nulls + rcuref + torture + stallwarn listRCU NMI-RCU UP diff --git a/Documentation/RCU/lockdep-splat.txt b/Documentation/RCU/lockdep-splat.rst index b8096316fd11..2a5c79db57dc 100644 --- a/Documentation/RCU/lockdep-splat.txt +++ b/Documentation/RCU/lockdep-splat.rst @@ -1,3 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================= +Lockdep-RCU Splat +================= + Lockdep-RCU was added to the Linux kernel in early 2010 (http://lwn.net/Articles/371986/). This facility checks for some common misuses of the RCU API, most notably using one of the rcu_dereference() @@ -12,55 +18,54 @@ overwriting or worse. There can of course be false positives, this being the real world and all that. So let's look at an example RCU lockdep splat from 3.0-rc5, one that -has long since been fixed: - -============================= -WARNING: suspicious RCU usage ------------------------------ -block/cfq-iosched.c:2776 suspicious rcu_dereference_protected() usage! - -other info that might help us debug this: - - -rcu_scheduler_active = 1, debug_locks = 0 -3 locks held by scsi_scan_6/1552: - #0: (&shost->scan_mutex){+.+.}, at: [<ffffffff8145efca>] -scsi_scan_host_selected+0x5a/0x150 - #1: (&eq->sysfs_lock){+.+.}, at: [<ffffffff812a5032>] -elevator_exit+0x22/0x60 - #2: (&(&q->__queue_lock)->rlock){-.-.}, at: [<ffffffff812b6233>] -cfq_exit_queue+0x43/0x190 - -stack backtrace: -Pid: 1552, comm: scsi_scan_6 Not tainted 3.0.0-rc5 #17 -Call Trace: - [<ffffffff810abb9b>] lockdep_rcu_dereference+0xbb/0xc0 - [<ffffffff812b6139>] __cfq_exit_single_io_context+0xe9/0x120 - [<ffffffff812b626c>] cfq_exit_queue+0x7c/0x190 - [<ffffffff812a5046>] elevator_exit+0x36/0x60 - [<ffffffff812a802a>] blk_cleanup_queue+0x4a/0x60 - [<ffffffff8145cc09>] scsi_free_queue+0x9/0x10 - [<ffffffff81460944>] __scsi_remove_device+0x84/0xd0 - [<ffffffff8145dca3>] scsi_probe_and_add_lun+0x353/0xb10 - [<ffffffff817da069>] ? error_exit+0x29/0xb0 - [<ffffffff817d98ed>] ? _raw_spin_unlock_irqrestore+0x3d/0x80 - [<ffffffff8145e722>] __scsi_scan_target+0x112/0x680 - [<ffffffff812c690d>] ? trace_hardirqs_off_thunk+0x3a/0x3c - [<ffffffff817da069>] ? error_exit+0x29/0xb0 - [<ffffffff812bcc60>] ? kobject_del+0x40/0x40 - [<ffffffff8145ed16>] scsi_scan_channel+0x86/0xb0 - [<ffffffff8145f0b0>] scsi_scan_host_selected+0x140/0x150 - [<ffffffff8145f149>] do_scsi_scan_host+0x89/0x90 - [<ffffffff8145f170>] do_scan_async+0x20/0x160 - [<ffffffff8145f150>] ? do_scsi_scan_host+0x90/0x90 - [<ffffffff810975b6>] kthread+0xa6/0xb0 - [<ffffffff817db154>] kernel_thread_helper+0x4/0x10 - [<ffffffff81066430>] ? finish_task_switch+0x80/0x110 - [<ffffffff817d9c04>] ? retint_restore_args+0xe/0xe - [<ffffffff81097510>] ? __kthread_init_worker+0x70/0x70 - [<ffffffff817db150>] ? gs_change+0xb/0xb - -Line 2776 of block/cfq-iosched.c in v3.0-rc5 is as follows: +has long since been fixed:: + + ============================= + WARNING: suspicious RCU usage + ----------------------------- + block/cfq-iosched.c:2776 suspicious rcu_dereference_protected() usage! + +other info that might help us debug this:: + + rcu_scheduler_active = 1, debug_locks = 0 + 3 locks held by scsi_scan_6/1552: + #0: (&shost->scan_mutex){+.+.}, at: [<ffffffff8145efca>] + scsi_scan_host_selected+0x5a/0x150 + #1: (&eq->sysfs_lock){+.+.}, at: [<ffffffff812a5032>] + elevator_exit+0x22/0x60 + #2: (&(&q->__queue_lock)->rlock){-.-.}, at: [<ffffffff812b6233>] + cfq_exit_queue+0x43/0x190 + + stack backtrace: + Pid: 1552, comm: scsi_scan_6 Not tainted 3.0.0-rc5 #17 + Call Trace: + [<ffffffff810abb9b>] lockdep_rcu_dereference+0xbb/0xc0 + [<ffffffff812b6139>] __cfq_exit_single_io_context+0xe9/0x120 + [<ffffffff812b626c>] cfq_exit_queue+0x7c/0x190 + [<ffffffff812a5046>] elevator_exit+0x36/0x60 + [<ffffffff812a802a>] blk_cleanup_queue+0x4a/0x60 + [<ffffffff8145cc09>] scsi_free_queue+0x9/0x10 + [<ffffffff81460944>] __scsi_remove_device+0x84/0xd0 + [<ffffffff8145dca3>] scsi_probe_and_add_lun+0x353/0xb10 + [<ffffffff817da069>] ? error_exit+0x29/0xb0 + [<ffffffff817d98ed>] ? _raw_spin_unlock_irqrestore+0x3d/0x80 + [<ffffffff8145e722>] __scsi_scan_target+0x112/0x680 + [<ffffffff812c690d>] ? trace_hardirqs_off_thunk+0x3a/0x3c + [<ffffffff817da069>] ? error_exit+0x29/0xb0 + [<ffffffff812bcc60>] ? kobject_del+0x40/0x40 + [<ffffffff8145ed16>] scsi_scan_channel+0x86/0xb0 + [<ffffffff8145f0b0>] scsi_scan_host_selected+0x140/0x150 + [<ffffffff8145f149>] do_scsi_scan_host+0x89/0x90 + [<ffffffff8145f170>] do_scan_async+0x20/0x160 + [<ffffffff8145f150>] ? do_scsi_scan_host+0x90/0x90 + [<ffffffff810975b6>] kthread+0xa6/0xb0 + [<ffffffff817db154>] kernel_thread_helper+0x4/0x10 + [<ffffffff81066430>] ? finish_task_switch+0x80/0x110 + [<ffffffff817d9c04>] ? retint_restore_args+0xe/0xe + [<ffffffff81097510>] ? __kthread_init_worker+0x70/0x70 + [<ffffffff817db150>] ? gs_change+0xb/0xb + +Line 2776 of block/cfq-iosched.c in v3.0-rc5 is as follows:: if (rcu_dereference(ioc->ioc_data) == cic) { @@ -70,7 +75,7 @@ case. Instead, we hold three locks, one of which might be RCU related. And maybe that lock really does protect this reference. If so, the fix is to inform RCU, perhaps by changing __cfq_exit_single_io_context() to take the struct request_queue "q" from cfq_exit_queue() as an argument, -which would permit us to invoke rcu_dereference_protected as follows: +which would permit us to invoke rcu_dereference_protected as follows:: if (rcu_dereference_protected(ioc->ioc_data, lockdep_is_held(&q->queue_lock)) == cic) { @@ -85,7 +90,7 @@ On the other hand, perhaps we really do need an RCU read-side critical section. In this case, the critical section must span the use of the return value from rcu_dereference(), or at least until there is some reference count incremented or some such. One way to handle this is to -add rcu_read_lock() and rcu_read_unlock() as follows: +add rcu_read_lock() and rcu_read_unlock() as follows:: rcu_read_lock(); if (rcu_dereference(ioc->ioc_data) == cic) { @@ -102,7 +107,7 @@ above lockdep-RCU splat. But in this particular case, we don't actually dereference the pointer returned from rcu_dereference(). Instead, that pointer is just compared to the cic pointer, which means that the rcu_dereference() can be replaced -by rcu_access_pointer() as follows: +by rcu_access_pointer() as follows:: if (rcu_access_pointer(ioc->ioc_data) == cic) { diff --git a/Documentation/RCU/lockdep.txt b/Documentation/RCU/lockdep.rst index 89db949eeca0..f1fc8ae3846a 100644 --- a/Documentation/RCU/lockdep.txt +++ b/Documentation/RCU/lockdep.rst @@ -1,4 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================== RCU and lockdep checking +======================== All flavors of RCU have lockdep checking available, so that lockdep is aware of when each task enters and leaves any flavor of RCU read-side @@ -8,7 +12,7 @@ tracking to include RCU state, which can sometimes help when debugging deadlocks and the like. In addition, RCU provides the following primitives that check lockdep's -state: +state:: rcu_read_lock_held() for normal RCU. rcu_read_lock_bh_held() for RCU-bh. @@ -63,7 +67,7 @@ checking of rcu_dereference() primitives: The rcu_dereference_check() check expression can be any boolean expression, but would normally include a lockdep expression. However, any boolean expression can be used. For a moderately ornate example, -consider the following: +consider the following:: file = rcu_dereference_check(fdt->fd[fd], lockdep_is_held(&files->file_lock) || @@ -82,7 +86,7 @@ RCU read-side critical sections, in case (2) the ->file_lock prevents any change from taking place, and finally, in case (3) the current task is the only task accessing the file_struct, again preventing any change from taking place. If the above statement was invoked only from updater -code, it could instead be written as follows: +code, it could instead be written as follows:: file = rcu_dereference_protected(fdt->fd[fd], lockdep_is_held(&files->file_lock) || @@ -105,7 +109,7 @@ false and they are called from outside any RCU read-side critical section. For example, the workqueue for_each_pwq() macro is intended to be used either within an RCU read-side critical section or with wq->mutex held. -It is thus implemented as follows: +It is thus implemented as follows:: #define for_each_pwq(pwq, wq) list_for_each_entry_rcu((pwq), &(wq)->pwqs, pwqs_node, diff --git a/Documentation/RCU/rculist_nulls.rst b/Documentation/RCU/rculist_nulls.rst new file mode 100644 index 000000000000..a9fc774bc400 --- /dev/null +++ b/Documentation/RCU/rculist_nulls.rst @@ -0,0 +1,200 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================================= +Using RCU hlist_nulls to protect list and objects +================================================= + +This section describes how to use hlist_nulls to +protect read-mostly linked lists and +objects using SLAB_TYPESAFE_BY_RCU allocations. + +Please read the basics in Documentation/RCU/listRCU.rst + +Using 'nulls' +============= + +Using special makers (called 'nulls') is a convenient way +to solve following problem : + +A typical RCU linked list managing objects which are +allocated with SLAB_TYPESAFE_BY_RCU kmem_cache can +use following algos : + +1) Lookup algo +-------------- + +:: + + rcu_read_lock() + begin: + obj = lockless_lookup(key); + if (obj) { + if (!try_get_ref(obj)) // might fail for free objects + goto begin; + /* + * Because a writer could delete object, and a writer could + * reuse these object before the RCU grace period, we + * must check key after getting the reference on object + */ + if (obj->key != key) { // not the object we expected + put_ref(obj); + goto begin; + } + } + rcu_read_unlock(); + +Beware that lockless_lookup(key) cannot use traditional hlist_for_each_entry_rcu() +but a version with an additional memory barrier (smp_rmb()) + +:: + + lockless_lookup(key) + { + struct hlist_node *node, *next; + for (pos = rcu_dereference((head)->first); + pos && ({ next = pos->next; smp_rmb(); prefetch(next); 1; }) && + ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; }); + pos = rcu_dereference(next)) + if (obj->key == key) + return obj; + return NULL; + } + +And note the traditional hlist_for_each_entry_rcu() misses this smp_rmb():: + + struct hlist_node *node; + for (pos = rcu_dereference((head)->first); + pos && ({ prefetch(pos->next); 1; }) && + ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; }); + pos = rcu_dereference(pos->next)) + if (obj->key == key) + return obj; + return NULL; + +Quoting Corey Minyard:: + + "If the object is moved from one list to another list in-between the + time the hash is calculated and the next field is accessed, and the + object has moved to the end of a new list, the traversal will not + complete properly on the list it should have, since the object will + be on the end of the new list and there's not a way to tell it's on a + new list and restart the list traversal. I think that this can be + solved by pre-fetching the "next" field (with proper barriers) before + checking the key." + +2) Insert algo +-------------- + +We need to make sure a reader cannot read the new 'obj->obj_next' value +and previous value of 'obj->key'. Or else, an item could be deleted +from a chain, and inserted into another chain. If new chain was empty +before the move, 'next' pointer is NULL, and lockless reader can +not detect it missed following items in original chain. + +:: + + /* + * Please note that new inserts are done at the head of list, + * not in the middle or end. + */ + obj = kmem_cache_alloc(...); + lock_chain(); // typically a spin_lock() + obj->key = key; + /* + * we need to make sure obj->key is updated before obj->next + * or obj->refcnt + */ + smp_wmb(); + atomic_set(&obj->refcnt, 1); + hlist_add_head_rcu(&obj->obj_node, list); + unlock_chain(); // typically a spin_unlock() + + +3) Remove algo +-------------- +Nothing special here, we can use a standard RCU hlist deletion. +But thanks to SLAB_TYPESAFE_BY_RCU, beware a deleted object can be reused +very very fast (before the end of RCU grace period) + +:: + + if (put_last_reference_on(obj) { + lock_chain(); // typically a spin_lock() + hlist_del_init_rcu(&obj->obj_node); + unlock_chain(); // typically a spin_unlock() + kmem_cache_free(cachep, obj); + } + + + +-------------------------------------------------------------------------- + +Avoiding extra smp_rmb() +======================== + +With hlist_nulls we can avoid extra smp_rmb() in lockless_lookup() +and extra smp_wmb() in insert function. + +For example, if we choose to store the slot number as the 'nulls' +end-of-list marker for each slot of the hash table, we can detect +a race (some writer did a delete and/or a move of an object +to another chain) checking the final 'nulls' value if +the lookup met the end of chain. If final 'nulls' value +is not the slot number, then we must restart the lookup at +the beginning. If the object was moved to the same chain, +then the reader doesn't care : It might eventually +scan the list again without harm. + + +1) lookup algo +-------------- + +:: + + head = &table[slot]; + rcu_read_lock(); + begin: + hlist_nulls_for_each_entry_rcu(obj, node, head, member) { + if (obj->key == key) { + if (!try_get_ref(obj)) // might fail for free objects + goto begin; + if (obj->key != key) { // not the object we expected + put_ref(obj); + goto begin; + } + goto out; + } + /* + * if the nulls value we got at the end of this lookup is + * not the expected one, we must restart lookup. + * We probably met an item that was moved to another chain. + */ + if (get_nulls_value(node) != slot) + goto begin; + obj = NULL; + + out: + rcu_read_unlock(); + +2) Insert function +------------------ + +:: + + /* + * Please note that new inserts are done at the head of list, + * not in the middle or end. + */ + obj = kmem_cache_alloc(cachep); + lock_chain(); // typically a spin_lock() + obj->key = key; + /* + * changes to obj->key must be visible before refcnt one + */ + smp_wmb(); + atomic_set(&obj->refcnt, 1); + /* + * insert obj in RCU way (readers might be traversing chain) + */ + hlist_nulls_add_head_rcu(&obj->obj_node, list); + unlock_chain(); // typically a spin_unlock() diff --git a/Documentation/RCU/rculist_nulls.txt b/Documentation/RCU/rculist_nulls.txt deleted file mode 100644 index 23f115dc87cf..000000000000 --- a/Documentation/RCU/rculist_nulls.txt +++ /dev/null @@ -1,172 +0,0 @@ -Using hlist_nulls to protect read-mostly linked lists and -objects using SLAB_TYPESAFE_BY_RCU allocations. - -Please read the basics in Documentation/RCU/listRCU.rst - -Using special makers (called 'nulls') is a convenient way -to solve following problem : - -A typical RCU linked list managing objects which are -allocated with SLAB_TYPESAFE_BY_RCU kmem_cache can -use following algos : - -1) Lookup algo --------------- -rcu_read_lock() -begin: -obj = lockless_lookup(key); -if (obj) { - if (!try_get_ref(obj)) // might fail for free objects - goto begin; - /* - * Because a writer could delete object, and a writer could - * reuse these object before the RCU grace period, we - * must check key after getting the reference on object - */ - if (obj->key != key) { // not the object we expected - put_ref(obj); - goto begin; - } -} -rcu_read_unlock(); - -Beware that lockless_lookup(key) cannot use traditional hlist_for_each_entry_rcu() -but a version with an additional memory barrier (smp_rmb()) - -lockless_lookup(key) -{ - struct hlist_node *node, *next; - for (pos = rcu_dereference((head)->first); - pos && ({ next = pos->next; smp_rmb(); prefetch(next); 1; }) && - ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; }); - pos = rcu_dereference(next)) - if (obj->key == key) - return obj; - return NULL; - -And note the traditional hlist_for_each_entry_rcu() misses this smp_rmb() : - - struct hlist_node *node; - for (pos = rcu_dereference((head)->first); - pos && ({ prefetch(pos->next); 1; }) && - ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; }); - pos = rcu_dereference(pos->next)) - if (obj->key == key) - return obj; - return NULL; -} - -Quoting Corey Minyard : - -"If the object is moved from one list to another list in-between the - time the hash is calculated and the next field is accessed, and the - object has moved to the end of a new list, the traversal will not - complete properly on the list it should have, since the object will - be on the end of the new list and there's not a way to tell it's on a - new list and restart the list traversal. I think that this can be - solved by pre-fetching the "next" field (with proper barriers) before - checking the key." - -2) Insert algo : ----------------- - -We need to make sure a reader cannot read the new 'obj->obj_next' value -and previous value of 'obj->key'. Or else, an item could be deleted -from a chain, and inserted into another chain. If new chain was empty -before the move, 'next' pointer is NULL, and lockless reader can -not detect it missed following items in original chain. - -/* - * Please note that new inserts are done at the head of list, - * not in the middle or end. - */ -obj = kmem_cache_alloc(...); -lock_chain(); // typically a spin_lock() -obj->key = key; -/* - * we need to make sure obj->key is updated before obj->next - * or obj->refcnt - */ -smp_wmb(); -atomic_set(&obj->refcnt, 1); -hlist_add_head_rcu(&obj->obj_node, list); -unlock_chain(); // typically a spin_unlock() - - -3) Remove algo --------------- -Nothing special here, we can use a standard RCU hlist deletion. -But thanks to SLAB_TYPESAFE_BY_RCU, beware a deleted object can be reused -very very fast (before the end of RCU grace period) - -if (put_last_reference_on(obj) { - lock_chain(); // typically a spin_lock() - hlist_del_init_rcu(&obj->obj_node); - unlock_chain(); // typically a spin_unlock() - kmem_cache_free(cachep, obj); -} - - - --------------------------------------------------------------------------- -With hlist_nulls we can avoid extra smp_rmb() in lockless_lookup() -and extra smp_wmb() in insert function. - -For example, if we choose to store the slot number as the 'nulls' -end-of-list marker for each slot of the hash table, we can detect -a race (some writer did a delete and/or a move of an object -to another chain) checking the final 'nulls' value if -the lookup met the end of chain. If final 'nulls' value -is not the slot number, then we must restart the lookup at -the beginning. If the object was moved to the same chain, -then the reader doesn't care : It might eventually -scan the list again without harm. - - -1) lookup algo - - head = &table[slot]; - rcu_read_lock(); -begin: - hlist_nulls_for_each_entry_rcu(obj, node, head, member) { - if (obj->key == key) { - if (!try_get_ref(obj)) // might fail for free objects - goto begin; - if (obj->key != key) { // not the object we expected - put_ref(obj); - goto begin; - } - goto out; - } -/* - * if the nulls value we got at the end of this lookup is - * not the expected one, we must restart lookup. - * We probably met an item that was moved to another chain. - */ - if (get_nulls_value(node) != slot) - goto begin; - obj = NULL; - -out: - rcu_read_unlock(); - -2) Insert function : --------------------- - -/* - * Please note that new inserts are done at the head of list, - * not in the middle or end. - */ -obj = kmem_cache_alloc(cachep); -lock_chain(); // typically a spin_lock() -obj->key = key; -/* - * changes to obj->key must be visible before refcnt one - */ -smp_wmb(); -atomic_set(&obj->refcnt, 1); -/* - * insert obj in RCU way (readers might be traversing chain) - */ -hlist_nulls_add_head_rcu(&obj->obj_node, list); -unlock_chain(); // typically a spin_unlock() diff --git a/Documentation/RCU/rcuref.txt b/Documentation/RCU/rcuref.rst index 5e6429d66c24..b33aeb14fde3 100644 --- a/Documentation/RCU/rcuref.txt +++ b/Documentation/RCU/rcuref.rst @@ -1,4 +1,8 @@ -Reference-count design for elements of lists/arrays protected by RCU. +.. SPDX-License-Identifier: GPL-2.0 + +==================================================================== +Reference-count design for elements of lists/arrays protected by RCU +==================================================================== Please note that the percpu-ref feature is likely your first @@ -12,32 +16,33 @@ please read on. Reference counting on elements of lists which are protected by traditional reader/writer spinlocks or semaphores are straightforward: -CODE LISTING A: -1. 2. -add() search_and_reference() -{ { - alloc_object read_lock(&list_lock); - ... search_for_element - atomic_set(&el->rc, 1); atomic_inc(&el->rc); - write_lock(&list_lock); ... - add_element read_unlock(&list_lock); - ... ... - write_unlock(&list_lock); } -} - -3. 4. -release_referenced() delete() -{ { - ... write_lock(&list_lock); - if(atomic_dec_and_test(&el->rc)) ... - kfree(el); - ... remove_element -} write_unlock(&list_lock); - ... - if (atomic_dec_and_test(&el->rc)) - kfree(el); - ... - } +CODE LISTING A:: + + 1. 2. + add() search_and_reference() + { { + alloc_object read_lock(&list_lock); + ... search_for_element + atomic_set(&el->rc, 1); atomic_inc(&el->rc); + write_lock(&list_lock); ... + add_element read_unlock(&list_lock); + ... ... + write_unlock(&list_lock); } + } + + 3. 4. + release_referenced() delete() + { { + ... write_lock(&list_lock); + if(atomic_dec_and_test(&el->rc)) ... + kfree(el); + ... remove_element + } write_unlock(&list_lock); + ... + if (atomic_dec_and_test(&el->rc)) + kfree(el); + ... + } If this list/array is made lock free using RCU as in changing the write_lock() in add() and delete() to spin_lock() and changing read_lock() @@ -46,34 +51,35 @@ search_and_reference() could potentially hold reference to an element which has already been deleted from the list/array. Use atomic_inc_not_zero() in this scenario as follows: -CODE LISTING B: -1. 2. -add() search_and_reference() -{ { - alloc_object rcu_read_lock(); - ... search_for_element - atomic_set(&el->rc, 1); if (!atomic_inc_not_zero(&el->rc)) { - spin_lock(&list_lock); rcu_read_unlock(); - return FAIL; - add_element } - ... ... - spin_unlock(&list_lock); rcu_read_unlock(); -} } -3. 4. -release_referenced() delete() -{ { - ... spin_lock(&list_lock); - if (atomic_dec_and_test(&el->rc)) ... - call_rcu(&el->head, el_free); remove_element - ... spin_unlock(&list_lock); -} ... - if (atomic_dec_and_test(&el->rc)) - call_rcu(&el->head, el_free); - ... - } +CODE LISTING B:: + + 1. 2. + add() search_and_reference() + { { + alloc_object rcu_read_lock(); + ... search_for_element + atomic_set(&el->rc, 1); if (!atomic_inc_not_zero(&el->rc)) { + spin_lock(&list_lock); rcu_read_unlock(); + return FAIL; + add_element } + ... ... + spin_unlock(&list_lock); rcu_read_unlock(); + } } + 3. 4. + release_referenced() delete() + { { + ... spin_lock(&list_lock); + if (atomic_dec_and_test(&el->rc)) ... + call_rcu(&el->head, el_free); remove_element + ... spin_unlock(&list_lock); + } ... + if (atomic_dec_and_test(&el->rc)) + call_rcu(&el->head, el_free); + ... + } Sometimes, a reference to the element needs to be obtained in the -update (write) stream. In such cases, atomic_inc_not_zero() might be +update (write) stream. In such cases, atomic_inc_not_zero() might be overkill, since we hold the update-side spinlock. One might instead use atomic_inc() in such cases. @@ -82,39 +88,40 @@ search_and_reference() code path. In such cases, the atomic_dec_and_test() may be moved from delete() to el_free() as follows: -CODE LISTING C: -1. 2. -add() search_and_reference() -{ { - alloc_object rcu_read_lock(); - ... search_for_element - atomic_set(&el->rc, 1); atomic_inc(&el->rc); - spin_lock(&list_lock); ... - - add_element rcu_read_unlock(); - ... } - spin_unlock(&list_lock); 4. -} delete() -3. { -release_referenced() spin_lock(&list_lock); -{ ... - ... remove_element - if (atomic_dec_and_test(&el->rc)) spin_unlock(&list_lock); - kfree(el); ... - ... call_rcu(&el->head, el_free); -} ... -5. } -void el_free(struct rcu_head *rhp) -{ - release_referenced(); -} +CODE LISTING C:: + + 1. 2. + add() search_and_reference() + { { + alloc_object rcu_read_lock(); + ... search_for_element + atomic_set(&el->rc, 1); atomic_inc(&el->rc); + spin_lock(&list_lock); ... + + add_element rcu_read_unlock(); + ... } + spin_unlock(&list_lock); 4. + } delete() + 3. { + release_referenced() spin_lock(&list_lock); + { ... + ... remove_element + if (atomic_dec_and_test(&el->rc)) spin_unlock(&list_lock); + kfree(el); ... + ... call_rcu(&el->head, el_free); + } ... + 5. } + void el_free(struct rcu_head *rhp) + { + release_referenced(); + } The key point is that the initial reference added by add() is not removed until after a grace period has elapsed following removal. This means that search_and_reference() cannot find this element, which means that the value of el->rc cannot increase. Thus, once it reaches zero, there are no -readers that can or ever will be able to reference the element. The -element can therefore safely be freed. This in turn guarantees that if +readers that can or ever will be able to reference the element. The +element can therefore safely be freed. This in turn guarantees that if any reader finds the element, that reader may safely acquire a reference without checking the value of the reference counter. @@ -130,21 +137,21 @@ the eventual invocation of kfree(), which is usually not a problem on modern computer systems, even the small ones. In cases where delete() can sleep, synchronize_rcu() can be called from -delete(), so that el_free() can be subsumed into delete as follows: - -4. -delete() -{ - spin_lock(&list_lock); - ... - remove_element - spin_unlock(&list_lock); - ... - synchronize_rcu(); - if (atomic_dec_and_test(&el->rc)) - kfree(el); - ... -} +delete(), so that el_free() can be subsumed into delete as follows:: + + 4. + delete() + { + spin_lock(&list_lock); + ... + remove_element + spin_unlock(&list_lock); + ... + synchronize_rcu(); + if (atomic_dec_and_test(&el->rc)) + kfree(el); + ... + } As additional examples in the kernel, the pattern in listing C is used by reference counting of struct pid, while the pattern in listing B is used by diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.rst index a360a8796710..c9ab6af4d3be 100644 --- a/Documentation/RCU/stallwarn.txt +++ b/Documentation/RCU/stallwarn.rst @@ -1,4 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================== Using RCU's CPU Stall Detector +============================== This document first discusses what sorts of issues RCU's CPU stall detector can locate, and then discusses kernel parameters and Kconfig @@ -7,39 +11,40 @@ this document explains the stall detector's "splat" format. What Causes RCU CPU Stall Warnings? +=================================== So your kernel printed an RCU CPU stall warning. The next question is "What caused it?" The following problems can result in RCU CPU stall warnings: -o A CPU looping in an RCU read-side critical section. +- A CPU looping in an RCU read-side critical section. -o A CPU looping with interrupts disabled. +- A CPU looping with interrupts disabled. -o A CPU looping with preemption disabled. +- A CPU looping with preemption disabled. -o A CPU looping with bottom halves disabled. +- A CPU looping with bottom halves disabled. -o For !CONFIG_PREEMPT kernels, a CPU looping anywhere in the kernel +- For !CONFIG_PREEMPT kernels, a CPU looping anywhere in the kernel without invoking schedule(). If the looping in the kernel is really expected and desirable behavior, you might need to add some calls to cond_resched(). -o Booting Linux using a console connection that is too slow to +- Booting Linux using a console connection that is too slow to keep up with the boot-time console-message rate. For example, a 115Kbaud serial console can be -way- too slow to keep up with boot-time message rates, and will frequently result in RCU CPU stall warning messages. Especially if you have added debug printk()s. -o Anything that prevents RCU's grace-period kthreads from running. +- Anything that prevents RCU's grace-period kthreads from running. This can result in the "All QSes seen" console-log message. This message will include information on when the kthread last ran and how often it should be expected to run. It can also - result in the "rcu_.*kthread starved for" console-log message, + result in the ``rcu_.*kthread starved for`` console-log message, which will include additional debugging information. -o A CPU-bound real-time task in a CONFIG_PREEMPT kernel, which might +- A CPU-bound real-time task in a CONFIG_PREEMPT kernel, which might happen to preempt a low-priority task in the middle of an RCU read-side critical section. This is especially damaging if that low-priority task is not permitted to run on any other CPU, @@ -48,7 +53,7 @@ o A CPU-bound real-time task in a CONFIG_PREEMPT kernel, which might While the system is in the process of running itself out of memory, you might see stall-warning messages. -o A CPU-bound real-time task in a CONFIG_PREEMPT_RT kernel that +- A CPU-bound real-time task in a CONFIG_PREEMPT_RT kernel that is running at a higher priority than the RCU softirq threads. This will prevent RCU callbacks from ever being invoked, and in a CONFIG_PREEMPT_RCU kernel will further prevent @@ -63,7 +68,7 @@ o A CPU-bound real-time task in a CONFIG_PREEMPT_RT kernel that can increase your system's context-switch rate and thus degrade performance. -o A periodic interrupt whose handler takes longer than the time +- A periodic interrupt whose handler takes longer than the time interval between successive pairs of interrupts. This can prevent RCU's kthreads and softirq handlers from running. Note that certain high-overhead debugging options, for example @@ -71,20 +76,27 @@ o A periodic interrupt whose handler takes longer than the time considerably longer than normal, which can in turn result in RCU CPU stall warnings. -o Testing a workload on a fast system, tuning the stall-warning +- Testing a workload on a fast system, tuning the stall-warning timeout down to just barely avoid RCU CPU stall warnings, and then running the same workload with the same stall-warning timeout on a slow system. Note that thermal throttling and on-demand governors can cause a single system to be sometimes fast and sometimes slow! -o A hardware or software issue shuts off the scheduler-clock +- A hardware or software issue shuts off the scheduler-clock interrupt on a CPU that is not in dyntick-idle mode. This problem really has happened, and seems to be most likely to result in RCU CPU stall warnings for CONFIG_NO_HZ_COMMON=n kernels. -o A bug in the RCU implementation. +- A hardware or software issue that prevents time-based wakeups + from occurring. These issues can range from misconfigured or + buggy timer hardware through bugs in the interrupt or exception + path (whether hardware, firmware, or software) through bugs + in Linux's timer subsystem through bugs in the scheduler, and, + yes, even including bugs in RCU itself. + +- A bug in the RCU implementation. -o A hardware failure. This is quite unlikely, but has occurred +- A hardware failure. This is quite unlikely, but has occurred at least once in real life. A CPU failed in a running system, becoming unresponsive, but not causing an immediate crash. This resulted in a series of RCU CPU stall warnings, eventually @@ -109,6 +121,7 @@ see include/trace/events/rcu.h. Fine-Tuning the RCU CPU Stall Detector +====================================== The rcuupdate.rcu_cpu_stall_suppress module parameter disables RCU's CPU stall detector, which detects conditions that unduly delay RCU grace @@ -118,6 +131,7 @@ The stall detector's idea of what constitutes "unduly delayed" is controlled by a set of kernel configuration variables and cpp macros: CONFIG_RCU_CPU_STALL_TIMEOUT +---------------------------- This kernel configuration parameter defines the period of time that RCU will wait from the beginning of a grace period until it @@ -137,6 +151,7 @@ CONFIG_RCU_CPU_STALL_TIMEOUT /sys/module/rcupdate/parameters/rcu_cpu_stall_suppress. RCU_STALL_DELAY_DELTA +--------------------- Although the lockdep facility is extremely useful, it does add some overhead. Therefore, under CONFIG_PROVE_RCU, the @@ -145,6 +160,7 @@ RCU_STALL_DELAY_DELTA macro, not a kernel configuration parameter.) RCU_STALL_RAT_DELAY +------------------- The CPU stall detector tries to make the offending CPU print its own warnings, as this often gives better-quality stack traces. @@ -155,6 +171,7 @@ RCU_STALL_RAT_DELAY parameter.) 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 @@ -168,9 +185,10 @@ rcupdate.rcu_task_stall_timeout Interpreting RCU's CPU Stall-Detector "Splats" +============================================== For non-RCU-tasks flavors of RCU, when a CPU detects that it is stalling, -it will print a message similar to the following: +it will print a message similar to the following:: INFO: rcu_sched detected stalls on CPUs/tasks: 2-...: (3 GPs behind) idle=06c/0/0 softirq=1453/1455 fqs=0 @@ -223,7 +241,7 @@ an estimate of the total number of RCU callbacks queued across all CPUs (625 in this case). In kernels with CONFIG_RCU_FAST_NO_HZ, more information is printed -for each CPU: +for each CPU:: 0: (64628 ticks this GP) idle=dd5/3fffffffffffffff/0 softirq=82/543 last_accelerate: a345/d342 dyntick_enabled: 1 @@ -235,7 +253,7 @@ processing is enabled. If the grace period ends just as the stall warning starts printing, there will be a spurious stall-warning message, which will include -the following: +the following:: INFO: Stall ended before state dump start @@ -248,7 +266,7 @@ which is overkill for this sort of problem. If all CPUs and tasks have passed through quiescent states, but the grace period has nevertheless failed to end, the stall-warning splat -will include something like the following: +will include something like the following:: All QSes seen, last rcu_preempt kthread activity 23807 (4297905177-4297881370), jiffies_till_next_fqs=3, root ->qsmask 0x0 @@ -261,7 +279,7 @@ which is way less than 23807. Finally, the root rcu_node structure's If the relevant grace-period kthread has been unable to run prior to the stall warning, as was the case in the "All QSes seen" line above, -the following additional line is printed: +the following additional line is printed:: kthread starved for 23807 jiffies! g7075 f0x0 RCU_GP_WAIT_FQS(3) ->state=0x1 ->cpu=5 @@ -276,6 +294,7 @@ kthread last ran on CPU 5. Multiple Warnings From One Stall +================================ If a stall lasts long enough, multiple stall-warning messages will be printed for it. The second and subsequent messages are printed at @@ -285,9 +304,10 @@ of the stall and the first message. Stall Warnings for Expedited Grace Periods +========================================== If an expedited grace period detects a stall, it will place a message -like the following in dmesg: +like the following in dmesg:: INFO: rcu_sched detected expedited stalls on CPUs/tasks: { 7-... } 21119 jiffies s: 73 root: 0x2/. diff --git a/Documentation/RCU/torture.txt b/Documentation/RCU/torture.rst index af712a3c5b6a..a90147713062 100644 --- a/Documentation/RCU/torture.txt +++ b/Documentation/RCU/torture.rst @@ -1,7 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================== RCU Torture Test Operation +========================== CONFIG_RCU_TORTURE_TEST +======================= The CONFIG_RCU_TORTURE_TEST config option is available for all RCU implementations. It creates an rcutorture kernel module that can @@ -13,9 +18,10 @@ when the module is loaded, and stops when the module is unloaded. Module parameters are prefixed by "rcutorture." in Documentation/admin-guide/kernel-parameters.txt. -OUTPUT +Output +====== -The statistics output is as follows: +The statistics output is as follows:: rcu-torture:--- Start of test: nreaders=16 nfakewriters=4 stat_interval=30 verbose=0 test_no_idle_hz=1 shuffle_interval=3 stutter=5 irqreader=1 fqs_duration=0 fqs_holdoff=0 fqs_stutter=3 test_boost=1/0 test_boost_interval=7 test_boost_duration=4 rcu-torture: rtc: (null) ver: 155441 tfle: 0 rta: 155441 rtaf: 8884 rtf: 155440 rtmbe: 0 rtbe: 0 rtbke: 0 rtbre: 0 rtbf: 0 rtb: 0 nt: 3055767 @@ -36,53 +42,53 @@ automatic determination as to whether RCU operated correctly. The entries are as follows: -o "rtc": The hexadecimal address of the structure currently visible +* "rtc": The hexadecimal address of the structure currently visible to readers. -o "ver": The number of times since boot that the RCU writer task +* "ver": The number of times since boot that the RCU writer task has changed the structure visible to readers. -o "tfle": If non-zero, indicates that the "torture freelist" +* "tfle": If non-zero, indicates that the "torture freelist" containing structures to be placed into the "rtc" area is empty. This condition is important, since it can fool you into thinking that RCU is working when it is not. :-/ -o "rta": Number of structures allocated from the torture freelist. +* "rta": Number of structures allocated from the torture freelist. -o "rtaf": Number of allocations from the torture freelist that have +* "rtaf": Number of allocations from the torture freelist that have failed due to the list being empty. It is not unusual for this to be non-zero, but it is bad for it to be a large fraction of the value indicated by "rta". -o "rtf": Number of frees into the torture freelist. +* "rtf": Number of frees into the torture freelist. -o "rtmbe": A non-zero value indicates that rcutorture believes that +* "rtmbe": A non-zero value indicates that rcutorture believes that rcu_assign_pointer() and rcu_dereference() are not working correctly. This value should be zero. -o "rtbe": A non-zero value indicates that one of the rcu_barrier() +* "rtbe": A non-zero value indicates that one of the rcu_barrier() family of functions is not working correctly. -o "rtbke": rcutorture was unable to create the real-time kthreads +* "rtbke": rcutorture was unable to create the real-time kthreads used to force RCU priority inversion. This value should be zero. -o "rtbre": Although rcutorture successfully created the kthreads +* "rtbre": Although rcutorture successfully created the kthreads used to force RCU priority inversion, it was unable to set them to the real-time priority level of 1. This value should be zero. -o "rtbf": The number of times that RCU priority boosting failed +* "rtbf": The number of times that RCU priority boosting failed to resolve RCU priority inversion. -o "rtb": The number of times that rcutorture attempted to force +* "rtb": The number of times that rcutorture attempted to force an RCU priority inversion condition. If you are testing RCU priority boosting via the "test_boost" module parameter, this value should be non-zero. -o "nt": The number of times rcutorture ran RCU read-side code from +* "nt": The number of times rcutorture ran RCU read-side code from within a timer handler. This value should be non-zero only if you specified the "irqreader" module parameter. -o "Reader Pipe": Histogram of "ages" of structures seen by readers. +* "Reader Pipe": Histogram of "ages" of structures seen by readers. If any entries past the first two are non-zero, RCU is broken. And rcutorture prints the error flag string "!!!" to make sure you notice. The age of a newly allocated structure is zero, @@ -94,14 +100,14 @@ o "Reader Pipe": Histogram of "ages" of structures seen by readers. RCU. If you want to see what it looks like when broken, break it yourself. ;-) -o "Reader Batch": Another histogram of "ages" of structures seen +* "Reader Batch": Another histogram of "ages" of structures seen by readers, but in terms of counter flips (or batches) rather than in terms of grace periods. The legal number of non-zero entries is again two. The reason for this separate view is that it is sometimes easier to get the third entry to show up in the "Reader Batch" list than in the "Reader Pipe" list. -o "Free-Block Circulation": Shows the number of torture structures +* "Free-Block Circulation": Shows the number of torture structures that have reached a given point in the pipeline. The first element should closely correspond to the number of structures allocated, the second to the number that have been removed from reader view, @@ -112,7 +118,7 @@ o "Free-Block Circulation": Shows the number of torture structures Different implementations of RCU can provide implementation-specific additional information. For example, Tree SRCU provides the following -additional line: +additional line:: srcud-torture: Tree SRCU per-CPU(idx=0): 0(35,-21) 1(-4,24) 2(1,1) 3(-26,20) 4(28,-47) 5(-9,4) 6(-10,14) 7(-14,11) T(1,6) @@ -123,15 +129,15 @@ using a dynamically allocated srcu_struct (hence "srcud-" rather than "old" and "current" values to the underlying array, and is useful for debugging. The final "T" entry contains the totals of the counters. - -USAGE ON SPECIFIC KERNEL BUILDS +Usage on Specific Kernel Builds +=============================== It is sometimes desirable to torture RCU on a specific kernel build, for example, when preparing to put that kernel build into production. In that case, the kernel should be built with CONFIG_RCU_TORTURE_TEST=m so that the test can be started using modprobe and terminated using rmmod. -For example, the following script may be used to torture RCU: +For example, the following script may be used to torture RCU:: #!/bin/sh @@ -148,7 +154,8 @@ two are self-explanatory, while the last indicates that while there were no RCU failures, CPU-hotplug problems were detected. -USAGE ON MAINLINE KERNELS +Usage on Mainline Kernels +========================= When using rcutorture to test changes to RCU itself, it is often necessary to build a number of kernels in order to test that change @@ -180,16 +187,16 @@ to Tree SRCU might run only the SRCU-N and SRCU-P scenarios using the --configs argument to kvm.sh as follows: "--configs 'SRCU-N SRCU-P'". Large systems can run multiple copies of of the full set of scenarios, for example, a system with 448 hardware threads can run five instances -of the full set concurrently. To make this happen: +of the full set concurrently. To make this happen:: kvm.sh --cpus 448 --configs '5*CFLIST' Alternatively, such a system can run 56 concurrent instances of a single -eight-CPU scenario: +eight-CPU scenario:: kvm.sh --cpus 448 --configs '56*TREE04' -Or 28 concurrent instances of each of two eight-CPU scenarios: +Or 28 concurrent instances of each of two eight-CPU scenarios:: kvm.sh --cpus 448 --configs '28*TREE03 28*TREE04' @@ -199,14 +206,14 @@ values for memory may require disabling the callback-flooding tests using the --bootargs parameter discussed below. Sometimes additional debugging is useful, and in such cases the --kconfig -parameter to kvm.sh may be used, for example, "--kconfig 'CONFIG_KASAN=y'". +parameter to kvm.sh may be used, for example, ``--kconfig 'CONFIG_KASAN=y'``. Kernel boot arguments can also be supplied, for example, to control rcutorture's module parameters. For example, to test a change to RCU's CPU stall-warning code, use "--bootargs 'rcutorture.stall_cpu=30'". This will of course result in the scripting reporting a failure, namely the resuling RCU CPU stall warning. As noted above, reducing memory may -require disabling rcutorture's callback-flooding tests: +require disabling rcutorture's callback-flooding tests:: kvm.sh --cpus 448 --configs '56*TREE04' --memory 128M \ --bootargs 'rcutorture.fwd_progress=0' @@ -225,7 +232,7 @@ is listed at the end of the kvm.sh output, which you really should redirect to a file. The build products and console output of each run is kept in tools/testing/selftests/rcutorture/res in timestamped directories. A given directory can be supplied to kvm-find-errors.sh in order to have -it cycle you through summaries of errors and full error logs. For example: +it cycle you through summaries of errors and full error logs. For example:: tools/testing/selftests/rcutorture/bin/kvm-find-errors.sh \ tools/testing/selftests/rcutorture/res/2020.01.20-15.54.23 @@ -245,38 +252,42 @@ that was tested and any uncommitted changes in diff format. The most frequently used files in each per-scenario-run directory are: -.config: This file contains the Kconfig options. +.config: + This file contains the Kconfig options. -Make.out: This contains build output for a specific scenario. +Make.out: + This contains build output for a specific scenario. -console.log: This contains the console output for a specific scenario. +console.log: + This contains the console output for a specific scenario. This file may be examined once the kernel has booted, but it might not exist if the build failed. -vmlinux: This contains the kernel, which can be useful with tools like +vmlinux: + This contains the kernel, which can be useful with tools like objdump and gdb. A number of additional files are available, but are less frequently used. Many are intended for debugging of rcutorture itself or of its scripting. As of v5.4, a successful run with the default set of scenarios produces -the following summary at the end of the run on a 12-CPU system: - -SRCU-N ------- 804233 GPs (148.932/s) [srcu: g10008272 f0x0 ] -SRCU-P ------- 202320 GPs (37.4667/s) [srcud: g1809476 f0x0 ] -SRCU-t ------- 1122086 GPs (207.794/s) [srcu: g0 f0x0 ] -SRCU-u ------- 1111285 GPs (205.794/s) [srcud: g1 f0x0 ] -TASKS01 ------- 19666 GPs (3.64185/s) [tasks: g0 f0x0 ] -TASKS02 ------- 20541 GPs (3.80389/s) [tasks: g0 f0x0 ] -TASKS03 ------- 19416 GPs (3.59556/s) [tasks: g0 f0x0 ] -TINY01 ------- 836134 GPs (154.84/s) [rcu: g0 f0x0 ] n_max_cbs: 34198 -TINY02 ------- 850371 GPs (157.476/s) [rcu: g0 f0x0 ] n_max_cbs: 2631 -TREE01 ------- 162625 GPs (30.1157/s) [rcu: g1124169 f0x0 ] -TREE02 ------- 333003 GPs (61.6672/s) [rcu: g2647753 f0x0 ] n_max_cbs: 35844 -TREE03 ------- 306623 GPs (56.782/s) [rcu: g2975325 f0x0 ] n_max_cbs: 1496497 -CPU count limited from 16 to 12 -TREE04 ------- 246149 GPs (45.5831/s) [rcu: g1695737 f0x0 ] n_max_cbs: 434961 -TREE05 ------- 314603 GPs (58.2598/s) [rcu: g2257741 f0x2 ] n_max_cbs: 193997 -TREE07 ------- 167347 GPs (30.9902/s) [rcu: g1079021 f0x0 ] n_max_cbs: 478732 -CPU count limited from 16 to 12 -TREE09 ------- 752238 GPs (139.303/s) [rcu: g13075057 f0x0 ] n_max_cbs: 99011 +the following summary at the end of the run on a 12-CPU system:: + + SRCU-N ------- 804233 GPs (148.932/s) [srcu: g10008272 f0x0 ] + SRCU-P ------- 202320 GPs (37.4667/s) [srcud: g1809476 f0x0 ] + SRCU-t ------- 1122086 GPs (207.794/s) [srcu: g0 f0x0 ] + SRCU-u ------- 1111285 GPs (205.794/s) [srcud: g1 f0x0 ] + TASKS01 ------- 19666 GPs (3.64185/s) [tasks: g0 f0x0 ] + TASKS02 ------- 20541 GPs (3.80389/s) [tasks: g0 f0x0 ] + TASKS03 ------- 19416 GPs (3.59556/s) [tasks: g0 f0x0 ] + TINY01 ------- 836134 GPs (154.84/s) [rcu: g0 f0x0 ] n_max_cbs: 34198 + TINY02 ------- 850371 GPs (157.476/s) [rcu: g0 f0x0 ] n_max_cbs: 2631 + TREE01 ------- 162625 GPs (30.1157/s) [rcu: g1124169 f0x0 ] + TREE02 ------- 333003 GPs (61.6672/s) [rcu: g2647753 f0x0 ] n_max_cbs: 35844 + TREE03 ------- 306623 GPs (56.782/s) [rcu: g2975325 f0x0 ] n_max_cbs: 1496497 + CPU count limited from 16 to 12 + TREE04 ------- 246149 GPs (45.5831/s) [rcu: g1695737 f0x0 ] n_max_cbs: 434961 + TREE05 ------- 314603 GPs (58.2598/s) [rcu: g2257741 f0x2 ] n_max_cbs: 193997 + TREE07 ------- 167347 GPs (30.9902/s) [rcu: g1079021 f0x0 ] n_max_cbs: 478732 + CPU count limited from 16 to 12 + TREE09 ------- 752238 GPs (139.303/s) [rcu: g13075057 f0x0 ] n_max_cbs: 99011 diff --git a/Documentation/admin-guide/LSM/Yama.rst b/Documentation/admin-guide/LSM/Yama.rst index d0a060de3973..d9cd937ebd2d 100644 --- a/Documentation/admin-guide/LSM/Yama.rst +++ b/Documentation/admin-guide/LSM/Yama.rst @@ -19,9 +19,10 @@ attach to other running processes (e.g. Firefox, SSH sessions, GPG agent, etc) to extract additional credentials and continue to expand the scope of their attack without resorting to user-assisted phishing. -This is not a theoretical problem. SSH session hijacking -(http://www.storm.net.nz/projects/7) and arbitrary code injection -(http://c-skills.blogspot.com/2007/05/injectso.html) attacks already +This is not a theoretical problem. `SSH session hijacking +<https://www.blackhat.com/presentations/bh-usa-05/bh-us-05-boileau.pdf>`_ +and `arbitrary code injection +<https://c-skills.blogspot.com/2007/05/injectso.html>`_ attacks already exist and remain possible if ptrace is allowed to operate as before. Since ptrace is not commonly used by non-developers and non-admins, system builders should be allowed the option to disable this debugging system. diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst index 5fb526900023..5aad534233cd 100644 --- a/Documentation/admin-guide/README.rst +++ b/Documentation/admin-guide/README.rst @@ -258,7 +258,7 @@ Configuring the kernel Compiling the kernel -------------------- - - Make sure you have at least gcc 4.6 available. + - Make sure you have at least gcc 4.9 available. For more information, refer to :ref:`Documentation/process/changes.rst <changes>`. Please note that you can still run a.out user programs with this kernel. diff --git a/Documentation/admin-guide/blockdev/drbd/index.rst b/Documentation/admin-guide/blockdev/drbd/index.rst index 68ecd5c113e9..561fd1e35917 100644 --- a/Documentation/admin-guide/blockdev/drbd/index.rst +++ b/Documentation/admin-guide/blockdev/drbd/index.rst @@ -10,7 +10,7 @@ Description clusters and in this context, is a "drop-in" replacement for shared storage. Simplistically, you could see it as a network RAID 1. - Please visit http://www.drbd.org to find out more. + Please visit https://www.drbd.org to find out more. .. toctree:: :maxdepth: 1 diff --git a/Documentation/admin-guide/blockdev/floppy.rst b/Documentation/admin-guide/blockdev/floppy.rst index 4a8f31cf4139..0328438ebe2c 100644 --- a/Documentation/admin-guide/blockdev/floppy.rst +++ b/Documentation/admin-guide/blockdev/floppy.rst @@ -6,7 +6,7 @@ FAQ list: ========= A FAQ list may be found in the fdutils package (see below), and also -at <http://fdutils.linux.lu/faq.html>. +at <https://fdutils.linux.lu/faq.html>. LILO configuration options (Thinkpad users, read this) @@ -220,11 +220,11 @@ It also contains additional documentation about the floppy driver. The latest version can be found at fdutils homepage: - http://fdutils.linux.lu + https://fdutils.linux.lu The fdutils releases can be found at: - http://fdutils.linux.lu/download.html + https://fdutils.linux.lu/download.html http://www.tux.org/pub/knaff/fdutils/ diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst index d6b3b77a4129..a22024f9175e 100644 --- a/Documentation/admin-guide/bootconfig.rst +++ b/Documentation/admin-guide/bootconfig.rst @@ -71,6 +71,16 @@ For example,:: foo = bar, baz foo = qux # !ERROR! we can not re-define same key +If you want to update the value, you must use the override operator +``:=`` explicitly. For example:: + + foo = bar, baz + foo := qux + +then, the ``qux`` is assigned to ``foo`` key. This is useful for +overriding the default value by adding (partial) custom bootconfigs +without parsing the default bootconfig. + If you want to append the value to existing key as an array member, you can use ``+=`` operator. For example:: @@ -84,6 +94,7 @@ For example, following config is NOT allowed.:: foo = value1 foo.bar = value2 # !ERROR! subkey "bar" and value "value1" can NOT co-exist + foo.bar := value2 # !ERROR! even with the override operator, this is NOT allowed. Comments diff --git a/Documentation/admin-guide/cgroup-v1/rdma.rst b/Documentation/admin-guide/cgroup-v1/rdma.rst index 2fcb0a9bf790..e69369b7252e 100644 --- a/Documentation/admin-guide/cgroup-v1/rdma.rst +++ b/Documentation/admin-guide/cgroup-v1/rdma.rst @@ -114,4 +114,4 @@ Following resources can be accounted by rdma controller. (d) Delete resource limit:: - echo echo mlx4_0 hca_handle=max hca_object=max > /sys/fs/cgroup/rdma/1/rdma.max + echo mlx4_0 hca_handle=max hca_object=max > /sys/fs/cgroup/rdma/1/rdma.max diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index ce3e05e41724..fa4018afa5a4 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -1356,8 +1356,8 @@ PAGE_SIZE multiple when read back. thp_fault_alloc Number of transparent hugepages which were allocated to satisfy - a page fault, including COW faults. This counter is not present - when CONFIG_TRANSPARENT_HUGEPAGE is not set. + a page fault. This counter is not present when CONFIG_TRANSPARENT_HUGEPAGE + is not set. thp_collapse_alloc Number of transparent hugepages which were allocated to allow @@ -1483,8 +1483,7 @@ IO Interface Files ~~~~~~~~~~~~~~~~~~ io.stat - A read-only nested-keyed file which exists on non-root - cgroups. + A read-only nested-keyed file. Lines are keyed by $MAJ:$MIN device numbers and not ordered. The following nested keys are defined. @@ -1684,9 +1683,9 @@ per-cgroup dirty memory states are examined and the more restrictive of the two is enforced. cgroup writeback requires explicit support from the underlying -filesystem. Currently, cgroup writeback is implemented on ext2, ext4 -and btrfs. On other filesystems, all writeback IOs are attributed to -the root cgroup. +filesystem. Currently, cgroup writeback is implemented on ext2, ext4, +btrfs, f2fs, and xfs. On other filesystems, all writeback IOs are +attributed to the root cgroup. There are inherent differences in memory and writeback management which affects how cgroup ownership is tracked. Memory is tracked per @@ -2043,7 +2042,7 @@ RDMA ---- The "rdma" controller regulates the distribution and accounting of -of RDMA resources. +RDMA resources. RDMA Interface Files ~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/admin-guide/cifs/todo.rst b/Documentation/admin-guide/cifs/todo.rst index 084c25f92dcb..25f11576e7b9 100644 --- a/Documentation/admin-guide/cifs/todo.rst +++ b/Documentation/admin-guide/cifs/todo.rst @@ -98,7 +98,7 @@ x) Finish support for SMB3.1.1 compression Known Bugs ========== -See http://bugzilla.samba.org - search on product "CifsVFS" for +See https://bugzilla.samba.org - search on product "CifsVFS" for current bug list. Also check http://bugzilla.kernel.org (Product = File System, Component = CIFS) 1) existing symbolic links (Windows reparse points) are recognized but diff --git a/Documentation/admin-guide/cifs/usage.rst b/Documentation/admin-guide/cifs/usage.rst index d3fb67b8a976..7b32d5063803 100644 --- a/Documentation/admin-guide/cifs/usage.rst +++ b/Documentation/admin-guide/cifs/usage.rst @@ -16,8 +16,7 @@ standard for interoperating between Macs and Windows and major NAS appliances. Please see MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification) -http://protocolfreedom.org/ and -http://samba.org/samba/PFIF/ +or https://samba.org/samba/PFIF/ for more details. @@ -32,7 +31,7 @@ Build instructions For Linux: -1) Download the kernel (e.g. from http://www.kernel.org) +1) Download the kernel (e.g. from https://www.kernel.org) and change directory into the top of the kernel directory tree (e.g. /usr/src/linux-2.5.73) 2) make menuconfig (or make xconfig) @@ -831,7 +830,7 @@ the active sessions and the shares that are mounted. Enabling Kerberos (extended security) works but requires version 1.2 or later of the helper program cifs.upcall to be present and to be configured in the /etc/request-key.conf file. The cifs.upcall helper program is from the Samba -project(http://www.samba.org). NTLM and NTLMv2 and LANMAN support do not +project(https://www.samba.org). NTLM and NTLMv2 and LANMAN support do not require this helper. Note that NTLMv2 security (which does not require the cifs.upcall helper program), instead of using Kerberos, is sufficient for some use cases. diff --git a/Documentation/admin-guide/cifs/winucase_convert.pl b/Documentation/admin-guide/cifs/winucase_convert.pl index 322a9c833f23..993186beea20 100755 --- a/Documentation/admin-guide/cifs/winucase_convert.pl +++ b/Documentation/admin-guide/cifs/winucase_convert.pl @@ -16,7 +16,7 @@ # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License -# along with this program. If not, see <http://www.gnu.org/licenses/>. +# along with this program. If not, see <https://www.gnu.org/licenses/>. # while(<>) { diff --git a/Documentation/admin-guide/dell_rbu.rst b/Documentation/admin-guide/dell_rbu.rst index 8d70e1fc9f9d..2196caf1b939 100644 --- a/Documentation/admin-guide/dell_rbu.rst +++ b/Documentation/admin-guide/dell_rbu.rst @@ -26,7 +26,7 @@ Please go to http://support.dell.com register and you can find info on OpenManage and Dell Update packages (DUP). Libsmbios can also be used to update BIOS on Dell systems go to -http://linux.dell.com/libsmbios/ for details. +https://linux.dell.com/libsmbios/ for details. Dell_RBU driver supports BIOS update using the monolithic image and packetized image methods. In case of monolithic the driver allocates a contiguous chunk diff --git a/Documentation/admin-guide/device-mapper/dm-dust.rst b/Documentation/admin-guide/device-mapper/dm-dust.rst index b6e7e7ead831..e35ec8cd2f88 100644 --- a/Documentation/admin-guide/device-mapper/dm-dust.rst +++ b/Documentation/admin-guide/device-mapper/dm-dust.rst @@ -69,10 +69,11 @@ Create the dm-dust device: $ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 4096' Check the status of the read behavior ("bypass" indicates that all I/O -will be passed through to the underlying device):: +will be passed through to the underlying device; "verbose" indicates that +bad block additions, removals, and remaps will be verbosely logged):: $ sudo dmsetup status dust1 - 0 33552384 dust 252:17 bypass + 0 33552384 dust 252:17 bypass verbose $ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=128 iflag=direct 128+0 records in @@ -164,7 +165,7 @@ following message command:: A message will print with the number of bad blocks currently configured on the device:: - kernel: device-mapper: dust: countbadblocks: 895 badblock(s) found + countbadblocks: 895 badblock(s) found Querying for specific bad blocks -------------------------------- @@ -176,11 +177,11 @@ following message command:: The following message will print if the block is in the list:: - device-mapper: dust: queryblock: block 72 found in badblocklist + dust_query_block: block 72 found in badblocklist The following message will print if the block is not in the list:: - device-mapper: dust: queryblock: block 72 not found in badblocklist + dust_query_block: block 72 not found in badblocklist The "queryblock" message command will work in both the "enabled" and "disabled" modes, allowing the verification of whether a block @@ -198,12 +199,28 @@ following message command:: After clearing the bad block list, the following message will appear:: - kernel: device-mapper: dust: clearbadblocks: badblocks cleared + dust_clear_badblocks: badblocks cleared If there were no bad blocks to clear, the following message will appear:: - kernel: device-mapper: dust: clearbadblocks: no badblocks found + dust_clear_badblocks: no badblocks found + +Listing the bad block list +-------------------------- + +To list all bad blocks in the bad block list (using an example device +with blocks 1 and 2 in the bad block list), run the following message +command:: + + $ sudo dmsetup message dust1 0 listbadblocks + 1 + 2 + +If there are no bad blocks in the bad block list, the command will +execute with no output:: + + $ sudo dmsetup message dust1 0 listbadblocks Message commands list --------------------- @@ -223,6 +240,7 @@ Single argument message commands:: countbadblocks clearbadblocks + listbadblocks disable enable quiet diff --git a/Documentation/admin-guide/device-mapper/dm-integrity.rst b/Documentation/admin-guide/device-mapper/dm-integrity.rst index 9edd45593abd..3ab4f7756a6e 100644 --- a/Documentation/admin-guide/device-mapper/dm-integrity.rst +++ b/Documentation/admin-guide/device-mapper/dm-integrity.rst @@ -45,7 +45,7 @@ To use the target for the first time: will format the device 3. unload the dm-integrity target 4. read the "provided_data_sectors" value from the superblock -5. load the dm-integrity target with the the target size +5. load the dm-integrity target with the target size "provided_data_sectors" 6. if you want to use dm-integrity with dm-crypt, load the dm-crypt target with the size "provided_data_sectors" @@ -99,7 +99,7 @@ interleave_sectors:number the superblock is used. meta_device:device - Don't interleave the data and metadata on on device. Use a + Don't interleave the data and metadata on the device. Use a separate device for metadata. buffer_sectors:number diff --git a/Documentation/admin-guide/device-mapper/dm-raid.rst b/Documentation/admin-guide/device-mapper/dm-raid.rst index 695a2ea1d1ae..7ef9fe63b3d4 100644 --- a/Documentation/admin-guide/device-mapper/dm-raid.rst +++ b/Documentation/admin-guide/device-mapper/dm-raid.rst @@ -71,7 +71,7 @@ The target is named "raid" and it accepts the following parameters:: ============= =============================================================== Reference: Chapter 4 of - http://www.snia.org/sites/default/files/SNIA_DDF_Technical_Position_v2.0.pdf + https://www.snia.org/sites/default/files/SNIA_DDF_Technical_Position_v2.0.pdf <#raid_params>: The number of parameters that follow. diff --git a/Documentation/admin-guide/device-mapper/dm-zoned.rst b/Documentation/admin-guide/device-mapper/dm-zoned.rst index 553752ea2521..e635041351bc 100644 --- a/Documentation/admin-guide/device-mapper/dm-zoned.rst +++ b/Documentation/admin-guide/device-mapper/dm-zoned.rst @@ -14,7 +14,7 @@ host-aware zoned block devices. For a more detailed description of the zoned block device models and their constraints see (for SCSI devices): -http://www.t10.org/drafts.htm#ZBC_Family +https://www.t10.org/drafts.htm#ZBC_Family and (for ATA devices): diff --git a/Documentation/admin-guide/device-mapper/index.rst b/Documentation/admin-guide/device-mapper/index.rst index ec62fcc8eece..6cf8adc86fa8 100644 --- a/Documentation/admin-guide/device-mapper/index.rst +++ b/Documentation/admin-guide/device-mapper/index.rst @@ -11,6 +11,7 @@ Device Mapper dm-clone dm-crypt dm-dust + dm-ebs dm-flakey dm-init dm-integrity diff --git a/Documentation/admin-guide/device-mapper/verity.rst b/Documentation/admin-guide/device-mapper/verity.rst index bb02caa45289..66f71f0dab1b 100644 --- a/Documentation/admin-guide/device-mapper/verity.rst +++ b/Documentation/admin-guide/device-mapper/verity.rst @@ -83,6 +83,10 @@ restart_on_corruption not compatible with ignore_corruption and requires user space support to avoid restart loops. +panic_on_corruption + Panic the device when a corrupted block is discovered. This option is + not compatible with ignore_corruption and restart_on_corruption. + ignore_zero_blocks Do not verify blocks that are expected to contain zeroes and always return zeroes instead. This may be useful if the partition contains unused blocks diff --git a/Documentation/admin-guide/devices.txt b/Documentation/admin-guide/devices.txt index 2a97aaec8b12..d336f3f73a4c 100644 --- a/Documentation/admin-guide/devices.txt +++ b/Documentation/admin-guide/devices.txt @@ -375,8 +375,9 @@ 239 = /dev/uhid User-space I/O driver support for HID subsystem 240 = /dev/userio Serio driver testing device 241 = /dev/vhost-vsock Host kernel driver for virtio vsock + 242 = /dev/rfkill Turning off radio transmissions (rfkill) - 242-254 Reserved for local use + 243-254 Reserved for local use 255 Reserved for MISC_DYNAMIC_MINOR 11 char Raw keyboard device (Linux/SPARC only) @@ -1442,7 +1443,7 @@ ... The driver and documentation may be obtained from - http://www.winradio.com/ + https://www.winradio.com/ 82 block I2O hard disk 0 = /dev/i2o/hdag 33rd I2O hard disk, whole disk @@ -1656,7 +1657,7 @@ dynamically, so there is no fixed mapping from subdevice pathnames to minor numbers. - See http://www.comedi.org/ for information about the Comedi + See https://www.comedi.org/ for information about the Comedi project. 98 block User-mode virtual block device @@ -1723,7 +1724,7 @@ implementations a kernel presence for caching and easy mounting. For more information about the project, write to <arla-drinkers@stacken.kth.se> or see - http://www.stacken.kth.se/project/arla/ + https://www.stacken.kth.se/project/arla/ 103 block Audit device 0 = /dev/audit Audit device diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst index 1012bd9305e9..e5a8def45f3f 100644 --- a/Documentation/admin-guide/dynamic-debug-howto.rst +++ b/Documentation/admin-guide/dynamic-debug-howto.rst @@ -70,10 +70,10 @@ statements via:: nullarbor:~ # cat <debugfs>/dynamic_debug/control # filename:lineno [module]function flags format - /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:323 [svcxprt_rdma]svc_rdma_cleanup =_ "SVCRDMA Module Removed, deregister RPC RDMA transport\012" - /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:341 [svcxprt_rdma]svc_rdma_init =_ "\011max_inline : %d\012" - /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:340 [svcxprt_rdma]svc_rdma_init =_ "\011sq_depth : %d\012" - /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:338 [svcxprt_rdma]svc_rdma_init =_ "\011max_requests : %d\012" + net/sunrpc/svc_rdma.c:323 [svcxprt_rdma]svc_rdma_cleanup =_ "SVCRDMA Module Removed, deregister RPC RDMA transport\012" + net/sunrpc/svc_rdma.c:341 [svcxprt_rdma]svc_rdma_init =_ "\011max_inline : %d\012" + net/sunrpc/svc_rdma.c:340 [svcxprt_rdma]svc_rdma_init =_ "\011sq_depth : %d\012" + net/sunrpc/svc_rdma.c:338 [svcxprt_rdma]svc_rdma_init =_ "\011max_requests : %d\012" ... @@ -93,7 +93,7 @@ the debug statement callsites with any non-default flags:: nullarbor:~ # awk '$3 != "=_"' <debugfs>/dynamic_debug/control # filename:lineno [module]function flags format - /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svcsock.c:1603 [sunrpc]svc_send p "svc_process: st_sendto returned %d\012" + net/sunrpc/svcsock.c:1603 [sunrpc]svc_send p "svc_process: st_sendto returned %d\012" Command Language Reference ========================== @@ -156,6 +156,7 @@ against. Possible keywords are::: ``line-range`` cannot contain space, e.g. "1-30" is valid range but "1 - 30" is not. + ``module=foo`` combined keyword=value form is interchangably accepted The meanings of each keyword are: @@ -164,15 +165,18 @@ func of each callsite. Example:: func svc_tcp_accept + func *recv* # in rfcomm, bluetooth, ping, tcp file - The given string is compared against either the full pathname, the - src-root relative pathname, or the basename of the source file of - each callsite. Examples:: + The given string is compared against either the src-root relative + pathname, or the basename of the source file of each callsite. + Examples:: file svcsock.c - file kernel/freezer.c - file /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svcsock.c + file kernel/freezer.c # ie column 1 of control file + file drivers/usb/* # all callsites under it + file inode.c:start_* # parse :tail as a func (above) + file inode.c:1-100 # parse :tail as a line-range (above) module The given string is compared against the module name @@ -182,6 +186,7 @@ module module sunrpc module nfsd + module drm* # both drm, drm_kms_helper format The given string is searched for in the dynamic debug format @@ -251,8 +256,8 @@ the syntax described above, but must not exceed 1023 characters. Your bootloader may impose lower limits. These ``dyndbg`` params are processed just after the ddebug tables are -processed, as part of the arch_initcall. Thus you can enable debug -messages in all code run after this arch_initcall via this boot +processed, as part of the early_initcall. Thus you can enable debug +messages in all code run after this early_initcall via this boot parameter. On an x86 system for example ACPI enablement is a subsys_initcall and:: diff --git a/Documentation/admin-guide/ext4.rst b/Documentation/admin-guide/ext4.rst index 9443fcef1876..a683976fad6d 100644 --- a/Documentation/admin-guide/ext4.rst +++ b/Documentation/admin-guide/ext4.rst @@ -395,6 +395,13 @@ When mounting an ext4 filesystem, the following option are accepted: Documentation/filesystems/dax.txt. Note that this option is incompatible with data=journal. + inlinecrypt + When possible, encrypt/decrypt the contents of encrypted files using the + blk-crypto framework rather than filesystem-layer encryption. This + allows the use of inline encryption hardware. The on-disk format is + unaffected. For more details, see + Documentation/block/inline-encryption.rst. + Data Mode ========= There are 3 different data modes: @@ -611,7 +618,7 @@ kernel source: <file:fs/ext4/> programs: http://e2fsprogs.sourceforge.net/ -useful links: http://fedoraproject.org/wiki/ext3-devel +useful links: https://fedoraproject.org/wiki/ext3-devel http://www.bullopensource.org/ext4/ http://ext4.wiki.kernel.org/index.php/Main_Page - http://fedoraproject.org/wiki/Features/Ext4 + https://fedoraproject.org/wiki/Features/Ext4 diff --git a/Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst b/Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst index 47b1b3afac99..3b1ce68d2456 100644 --- a/Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst +++ b/Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst @@ -14,7 +14,7 @@ to the core through the special register mechanism that is susceptible to MDS attacks. Affected processors --------------------- +------------------- Core models (desktop, mobile, Xeon-E3) that implement RDRAND and/or RDSEED may be affected. @@ -59,7 +59,7 @@ executed on another core or sibling thread using MDS techniques. Mitigation mechanism -------------------- +-------------------- Intel will release microcode updates that modify the RDRAND, RDSEED, and EGETKEY instructions to overwrite secret special register data in the shared staging buffer before the secret data can be accessed by another logical @@ -118,7 +118,7 @@ with the option "srbds=". The option for this is: ============= ============================================================= SRBDS System Information ------------------------ +------------------------ The Linux kernel provides vulnerability status information through sysfs. For SRBDS this can be accessed by the following sysfs file: /sys/devices/system/cpu/vulnerabilities/srbds diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 58c7f9fc2396..ed1cf94ea50c 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -41,6 +41,7 @@ problems and bugs in particular. init kdump/index perf/index + pstore-blk This is the beginning of a section with information of interest to application developers. Documents covering various aspects of the kernel diff --git a/Documentation/admin-guide/kdump/vmcoreinfo.rst b/Documentation/admin-guide/kdump/vmcoreinfo.rst index e4ee8b2db604..2baad0bfb09d 100644 --- a/Documentation/admin-guide/kdump/vmcoreinfo.rst +++ b/Documentation/admin-guide/kdump/vmcoreinfo.rst @@ -93,6 +93,11 @@ It exists in the sparse memory mapping model, and it is also somewhat similar to the mem_map variable, both of them are used to translate an address. +MAX_PHYSMEM_BITS +---------------- + +Defines the maximum supported physical address space memory. + page ---- @@ -399,6 +404,17 @@ KERNELPACMASK The mask to extract the Pointer Authentication Code from a kernel virtual address. +TCR_EL1.T1SZ +------------ + +Indicates the size offset of the memory region addressed by TTBR1_EL1. +The region size is 2^(64-T1SZ) bytes. + +TTBR1_EL1 is the table base address register specified by ARMv8-A +architecture which is used to lookup the page-tables for the Virtual +addresses in the higher VA range (refer to ARMv8 ARM document for +more details). + arm === diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index fb95fad81c79..98ea67f27809 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -703,6 +703,11 @@ cpufreq.off=1 [CPU_FREQ] disable the cpufreq sub-system + cpufreq.default_governor= + [CPU_FREQ] Name of the default cpufreq governor or + policy to use. This governor must be registered in the + kernel before the cpufreq driver probes. + cpu_init_udelay=N [X86] Delay for N microsec between assert and de-assert of APIC INIT to start processors. This delay occurs @@ -827,6 +832,21 @@ useful to also enable the page_owner functionality. on: enable the feature + debugfs= [KNL] This parameter enables what is exposed to userspace + and debugfs internal clients. + Format: { on, no-mount, off } + on: All functions are enabled. + no-mount: + Filesystem is not registered but kernel clients can + access APIs and a crashkernel can be used to read + its content. There is nothing to mount. + off: Filesystem is not registered and clients + get a -EPERM as result when trying to register files + or directories within debugfs. + This is equivalent of the runtime functionality if + debugfs was not enabled in the kernel at all. + Default value is set in build-time with a kernel configuration. + debugpat [X86] Enable PAT debugging decnet.addr= [HW,NET] @@ -896,6 +916,10 @@ disable_radix [PPC] Disable RADIX MMU mode on POWER9 + radix_hcall_invalidate=on [PPC/PSERIES] + Disable RADIX GTSE feature and use hcall for TLB + invalidate. + disable_tlbie [PPC] Disable TLBIE instruction. Currently does not work with KVM, with HASH MMU, or with coherent accelerators. @@ -1207,26 +1231,28 @@ Format: {"off" | "on" | "skip[mbr]"} efi= [EFI] - Format: { "old_map", "nochunk", "noruntime", "debug", - "nosoftreserve", "disable_early_pci_dma", - "no_disable_early_pci_dma" } - old_map [X86-64]: switch to the old ioremap-based EFI - runtime services mapping. [Needs CONFIG_X86_UV=y] + Format: { "debug", "disable_early_pci_dma", + "nochunk", "noruntime", "nosoftreserve", + "novamap", "no_disable_early_pci_dma", + "old_map" } + debug: enable misc debug output. + disable_early_pci_dma: disable the busmaster bit on all + PCI bridges while in the EFI boot stub. nochunk: disable reading files in "chunks" in the EFI boot stub, as chunking can cause problems with some firmware implementations. noruntime : disable EFI runtime services support - debug: enable misc debug output nosoftreserve: The EFI_MEMORY_SP (Specific Purpose) attribute may cause the kernel to reserve the memory range for a memory mapping driver to claim. Specify efi=nosoftreserve to disable this reservation and treat the memory by its base type (i.e. EFI_CONVENTIONAL_MEMORY / "System RAM"). - disable_early_pci_dma: Disable the busmaster bit on all - PCI bridges while in the EFI boot stub + novamap: do not call SetVirtualAddressMap(). no_disable_early_pci_dma: Leave the busmaster bit set on all PCI bridges while in the EFI boot stub + old_map [X86-64]: switch to the old ioremap-based EFI + runtime services mapping. [Needs CONFIG_X86_UV=y] efi_no_storage_paranoia [EFI; X86] Using this parameter you can use more than 50% of @@ -2786,7 +2812,7 @@ touchscreen support is not enabled in the mainstream kernel as of 2.6.30, a preliminary port can be found in the "bleeding edge" mini2440 support kernel at - http://repo.or.cz/w/linux-2.6/mini2440.git + https://repo.or.cz/w/linux-2.6/mini2440.git mitigations= [X86,PPC,S390,ARM64] Control optional mitigations for @@ -3079,6 +3105,8 @@ no5lvl [X86-64] Disable 5-level paging mode. Forces kernel to use 4-level paging instead. + nofsgsbase [X86] Disables FSGSBASE instructions. + no_console_suspend [HW] Never suspend the console Disable suspending of consoles during suspend and @@ -4038,6 +4066,14 @@ latencies, which will choose a value aligned with the appropriate hardware boundaries. + rcutree.rcu_min_cached_objs= [KNL] + Minimum number of objects which are cached and + maintained per one CPU. Object size is equal + to PAGE_SIZE. The cache allows to reduce the + pressure to page allocator, also it makes the + whole algorithm to behave better in low memory + condition. + rcutree.jiffies_till_first_fqs= [KNL] Set delay from grace-period initialization to first attempt to force quiescent states. @@ -4258,6 +4294,20 @@ Set time (jiffies) between CPU-hotplug operations, or zero to disable CPU-hotplug testing. + rcutorture.read_exit= [KNL] + Set the number of read-then-exit kthreads used + to test the interaction of RCU updaters and + task-exit processing. + + rcutorture.read_exit_burst= [KNL] + The number of times in a given read-then-exit + episode that a set of read-then-exit kthreads + is spawned. + + rcutorture.read_exit_delay= [KNL] + The delay, in seconds, between successive + read-then-exit testing episodes. + rcutorture.shuffle_interval= [KNL] Set task-shuffle interval (s). Shuffling tasks allows some CPUs to go into dyntick-idle mode @@ -4407,6 +4457,45 @@ reboot_cpu is s[mp]#### with #### being the processor to be used for rebooting. + refscale.holdoff= [KNL] + Set test-start holdoff period. The purpose of + this parameter is to delay the start of the + test until boot completes in order to avoid + interference. + + refscale.loops= [KNL] + Set the number of loops over the synchronization + primitive under test. Increasing this number + reduces noise due to loop start/end overhead, + but the default has already reduced the per-pass + noise to a handful of picoseconds on ca. 2020 + x86 laptops. + + refscale.nreaders= [KNL] + Set number of readers. The default value of -1 + selects N, where N is roughly 75% of the number + of CPUs. A value of zero is an interesting choice. + + refscale.nruns= [KNL] + Set number of runs, each of which is dumped onto + the console log. + + refscale.readdelay= [KNL] + Set the read-side critical-section duration, + measured in microseconds. + + refscale.scale_type= [KNL] + Specify the read-protection implementation to test. + + refscale.shutdown= [KNL] + Shut down the system at the end of the performance + test. This defaults to 1 (shut it down) when + rcuperf is built into the kernel and to 0 (leave + it running) when rcuperf is built as a module. + + refscale.verbose= [KNL] + Enable additional printk() statements. + relax_domain_level= [KNL, SMP] Set scheduler's default relax_domain_level. See Documentation/admin-guide/cgroup-v1/cpusets.rst. @@ -4604,7 +4693,7 @@ fragmentation. Defaults to 1 for systems with more than 32MB of RAM, 0 otherwise. - slub_debug[=options[,slabs]] [MM, SLUB] + slub_debug[=options[,slabs][;[options[,slabs]]...] [MM, SLUB] Enabling slub_debug allows one to determine the culprit if slab objects become corrupted. Enabling slub_debug can create guard zones around objects and @@ -5082,6 +5171,13 @@ Prevent the CPU-hotplug component of torturing until after init has spawned. + torture.ftrace_dump_at_shutdown= [KNL] + Dump the ftrace buffer at torture-test shutdown, + even if there were no errors. This can be a + very costly operation when many torture tests + are running concurrently, especially on systems + with rotating-rust storage. + tp720= [HW,PS2] tpm_suspend_pcr=[HW,TPM] @@ -5712,8 +5808,9 @@ panic() code such as dumping handler. xen_nopvspin [X86,XEN] - Disables the ticketlock slowpath using Xen PV - optimizations. + Disables the qspinlock slowpath using Xen PV optimizations. + This parameter is obsoleted by "nopvspin" parameter, which + has equivalent effect for XEN platform. xen_nopv [X86] Disables the PV optimizations forcing the HVM guest to @@ -5739,6 +5836,11 @@ as generic guest with no PV drivers. Currently support XEN HVM, KVM, HYPER_V and VMWARE guest. + nopvspin [X86,XEN,KVM] + Disables the qspinlock slow path using PV optimizations + which allow the hypervisor to 'idle' the guest on lock + contention. + xirc2ps_cs= [NET,PCMCIA] Format: <irq>,<irq_mask>,<io>,<full_duplex>,<do_sound>,<lockup_hack>[,<irq2>[,<irq3>[,<irq4>]]] diff --git a/Documentation/admin-guide/laptops/disk-shock-protection.rst b/Documentation/admin-guide/laptops/disk-shock-protection.rst index e97c5f78d8c3..22c7ec3e84cf 100644 --- a/Documentation/admin-guide/laptops/disk-shock-protection.rst +++ b/Documentation/admin-guide/laptops/disk-shock-protection.rst @@ -135,7 +135,7 @@ single project which, although still considered experimental, is fit for use. Please feel free to add projects that have been the victims of my ignorance. -- http://www.thinkwiki.org/wiki/HDAPS +- https://www.thinkwiki.org/wiki/HDAPS See this page for information about Linux support of the hard disk active protection system as implemented in IBM/Lenovo Thinkpads. diff --git a/Documentation/admin-guide/laptops/sonypi.rst b/Documentation/admin-guide/laptops/sonypi.rst index c6eaaf48f7c1..190da1234314 100644 --- a/Documentation/admin-guide/laptops/sonypi.rst +++ b/Documentation/admin-guide/laptops/sonypi.rst @@ -151,7 +151,7 @@ Bugs: different way to adjust the backlighting of the screen. There is a userspace utility to adjust the brightness on those models, which can be downloaded from - http://www.acc.umu.se/~erikw/program/smartdimmer-0.1.tar.bz2 + https://www.acc.umu.se/~erikw/program/smartdimmer-0.1.tar.bz2 - since all development was done by reverse engineering, there is *absolutely no guarantee* that this driver will not crash your diff --git a/Documentation/admin-guide/laptops/thinkpad-acpi.rst b/Documentation/admin-guide/laptops/thinkpad-acpi.rst index 822907dcc845..5e477869df18 100644 --- a/Documentation/admin-guide/laptops/thinkpad-acpi.rst +++ b/Documentation/admin-guide/laptops/thinkpad-acpi.rst @@ -50,6 +50,7 @@ detailed description): - WAN enable and disable - UWB enable and disable - LCD Shadow (PrivacyGuard) enable and disable + - Lap mode sensor A compatibility table by model and feature is maintained on the web site, http://ibm-acpi.sf.net/. I appreciate any success or failure @@ -904,7 +905,7 @@ temperatures: The mapping of thermal sensors to physical locations varies depending on system-board model (and thus, on ThinkPad model). -http://thinkwiki.org/wiki/Thermal_Sensors is a public wiki page that +https://thinkwiki.org/wiki/Thermal_Sensors is a public wiki page that tries to track down these locations for various models. Most (newer?) models seem to follow this pattern: @@ -925,7 +926,7 @@ For the R51 (source: Thomas Gruber): - 3: Internal HDD For the T43, T43/p (source: Shmidoax/Thinkwiki.org) -http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p +https://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p - 2: System board, left side (near PCMCIA slot), reported as HDAPS temp - 3: PCMCIA slot @@ -935,7 +936,7 @@ http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p - 11: Power regulator, underside of system board, below F2 key The A31 has a very atypical layout for the thermal sensors -(source: Milos Popovic, http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31) +(source: Milos Popovic, https://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31) - 1: CPU - 2: Main Battery: main sensor @@ -1432,6 +1433,20 @@ The first command ensures the best viewing angle and the latter one turns on the feature, restricting the viewing angles. +DYTC Lapmode sensor +------------------ + +sysfs: dytc_lapmode + +Newer thinkpads and mobile workstations have the ability to determine if +the device is in deskmode or lapmode. This feature is used by user space +to decide if WWAN transmission can be increased to maximum power and is +also useful for understanding the different thermal modes available as +they differ between desk and lap mode. + +The property is read-only. If the platform doesn't have support the sysfs +class is not created. + EXPERIMENTAL: UWB ----------------- @@ -1470,6 +1485,23 @@ For more details about which buttons will appear depending on the mode, please review the laptop's user guide: http://www.lenovo.com/shop/americas/content/user_guides/x1carbon_2_ug_en.pdf +Battery charge control +---------------------- + +sysfs attributes: +/sys/class/power_supply/BAT*/charge_control_{start,end}_threshold + +These two attributes are created for those batteries that are supported by the +driver. They enable the user to control the battery charge thresholds of the +given battery. Both values may be read and set. `charge_control_start_threshold` +accepts an integer between 0 and 99 (inclusive); this value represents a battery +percentage level, below which charging will begin. `charge_control_end_threshold` +accepts an integer between 1 and 100 (inclusive); this value represents a battery +percentage level, above which charging will stop. + +The exact semantics of the attributes may be found in +Documentation/ABI/testing/sysfs-class-power. + Multiple Commands, Module Parameters ------------------------------------ diff --git a/Documentation/admin-guide/md.rst b/Documentation/admin-guide/md.rst index d973d469ffc4..cc8781b96b4d 100644 --- a/Documentation/admin-guide/md.rst +++ b/Documentation/admin-guide/md.rst @@ -426,6 +426,10 @@ All md devices contain: The accepted values when writing to this file are ``ppl`` and ``resync``, used to enable and disable PPL. + uuid + This indicates the UUID of the array in the following format: + xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + As component devices are added to an md array, they appear in the ``md`` directory as new directories named:: diff --git a/Documentation/admin-guide/media/building.rst b/Documentation/admin-guide/media/building.rst index c898e3a981c1..2d660b76caea 100644 --- a/Documentation/admin-guide/media/building.rst +++ b/Documentation/admin-guide/media/building.rst @@ -90,7 +90,7 @@ built as modules. Those GPU-specific drivers are selected via the ``Graphics support`` menu, under ``Device Drivers``. - When a GPU driver supports supports HDMI CEC, it will automatically + When a GPU driver supports HDMI CEC, it will automatically enable the CEC core support at the media subsystem. Media dependencies @@ -244,7 +244,7 @@ functionality. If you have an hybrid card, you may need to enable both ``Analog TV`` and ``Digital TV`` at the menu. -When using this option, the defaults for the the media support core +When using this option, the defaults for the media support core functionality are usually good enough to provide the basic functionality for the driver. Yet, you could manually enable some desired extra (optional) functionality using the settings under each of the following diff --git a/Documentation/admin-guide/media/fimc.rst b/Documentation/admin-guide/media/fimc.rst index 0b8ddc4a3008..56b149d9a527 100644 --- a/Documentation/admin-guide/media/fimc.rst +++ b/Documentation/admin-guide/media/fimc.rst @@ -2,7 +2,7 @@ .. include:: <isonum.txt> -The Samsung S5P/EXYNOS4 FIMC driver +The Samsung S5P/Exynos4 FIMC driver =================================== Copyright |copy| 2012 - 2013 Samsung Electronics Co., Ltd. @@ -19,7 +19,7 @@ drivers/media/platform/exynos4-is directory. Supported SoCs -------------- -S5PC100 (mem-to-mem only), S5PV210, EXYNOS4210 +S5PC100 (mem-to-mem only), S5PV210, Exynos4210 Supported features ------------------ @@ -45,7 +45,7 @@ Media device interface ~~~~~~~~~~~~~~~~~~~~~~ The driver supports Media Controller API as defined at :ref:`media_controller`. -The media device driver name is "SAMSUNG S5P FIMC". +The media device driver name is "Samsung S5P FIMC". The purpose of this interface is to allow changing assignment of FIMC instances to the SoC peripheral camera input at runtime and optionally to control internal diff --git a/Documentation/admin-guide/media/vivid.rst b/Documentation/admin-guide/media/vivid.rst index 52e57b773f07..6d7175f96f74 100644 --- a/Documentation/admin-guide/media/vivid.rst +++ b/Documentation/admin-guide/media/vivid.rst @@ -293,6 +293,15 @@ all configurable using the following module options: - 0: vmalloc - 1: dma-contig +- cache_hints: + + specifies if the device should set queues' user-space cache and memory + consistency hint capability (V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS). + The hints are valid only when using MMAP streaming I/O. Default is 0. + + - 0: forbid hints + - 1: allow hints + Taken together, all these module options allow you to precisely customize the driver behavior and test your application with all sorts of permutations. It is also very suitable to emulate hardware that is not yet available, e.g. diff --git a/Documentation/admin-guide/mm/concepts.rst b/Documentation/admin-guide/mm/concepts.rst index c2531b14bf46..fa0974fbeae7 100644 --- a/Documentation/admin-guide/mm/concepts.rst +++ b/Documentation/admin-guide/mm/concepts.rst @@ -35,7 +35,7 @@ physical memory (demand paging) and provides a mechanism for the protection and controlled sharing of data between processes. With virtual memory, each and every memory access uses a virtual -address. When the CPU decodes the an instruction that reads (or +address. When the CPU decodes an instruction that reads (or writes) from (or to) the system memory, it translates the `virtual` address encoded in that instruction to a `physical` address that the memory controller can understand. diff --git a/Documentation/admin-guide/mm/hugetlbpage.rst b/Documentation/admin-guide/mm/hugetlbpage.rst index 5026e58826e2..015a5f7d7854 100644 --- a/Documentation/admin-guide/mm/hugetlbpage.rst +++ b/Documentation/admin-guide/mm/hugetlbpage.rst @@ -101,37 +101,48 @@ be specified in bytes with optional scale suffix [kKmMgG]. The default huge page size may be selected with the "default_hugepagesz=<size>" boot parameter. Hugetlb boot command line parameter semantics -hugepagesz - Specify a huge page size. Used in conjunction with hugepages + +hugepagesz + Specify a huge page size. Used in conjunction with hugepages parameter to preallocate a number of huge pages of the specified size. Hence, hugepagesz and hugepages are typically specified in - pairs such as: + pairs such as:: + hugepagesz=2M hugepages=512 + hugepagesz can only be specified once on the command line for a specific huge page size. Valid huge page sizes are architecture dependent. -hugepages - Specify the number of huge pages to preallocate. This typically +hugepages + Specify the number of huge pages to preallocate. This typically follows a valid hugepagesz or default_hugepagesz parameter. However, if hugepages is the first or only hugetlb command line parameter it implicitly specifies the number of huge pages of default size to allocate. If the number of huge pages of default size is implicitly specified, it can not be overwritten by a hugepagesz,hugepages parameter pair for the default size. - For example, on an architecture with 2M default huge page size: + + For example, on an architecture with 2M default huge page size:: + hugepages=256 hugepagesz=2M hugepages=512 + will result in 256 2M huge pages being allocated and a warning message indicating that the hugepages=512 parameter is ignored. If a hugepages parameter is preceded by an invalid hugepagesz parameter, it will be ignored. -default_hugepagesz - Specify the default huge page size. This parameter can +default_hugepagesz + pecify the default huge page size. This parameter can only be specified once on the command line. default_hugepagesz can optionally be followed by the hugepages parameter to preallocate a specific number of huge pages of default size. The number of default sized huge pages to preallocate can also be implicitly specified as mentioned in the hugepages section above. Therefore, on an - architecture with 2M default huge page size: + architecture with 2M default huge page size:: + hugepages=256 default_hugepagesz=2M hugepages=256 hugepages=256 default_hugepagesz=2M + will all result in 256 2M huge pages being allocated. Valid default huge page size is architecture dependent. diff --git a/Documentation/admin-guide/mm/index.rst b/Documentation/admin-guide/mm/index.rst index 11db46448354..cd727cfc1b04 100644 --- a/Documentation/admin-guide/mm/index.rst +++ b/Documentation/admin-guide/mm/index.rst @@ -31,6 +31,7 @@ the Linux memory management. idle_page_tracking ksm memory-hotplug + nommu-mmap numa_memory_policy numaperf pagemap diff --git a/Documentation/admin-guide/mm/ksm.rst b/Documentation/admin-guide/mm/ksm.rst index 874eb0c77d34..97d816791aca 100644 --- a/Documentation/admin-guide/mm/ksm.rst +++ b/Documentation/admin-guide/mm/ksm.rst @@ -9,7 +9,7 @@ Overview KSM is a memory-saving de-duplication feature, enabled by CONFIG_KSM=y, added to the Linux kernel in 2.6.32. See ``mm/ksm.c`` for its implementation, -and http://lwn.net/Articles/306704/ and http://lwn.net/Articles/330589/ +and http://lwn.net/Articles/306704/ and https://lwn.net/Articles/330589/ KSM was originally developed for use with KVM (where it was known as Kernel Shared Memory), to fit more virtual machines into physical memory, @@ -52,7 +52,7 @@ with EAGAIN, but more probably arousing the Out-Of-Memory killer. If KSM is not configured into the running kernel, madvise MADV_MERGEABLE and MADV_UNMERGEABLE simply fail with EINVAL. If the running kernel was built with CONFIG_KSM=y, those calls will normally succeed: even if the -the KSM daemon is not currently running, MADV_MERGEABLE still registers +KSM daemon is not currently running, MADV_MERGEABLE still registers the range for whenever the KSM daemon is started; even if the range cannot contain any pages which KSM could actually merge; even if MADV_UNMERGEABLE is applied to a range which was never MADV_MERGEABLE. diff --git a/Documentation/nommu-mmap.txt b/Documentation/admin-guide/mm/nommu-mmap.rst index 530fed08de2c..530fed08de2c 100644 --- a/Documentation/nommu-mmap.txt +++ b/Documentation/admin-guide/mm/nommu-mmap.rst diff --git a/Documentation/admin-guide/mm/numaperf.rst b/Documentation/admin-guide/mm/numaperf.rst index a80c3c37226e..4d69ef1de830 100644 --- a/Documentation/admin-guide/mm/numaperf.rst +++ b/Documentation/admin-guide/mm/numaperf.rst @@ -129,7 +129,7 @@ will create the following directory:: /sys/devices/system/node/nodeX/memory_side_cache/ -If that directory is not present, the system either does not not provide +If that directory is not present, the system either does not provide a memory-side cache, or that information is not accessible to the kernel. The attributes for each level of cache is provided under its cache diff --git a/Documentation/admin-guide/mm/transhuge.rst b/Documentation/admin-guide/mm/transhuge.rst index 6a233e42be08..b2acd0d395ca 100644 --- a/Documentation/admin-guide/mm/transhuge.rst +++ b/Documentation/admin-guide/mm/transhuge.rst @@ -305,8 +305,7 @@ monitor how successfully the system is providing huge pages for use. thp_fault_alloc is incremented every time a huge page is successfully - allocated to handle a page fault. This applies to both the - first time a page is faulted and for COW faults. + allocated to handle a page fault. thp_collapse_alloc is incremented by khugepaged when it has found diff --git a/Documentation/admin-guide/nfs/nfs-client.rst b/Documentation/admin-guide/nfs/nfs-client.rst index c4b777c7584b..6adb6457bc69 100644 --- a/Documentation/admin-guide/nfs/nfs-client.rst +++ b/Documentation/admin-guide/nfs/nfs-client.rst @@ -65,8 +65,8 @@ migrated onto another server by means of the special "fs_locations" attribute. See `RFC3530 Section 6: Filesystem Migration and Replication`_ and `Implementation Guide for Referrals in NFSv4`_. -.. _RFC3530 Section 6\: Filesystem Migration and Replication: http://tools.ietf.org/html/rfc3530#section-6 -.. _Implementation Guide for Referrals in NFSv4: http://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00 +.. _RFC3530 Section 6\: Filesystem Migration and Replication: https://tools.ietf.org/html/rfc3530#section-6 +.. _Implementation Guide for Referrals in NFSv4: https://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00 The fs_locations information can take the form of either an ip address and a path, or a DNS hostname and a path. The latter requires the NFS client to diff --git a/Documentation/admin-guide/nfs/nfs-rdma.rst b/Documentation/admin-guide/nfs/nfs-rdma.rst index ef0f3678b1fb..f137485f8bde 100644 --- a/Documentation/admin-guide/nfs/nfs-rdma.rst +++ b/Documentation/admin-guide/nfs/nfs-rdma.rst @@ -65,7 +65,7 @@ use with NFS/RDMA. If the version is less than 1.1.2 or the command does not exist, you should install the latest version of nfs-utils. - Download the latest package from: http://www.kernel.org/pub/linux/utils/nfs + Download the latest package from: https://www.kernel.org/pub/linux/utils/nfs Uncompress the package and follow the installation instructions. diff --git a/Documentation/admin-guide/nfs/nfsroot.rst b/Documentation/admin-guide/nfs/nfsroot.rst index c6772075c80c..135218f33394 100644 --- a/Documentation/admin-guide/nfs/nfsroot.rst +++ b/Documentation/admin-guide/nfs/nfsroot.rst @@ -264,7 +264,7 @@ They depend on various facilities being available: access to the floppy drive device, /dev/fd0 For more information on syslinux, including how to create bootdisks - for prebuilt kernels, see http://syslinux.zytor.com/ + for prebuilt kernels, see https://syslinux.zytor.com/ .. note:: Previously it was possible to write a kernel directly to @@ -292,7 +292,7 @@ They depend on various facilities being available: cdrecord dev=ATAPI:1,0,0 arch/x86/boot/image.iso For more information on isolinux, including how to create bootdisks - for prebuilt kernels, see http://syslinux.zytor.com/ + for prebuilt kernels, see https://syslinux.zytor.com/ - Using LILO @@ -346,7 +346,7 @@ They depend on various facilities being available: see Documentation/admin-guide/serial-console.rst for more information. For more information on isolinux, including how to create bootdisks - for prebuilt kernels, see http://syslinux.zytor.com/ + for prebuilt kernels, see https://syslinux.zytor.com/ diff --git a/Documentation/admin-guide/nfs/pnfs-block-server.rst b/Documentation/admin-guide/nfs/pnfs-block-server.rst index b00a2e705cc4..20fe9f5117fe 100644 --- a/Documentation/admin-guide/nfs/pnfs-block-server.rst +++ b/Documentation/admin-guide/nfs/pnfs-block-server.rst @@ -8,7 +8,7 @@ to handling all the metadata access to the NFS export also hands out layouts to the clients to directly access the underlying block devices that are shared with the client. -To use pNFS block layouts with with the Linux NFS server the exported file +To use pNFS block layouts with the Linux NFS server the exported file system needs to support the pNFS block layouts (currently just XFS), and the file system must sit on shared storage (typically iSCSI) that is accessible to the clients in addition to the MDS. As of now the file system needs to diff --git a/Documentation/admin-guide/nfs/pnfs-scsi-server.rst b/Documentation/admin-guide/nfs/pnfs-scsi-server.rst index d2f6ee558071..b2eec2288329 100644 --- a/Documentation/admin-guide/nfs/pnfs-scsi-server.rst +++ b/Documentation/admin-guide/nfs/pnfs-scsi-server.rst @@ -9,7 +9,7 @@ which in addition to handling all the metadata access to the NFS export, also hands out layouts to the clients so that they can directly access the underlying SCSI LUNs that are shared with the client. -To use pNFS SCSI layouts with with the Linux NFS server, the exported file +To use pNFS SCSI layouts with the Linux NFS server, the exported file system needs to support the pNFS SCSI layouts (currently just XFS), and the file system must sit on a SCSI LUN that is accessible to the clients in addition to the MDS. As of now the file system needs to sit directly on the diff --git a/Documentation/admin-guide/perf/arm-ccn.rst b/Documentation/admin-guide/perf/arm-ccn.rst index 832b0c64023a..f62f7fe50eba 100644 --- a/Documentation/admin-guide/perf/arm-ccn.rst +++ b/Documentation/admin-guide/perf/arm-ccn.rst @@ -27,7 +27,7 @@ Crosspoint PMU events require "xp" (index), "bus" (bus number) and "vc" (virtual channel ID). Crosspoint watchpoint-based events (special "event" value 0xfe) -require "xp" and "vc" as as above plus "port" (device port index), +require "xp" and "vc" as above plus "port" (device port index), "dir" (transmit/receive direction), comparator values ("cmp_l" and "cmp_h") and "mask", being index of the comparator mask. diff --git a/Documentation/admin-guide/pm/cpufreq.rst b/Documentation/admin-guide/pm/cpufreq.rst index 0c74a7784964..368e612145d2 100644 --- a/Documentation/admin-guide/pm/cpufreq.rst +++ b/Documentation/admin-guide/pm/cpufreq.rst @@ -147,9 +147,9 @@ CPUs in it. The next major initialization step for a new policy object is to attach a scaling governor to it (to begin with, that is the default scaling governor -determined by the kernel configuration, but it may be changed later -via ``sysfs``). First, a pointer to the new policy object is passed to the -governor's ``->init()`` callback which is expected to initialize all of the +determined by the kernel command line or configuration, but it may be changed +later via ``sysfs``). First, a pointer to the new policy object is passed to +the governor's ``->init()`` callback which is expected to initialize all of the data structures necessary to handle the given policy and, possibly, to add a governor ``sysfs`` interface to it. Next, the governor is started by invoking its ``->start()`` callback. diff --git a/Documentation/admin-guide/pm/intel-speed-select.rst b/Documentation/admin-guide/pm/intel-speed-select.rst index b2ca601c21c6..219f1359aac7 100644 --- a/Documentation/admin-guide/pm/intel-speed-select.rst +++ b/Documentation/admin-guide/pm/intel-speed-select.rst @@ -114,7 +114,7 @@ base performance profile (which is performance level 0). Lock/Unlock status ~~~~~~~~~~~~~~~~~~ -Even if there are multiple performance profiles, it is possible that that they +Even if there are multiple performance profiles, it is possible that they are locked. If they are locked, users cannot issue a command to change the performance state. It is possible that there is a BIOS setup to unlock or check with your system vendor. @@ -883,7 +883,7 @@ To enable Intel(R) SST-TF, execute:: enable:success In this case, the option "-a" is optional. If set, it enables Intel(R) SST-TF -feature and also sets the CPUs to high and and low priority using Intel Speed +feature and also sets the CPUs to high and low priority using Intel Speed Select Technology Core Power (Intel(R) SST-CP) features. The CPU numbers passed with "-c" arguments are marked as high priority, including its siblings. diff --git a/Documentation/admin-guide/pm/intel_pstate.rst b/Documentation/admin-guide/pm/intel_pstate.rst index 39d80bc29ccd..9db924904d2c 100644 --- a/Documentation/admin-guide/pm/intel_pstate.rst +++ b/Documentation/admin-guide/pm/intel_pstate.rst @@ -431,6 +431,17 @@ argument is passed to the kernel in the command line. supported in the current configuration, writes to this attribute will fail with an appropriate error. +``energy_efficiency`` + This attribute is only present on platforms, which have CPUs matching + Kaby Lake or Coffee Lake desktop CPU model. By default + energy efficiency optimizations are disabled on these CPU models in HWP + mode by this driver. Enabling energy efficiency may limit maximum + operating frequency in both HWP and non HWP mode. In non HWP mode, + optimizations are done only in the turbo frequency range. In HWP mode, + optimizations are done in the entire frequency range. Setting this + attribute to "1" enables energy efficiency optimizations and setting + to "0" disables energy efficiency optimizations. + Interpretation of Policy Attributes ----------------------------------- @@ -554,7 +565,11 @@ somewhere between the two extremes: Strings written to the ``energy_performance_preference`` attribute are internally translated to integer values written to the processor's Energy-Performance Preference (EPP) knob (if supported) or its -Energy-Performance Bias (EPB) knob. +Energy-Performance Bias (EPB) knob. It is also possible to write a positive +integer value between 0 to 255, if the EPP feature is present. If the EPP +feature is not present, writing integer value to this attribute is not +supported. In this case, user can use + "/sys/devices/system/cpu/cpu*/power/energy_perf_bias" interface. [Note that tasks may by migrated from one CPU to another by the scheduler's load-balancing algorithm and if different energy vs performance hints are @@ -708,7 +723,7 @@ core (for the policies with other scaling governors). The ``ftrace`` interface can be used for low-level diagnostics of ``intel_pstate``. For example, to check how often the function to set a -P-state is called, the ``ftrace`` filter can be set to to +P-state is called, the ``ftrace`` filter can be set to :c:func:`intel_pstate_set_pstate`:: # cd /sys/kernel/debug/tracing/ diff --git a/Documentation/admin-guide/security-bugs.rst b/Documentation/admin-guide/security-bugs.rst index dcd6c93c7aac..c32eb786201c 100644 --- a/Documentation/admin-guide/security-bugs.rst +++ b/Documentation/admin-guide/security-bugs.rst @@ -21,11 +21,18 @@ understand and fix the security vulnerability. As it is with any bug, the more information provided the easier it will be to diagnose and fix. Please review the procedure outlined in -admin-guide/reporting-bugs.rst if you are unclear about what +:doc:`reporting-bugs` if you are unclear about what information is helpful. Any exploit code is very helpful and will not be released without consent from the reporter unless it has already been made public. +Please send plain text emails without attachments where possible. +It is much harder to have a context-quoted discussion about a complex +issue if all the details are hidden away in attachments. Think of it like a +:doc:`regular patch submission <../process/submitting-patches>` +(even if you don't have a patch yet): describe the problem and impact, list +reproduction steps, and follow it with a proposed fix, all in plain text. + Disclosure and embargoed information ------------------------------------ diff --git a/Documentation/admin-guide/spkguide.txt b/Documentation/admin-guide/spkguide.txt new file mode 100644 index 000000000000..3782f6a09e97 --- /dev/null +++ b/Documentation/admin-guide/spkguide.txt @@ -0,0 +1,1575 @@ + +The Speakup User's Guide +For Speakup 3.1.2 and Later +By Gene Collins +Updated by others +Last modified on Mon Sep 27 14:26:31 2010 +Document version 1.3 + +Copyright (c) 2005 Gene Collins +Copyright (c) 2008 Samuel Thibault +Copyright (c) 2009, 2010 the Speakup Team + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A +copy of the license is included in the section entitled "GNU Free +Documentation License". + +Preface + +The purpose of this document is to familiarize users with the user +interface to Speakup, a Linux Screen Reader. If you need instructions +for installing or obtaining Speakup, visit the web site at +http://linux-speakup.org/. Speakup is a set of patches to the standard +Linux kernel source tree. It can be built as a series of modules, or as +a part of a monolithic kernel. These details are beyond the scope of +this manual, but the user may need to be aware of the module +capabilities, depending on how your system administrator has installed +Speakup. If Speakup is built as a part of a monolithic kernel, and the +user is using a hardware synthesizer, then Speakup will be able to +provide speech access from the time the kernel is loaded, until the time +the system is shutdown. This means that if you have obtained Linux +installation media for a distribution which includes Speakup as a part +of its kernel, you will be able, as a blind person, to install Linux +with speech access unaided by a sighted person. Again, these details +are beyond the scope of this manual, but the user should be aware of +them. See the web site mentioned above for further details. + +1. Starting Speakup + +If your system administrator has installed Speakup to work with your +specific synthesizer by default, then all you need to do to use Speakup +is to boot your system, and Speakup should come up talking. This +assumes of course that your synthesizer is a supported hardware +synthesizer, and that it is either installed in or connected to your +system, and is if necessary powered on. + +It is possible, however, that Speakup may have been compiled into the +kernel with no default synthesizer. It is even possible that your +kernel has been compiled with support for some of the supported +synthesizers and not others. If you find that this is the case, and +your synthesizer is supported but not available, complain to the person +who compiled and installed your kernel. Or better yet, go to the web +site, and learn how to patch Speakup into your own kernel source, and +build and install your own kernel. + +If your kernel has been compiled with Speakup, and has no default +synthesizer set, or you would like to use a different synthesizer than +the default one, then you may issue the following command at the boot +prompt of your boot loader. + +linux speakup.synth=ltlk + +This command would tell Speakup to look for and use a LiteTalk or +DoubleTalk LT at boot up. You may replace the ltlk synthesizer keyword +with the keyword for whatever synthesizer you wish to use. The +speakup.synth parameter will accept the following keywords, provided +that support for the related synthesizers has been built into the +kernel. + +acntsa -- Accent SA +acntpc -- Accent PC +apollo -- Apollo +audptr -- Audapter +bns -- Braille 'n Speak +dectlk -- DecTalk Express (old and new, db9 serial only) +decext -- DecTalk (old) External +dtlk -- DoubleTalk PC +keypc -- Keynote Gold PC +ltlk -- DoubleTalk LT, LiteTalk, or external Tripletalk (db9 serial only) +spkout -- Speak Out +txprt -- Transport +dummy -- Plain text terminal + +Note: Speakup does * NOT * support usb connections! Speakup also does * +NOT * support the internal Tripletalk! + +Speakup does support two other synthesizers, but because they work in +conjunction with other software, they must be loaded as modules after +their related software is loaded, and so are not available at boot up. +These are as follows: + +decpc -- DecTalk PC (not available at boot up) +soft -- One of several software synthesizers (not available at boot up) + +See the sections on loading modules and software synthesizers later in +this manual for further details. It should be noted here that the +speakup.synth boot parameter will have no effect if Speakup has been +compiled as modules. In order for Speakup modules to be loaded during +the boot process, such action must be configured by your system +administrator. This will mean that you will hear some, but not all, of +the bootup messages. + +2. Basic operation + +Once you have booted the system, and if necessary, have supplied the +proper bootup parameter for your synthesizer, Speakup will begin +talking as soon as the kernel is loaded. In fact, it will talk a lot! +It will speak all the boot up messages that the kernel prints on the +screen during the boot process. This is because Speakup is not a +separate screen reader, but is actually built into the operating +system. Since almost all console applications must print text on the +screen using the kernel, and must get their keyboard input through the +kernel, they are automatically handled properly by Speakup. There are a +few exceptions, but we'll come to those later. + +Note: In this guide I will refer to the numeric keypad as the keypad. +This is done because the speakupmap.map file referred to later in this +manual uses the term keypad instead of numeric keypad. Also I'm lazy +and would rather only type one word. So keypad it is. Got it? Good. + +Most of the Speakup review keys are located on the keypad at the far +right of the keyboard. The numlock key should be off, in order for these +to work. If you toggle the numlock on, the keypad will produce numbers, +which is exactly what you want for spreadsheets and such. For the +purposes of this guide, you should have the numlock turned off, which is +its default state at bootup. + +You probably won't want to listen to all the bootup messages every time +you start your system, though it's a good idea to listen to them at +least once, just so you'll know what kind of information is available to +you during the boot process. You can always review these messages after +bootup with the command: + +dmesg | more + +In order to speed the boot process, and to silence the speaking of the +bootup messages, just press the keypad enter key. This key is located +in the bottom right corner of the keypad. Speakup will shut up and stay +that way, until you press another key. + +You can check to see if the boot process has completed by pressing the 8 +key on the keypad, which reads the current line. This also has the +effect of starting Speakup talking again, so you can press keypad enter +to silence it again if the boot process has not completed. + +When the boot process is complete, you will arrive at a "login" prompt. +At this point, you'll need to type in your user id and password, as +provided by your system administrator. You will hear Speakup speak the +letters of your user id as you type it, but not the password. This is +because the password is not displayed on the screen for security +reasons. This has nothing to do with Speakup, it's a Linux security +feature. + +Once you've logged in, you can run any Linux command or program which is +allowed by your user id. Normal users will not be able to run programs +which require root privileges. + +When you are running a program or command, Speakup will automatically +speak new text as it arrives on the screen. You can at any time silence +the speech with keypad enter, or use any of the Speakup review keys. + +Here are some basic Speakup review keys, and a short description of what +they do. + +keypad 1 -- read previous character +keypad 2 -- read current character (pressing keypad 2 twice rapidly will speak + the current character phonetically) +keypad 3 -- read next character +keypad 4 -- read previous word +keypad 5 -- read current word (press twice rapidly to spell the current word) +keypad 6 -- read next word +keypad 7 -- read previous line +keypad 8 -- read current line (press twice rapidly to hear how much the + text on the current line is indented) +keypad 9 -- read next line +keypad period -- speak current cursor position and announce current + virtual console + +It's also worth noting that the insert key on the keypad is mapped +as the speakup key. Instead of pressing and releasing this key, as you +do under DOS or Windows, you hold it like a shift key, and press other +keys in combination with it. For example, repeatedly holding keypad +insert, from now on called speakup, and keypad enter will toggle the +speaking of new text on the screen on and off. This is not the same as +just pressing keypad enter by itself, which just silences the speech +until you hit another key. When you hit speakup plus keypad enter, +Speakup will say, "You turned me off.", or "Hey, that's better." When +Speakup is turned off, no new text on the screen will be spoken. You +can still use the reading controls to review the screen however. + +3. Using the Speakup Help System + +In order to enter the Speakup help system, press and hold the speakup +key (remember that this is the keypad insert key), and press the f1 key. +You will hear the message: + +"Press space to leave help, cursor up or down to scroll, or a letter to +go to commands in list." + +When you press the spacebar to leave the help system, you will hear: + +"Leaving help." + +While you are in the Speakup help system, you can scroll up or down +through the list of available commands using the cursor keys. The list +of commands is arranged in alphabetical order. If you wish to jump to +commands in a specific part of the alphabet, you may press the letter of +the alphabet you wish to jump to. + +You can also just explore by typing keyboard keys. Pressing keys will +cause Speakup to speak the command associated with that key. For +example, if you press the keypad 8 key, you will hear: + +"Keypad 8 is line, say current." + +You'll notice that some commands do not have keys assigned to them. +This is because they are very infrequently used commands, and are also +accessible through the sys system. We'll discuss the sys system later +in this manual. + +You'll also notice that some commands have two keys assigned to them. +This is because Speakup has a built in set of alternative key bindings +for laptop users. The alternate speakup key is the caps lock key. You +can press and hold the caps lock key, while pressing an alternate +speakup command key to activate the command. On most laptops, the +numeric keypad is defined as the keys in the j k l area of the keyboard. + +There is usually a function key which turns this keypad function on and +off, and some other key which controls the numlock state. Toggling the +keypad functionality on and off can become a royal pain. So, Speakup +gives you a simple way to get at an alternative set of key mappings for +your laptop. These are also available by default on desktop systems, +because Speakup does not know whether it is running on a desktop or +laptop. So you may choose which set of Speakup keys to use. Some +system administrators may have chosen to compile Speakup for a desktop +system without this set of alternate key bindings, but these details are +beyond the scope of this manual. To use the caps lock for its normal +purpose, hold the shift key while toggling the caps lock on and off. We +should note here, that holding the caps lock key and pressing the z key +will toggle the alternate j k l keypad on and off. + +4. Keys and Their Assigned Commands + +In this section, we'll go through a list of all the speakup keys and +commands. You can also get a list of commands and assigned keys from +the help system. + +The following list was taken from the speakupmap.map file. Key +assignments are on the left of the equal sign, and the associated +Speakup commands are on the right. The designation "spk" means to press +and hold the speakup key, a.k.a. keypad insert, a.k.a. caps lock, while +pressing the other specified key. + +spk key_f9 = punc_level_dec +spk key_f10 = punc_level_inc +spk key_f11 = reading_punc_dec +spk key_f12 = reading_punc_inc +spk key_1 = vol_dec +spk key_2 = vol_inc +spk key_3 = pitch_dec +spk key_4 = pitch_inc +spk key_5 = rate_dec +spk key_6 = rate_inc +key_kpasterisk = toggle_cursoring +spk key_kpasterisk = speakup_goto +spk key_f1 = speakup_help +spk key_f2 = set_win +spk key_f3 = clear_win +spk key_f4 = enable_win +spk key_f5 = edit_some +spk key_f6 = edit_most +spk key_f7 = edit_delim +spk key_f8 = edit_repeat +shift spk key_f9 = edit_exnum + key_kp7 = say_prev_line +spk key_kp7 = left_edge + key_kp8 = say_line +double key_kp8 = say_line_indent +spk key_kp8 = say_from_top + key_kp9 = say_next_line +spk key_kp9 = top_edge + key_kpminus = speakup_parked +spk key_kpminus = say_char_num + key_kp4 = say_prev_word +spk key_kp4 = say_from_left + key_kp5 = say_word +double key_kp5 = spell_word +spk key_kp5 = spell_phonetic + key_kp6 = say_next_word +spk key_kp6 = say_to_right + key_kpplus = say_screen +spk key_kpplus = say_win + key_kp1 = say_prev_char +spk key_kp1 = right_edge + key_kp2 = say_char +spk key_kp2 = say_to_bottom +double key_kp2 = say_phonetic_char + key_kp3 = say_next_char +spk key_kp3 = bottom_edge + key_kp0 = spk_key + key_kpdot = say_position +spk key_kpdot = say_attributes +key_kpenter = speakup_quiet +spk key_kpenter = speakup_off +key_sysrq = speech_kill + key_kpslash = speakup_cut +spk key_kpslash = speakup_paste +spk key_pageup = say_first_char +spk key_pagedown = say_last_char +key_capslock = spk_key + spk key_z = spk_lock +key_leftmeta = spk_key +ctrl spk key_0 = speakup_goto +spk key_u = say_prev_line +spk key_i = say_line +double spk key_i = say_line_indent +spk key_o = say_next_line +spk key_minus = speakup_parked +shift spk key_minus = say_char_num +spk key_j = say_prev_word +spk key_k = say_word +double spk key_k = spell_word +spk key_l = say_next_word +spk key_m = say_prev_char +spk key_comma = say_char +double spk key_comma = say_phonetic_char +spk key_dot = say_next_char +spk key_n = say_position + ctrl spk key_m = left_edge + ctrl spk key_y = top_edge + ctrl spk key_dot = right_edge +ctrl spk key_p = bottom_edge +spk key_apostrophe = say_screen +spk key_h = say_from_left +spk key_y = say_from_top +spk key_semicolon = say_to_right +spk key_p = say_to_bottom +spk key_slash = say_attributes + spk key_enter = speakup_quiet + ctrl spk key_enter = speakup_off + spk key_9 = speakup_cut +spk key_8 = speakup_paste +shift spk key_m = say_first_char + ctrl spk key_semicolon = say_last_char + +5. The Speakup Sys System + +The Speakup screen reader also creates a speakup subdirectory as a part +of the sys system. + +As a convenience, run as root + +ln -s /sys/accessibility/speakup /speakup + +to directly access speakup parameters from /speakup. +You can see these entries by typing the command: + +ls -1 /speakup/* + +If you issue the above ls command, you will get back something like +this: + +/speakup/attrib_bleep +/speakup/bell_pos +/speakup/bleep_time +/speakup/bleeps +/speakup/cursor_time +/speakup/delimiters +/speakup/ex_num +/speakup/key_echo +/speakup/keymap +/speakup/no_interrupt +/speakup/punc_all +/speakup/punc_level +/speakup/punc_most +/speakup/punc_some +/speakup/reading_punc +/speakup/repeats +/speakup/say_control +/speakup/say_word_ctl +/speakup/silent +/speakup/spell_delay +/speakup/synth +/speakup/synth_direct +/speakup/version + +/speakup/i18n: +announcements +characters +chartab +colors +ctl_keys +formatted +function_names +key_names +states + +/speakup/soft: +caps_start +caps_stop +delay_time +direct +freq +full_time +jiffy_delta +pitch +inflection +punct +rate +tone +trigger_time +voice +vol + +Notice the two subdirectories of /speakup: /speakup/i18n and +/speakup/soft. +The i18n subdirectory is described in a later section. +The files under /speakup/soft represent settings that are specific to the +driver for the software synthesizer. If you use the LiteTalk, your +synthesizer-specific settings would be found in /speakup/ltlk. In other words, +a subdirectory named /speakup/KWD is created to hold parameters specific +to the device whose keyword is KWD. +These parameters include volume, rate, pitch, and others. + +In addition to using the Speakup hot keys to change such things as +volume, pitch, and rate, you can also echo values to the appropriate +entry in the /speakup directory. This is very useful, since it +lets you control Speakup parameters from within a script. How you +would write such scripts is somewhat beyond the scope of this manual, +but I will include a couple of simple examples here to give you a +general idea of what such scripts can do. + +Suppose for example, that you wanted to control both the punctuation +level and the reading punctuation level at the same time. For +simplicity, we'll call them punc0, punc1, punc2, and punc3. The scripts +might look something like this: + +#!/bin/bash +# punc0 +# set punc and reading punc levels to 0 +echo 0 >/speakup/punc_level +echo 0 >/speakup/reading_punc +echo Punctuation level set to 0. + +#!/bin/bash +# punc1 +# set punc and reading punc levels to 1 +echo 1 >/speakup/punc_level +echo 1 >/speakup/reading_punc +echo Punctuation level set to 1. + +#!/bin/bash +# punc2 +# set punc and reading punc levels to 2 +echo 2 >/speakup/punc_level +echo 2 >/speakup/reading_punc +echo Punctuation level set to 2. + +#!/bin/bash +# punc3 +# set punc and reading punc levels to 3 +echo 3 >/speakup/punc_level +echo 3 >/speakup/reading_punc +echo Punctuation level set to 3. + +If you were to store these four small scripts in a directory in your +path, perhaps /usr/local/bin, and set the permissions to 755 with the +chmod command, then you could change the default reading punc and +punctuation levels at the same time by issuing just one command. For +example, if you were to execute the punc3 command at your shell prompt, +then the reading punc and punc level would both get set to 3. + +I should note that the above scripts were written to work with bash, but +regardless of which shell you use, you should be able to do something +similar. + +The Speakup sys system also has another interesting use. You can echo +Speakup parameters into the sys system in a script during system +startup, and speakup will return to your preferred parameters every time +the system is rebooted. + +Most of the Speakup sys parameters can be manipulated by a regular user +on the system. However, there are a few parameters that are dangerous +enough that they should only be manipulated by the root user on your +system. There are even some parameters that are read only, and cannot +be written to at all. For example, the version entry in the Speakup +sys system is read only. This is because there is no reason for a user +to tamper with the version number which is reported by Speakup. Doing +an ls -l on /speakup/version will return this: + +-r--r--r-- 1 root root 0 Mar 21 13:46 /speakup/version + +As you can see, the version entry in the Speakup sys system is read +only, is owned by root, and belongs to the root group. Doing a cat of +/speakup/version will display the Speakup version number, like +this: + +cat /speakup/version +Speakup v-2.00 CVS: Thu Oct 21 10:38:21 EDT 2004 +synth dtlk version 1.1 + +The display shows the Speakup version number, along with the version +number of the driver for the current synthesizer. + +Looking at entries in the Speakup sys system can be useful in many +ways. For example, you might wish to know what level your volume is set +at. You could type: + +cat /speakup/KWD/vol +# Replace KWD with the keyword for your synthesizer, E.G., ltlk for LiteTalk. +5 + +The number five which comes back is the level at which the synthesizer +volume is set at. + +All the entries in the Speakup sys system are readable, some are +writable by root only, and some are writable by everyone. Unless you +know what you are doing, you should probably leave the ones that are +writable by root only alone. Most of the names are self explanatory. +Vol for controlling volume, pitch for pitch, inflection for pitch range, rate +for controlling speaking rate, etc. If you find one you aren't sure about, you +can post a query on the Speakup list. + +6. Changing Synthesizers + +It is possible to change to a different synthesizer while speakup is +running. In other words, it is not necessary to reboot the system +in order to use a different synthesizer. You can simply echo the +synthesizer keyword to the /speakup/synth sys entry. +Depending on your situation, you may wish to echo none to the synth +sys entry, to disable speech while one synthesizer is disconnected and +a second one is connected in its place. Then echo the keyword for the +new synthesizer into the synth sys entry in order to start speech +with the newly connected synthesizer. See the list of synthesizer +keywords in section 1 to find the keyword which matches your synth. + +7. Loading modules + +As mentioned earlier, Speakup can either be completely compiled into the +kernel, with the exception of the help module, or it can be compiled as +a series of modules. When compiled as modules, Speakup will only be +able to speak some of the bootup messages if your system administrator +has configured the system to load the modules at boo time. The modules +can be loaded after the file systems have been checked and mounted, or +from an initrd. There is a third possibility. Speakup can be compiled +with some components built into the kernel, and others as modules. As +we'll see in the next section, this is particularly useful when you are +working with software synthesizers. + +If Speakup is completely compiled as modules, then you must use the +modprobe command to load Speakup. You do this by loading the module for +the synthesizer driver you wish to use. The driver modules are all +named speakup_<keyword>, where <keyword> is the keyword for the +synthesizer you want. So, in order to load the driver for the DecTalk +Express, you would type the following command: + +modprobe speakup_dectlk + +Issuing this command would load the DecTalk Express driver and all other +related Speakup modules necessary to get Speakup up and running. + +To completely unload Speakup, again presuming that it is entirely built +as modules, you would give the command: + +modprobe -r speakup_dectlk + +The above command assumes you were running a DecTalk Express. If you +were using a different synth, then you would substitute its keyword in +place of dectlk. + +If you have multiple drivers loaded, you need to unload all of them, in +order to completely unload Speakup. +For example, if you have loaded both the dectlk and ltlk drivers, use the +command: +modprobe -r speakup_dectlk speakup_ltlk + +You cannot unload the driver for software synthesizers when a user-space +daemon is using /dev/softsynth. First, kill the daemon. Next, remove +the driver with the command: +modprobe -r speakup_soft + +Now, suppose we have a situation where the main Speakup component +is built into the kernel, and some or all of the drivers are built as +modules. Since the main part of Speakup is compiled into the kernel, a +partial Speakup sys system has been created which we can take advantage +of by simply echoing the synthesizer keyword into the +/speakup/synth sys entry. This will cause the kernel to +automatically load the appropriate driver module, and start Speakup +talking. To switch to another synth, just echo a new keyword to the +synth sys entry. For example, to load the DoubleTalk LT driver, +you would type: + +echo ltlk >/speakup/synth + +You can use the modprobe -r command to unload driver modules, regardless +of whether the main part of Speakup has been built into the kernel or +not. + +8. Using Software Synthesizers + +Using a software synthesizer requires that some other software be +installed and running on your system. For this reason, software +synthesizers are not available for use at bootup, or during a system +installation process. +There are two freely-available solutions for software speech: Espeakup and +Speech Dispatcher. +These are described in subsections 8.1 and 8.2, respectively. + +During the rest of this section, we assume that speakup_soft is either +built in to your kernel, or loaded as a module. + +If your system does not have udev installed , before you can use a +software synthesizer, you must have created the /dev/softsynth device. +If you have not already done so, issue the following commands as root: + +cd /dev +mknod softsynth c 10 26 + +While we are at it, we might just as well create the /dev/synth device, +which can be used to let user space programs send information to your +synthesizer. To create /dev/synth, change to the /dev directory, and +issue the following command as root: + +mknod synth c 10 25 + +of both. + +8.1. Espeakup + +Espeakup is a connector between Speakup and the eSpeak software synthesizer. +Espeakup may already be available as a package for your distribution +of Linux. If it is not packaged, you need to install it manually. +You can find it in the contrib/ subdirectory of the Speakup sources. +The filename is espeakup-$VERSION.tar.bz2, where $VERSION +depends on the current release of Espeakup. The Speakup 3.1.2 source +ships with version 0.71 of Espeakup. +The README file included with the Espeakup sources describes the process +of manual installation. + +Assuming that Espeakup is installed, either by the user or by the distributor, +follow these steps to use it. + +Tell Speakup to use the "soft driver: +echo soft > /speakup/synth + +Finally, start the espeakup program. There are two ways to do it. +Both require root privileges. + +If Espeakup was installed as a package for your Linux distribution, +you probably have a distribution-specific script that controls the operation +of the daemon. Look for a file named espeakup under /etc/init.d or +/etc/rc.d. Execute the following command with root privileges: +/etc/init.d/espeakup start +Replace init.d with rc.d, if your distribution uses scripts located under +/etc/rc.d. +Your distribution will also have a procedure for starting daemons at +boot-time, so it is possible to have software speech as soon as user-space +daemons are started by the bootup scripts. +These procedures are not described in this document. + +If you built Espeakup manually, the "make install" step placed the binary +under /usr/bin. +Run the following command as root: +/usr/bin/espeakup +Espeakup should start speaking. + +8.2. Speech Dispatcher + +For this option, you must have a package called +Speech Dispatcher running on your system, and it must be configured to +work with one of its supported software synthesizers. + +Two open source synthesizers you might use are Flite and Festival. You +might also choose to purchase the Software DecTalk from Fonix Sales Inc. +If you run a google search for Fonix, you'll find their web site. + +You can obtain a copy of Speech Dispatcher from free(b)soft at +http://www.freebsoft.org/. Follow the installation instructions that +come with Speech Dispatcher in order to install and configure Speech +Dispatcher. You can check out the web site for your Linux distribution +in order to get a copy of either Flite or Festival. Your Linux +distribution may also have a precompiled Speech Dispatcher package. + +Once you've installed, configured, and tested Speech Dispatcher with your +chosen software synthesizer, you still need one more piece of software +in order to make things work. You need a package called speechd-up. +You get it from the free(b)soft web site mentioned above. After you've +compiled and installed speechd-up, you are almost ready to begin using +your software synthesizer. + +Now you can begin using your software synthesizer. In order to do so, +echo the soft keyword to the synth sys entry like this: + +echo soft >/speakup/synth + +Next run the speechd_up command like this: + +speechd_up & + +Your synth should now start talking, and you should be able to adjust +the pitch, rate, etc. + +9. Using The DecTalk PC Card + +The DecTalk PC card is an ISA card that is inserted into one of the ISA +slots in your computer. It requires that the DecTalk PC software be +installed on your computer, and that the software be loaded onto the +Dectalk PC card before it can be used. + +You can get the dec_pc.tgz file from the linux-speakup.org site. The +dec_pc.tgz file is in the ~ftp/pub/linux/speakup directory. + +After you have downloaded the dec_pc.tgz file, untar it in your home +directory, and read the Readme file in the newly created dec_pc +directory. + +The easiest way to get the software working is to copy the entire dec_pc +directory into /user/local/lib. To do this, su to root in your home +directory, and issue the command: + +cp dec_pc /usr/local/lib + +You will need to copy the dtload command from the dec_pc directory to a +directory in your path. Either /usr/bin or /usr/local/bin is a good +choice. + +You can now run the dtload command in order to load the DecTalk PC +software onto the card. After you have done this, echo the decpc +keyword to the synth entry in the sys system like this: + +echo decpc >/speakup/synth + +Your DecTalk PC should start talking, and then you can adjust the pitch, +rate, volume, voice, etc. The voice entry in the Speakup sys system +will accept a number from 0 through 7 for the DecTalk PC synthesizer, +which will give you access to some of the DecTalk voices. + +10. Using Cursor Tracking + +In Speakup version 2.0 and later, cursor tracking is turned on by +default. This means that when you are using an editor, Speakup will +automatically speak characters as you move left and right with the +cursor keys, and lines as you move up and down with the cursor keys. +This is the traditional sort of cursor tracking. +Recent versions of Speakup provide two additional ways to control the +text that is spoken when the cursor is moved: +"highlight tracking" and "read window." +They are described later in this section. +Sometimes, these modes get in your way, so you can disable cursor tracking +altogether. + +You may select among the various forms of cursor tracking using the keypad +asterisk key. +Each time you press this key, a new mode is selected, and Speakup speaks +the name of the new mode. The names for the four possible states of cursor +tracking are: "cursoring on", "highlight tracking", "read window", +and "cursoring off." The keypad asterisk key moves through the list of +modes in a circular fashion. + +If highlight tracking is enabled, Speakup tracks highlighted text, +rather than the cursor itself. When you move the cursor with the arrow keys, +Speakup speaks the currently highlighted information. +This is useful when moving through various menus and dialog boxes. +If cursor tracking isn't helping you while navigating a menu, +try highlight tracking. + +With the "read window" variety of cursor tracking, you can limit the text +that Speakup speaks by specifying a window of interest on the screen. +See section 15 for a description of the process of defining windows. +When you move the cursor via the arrow keys, Speakup only speaks +the contents of the window. This is especially helpful when you are hearing +superfluous speech. Consider the following example. + +Suppose that you are at a shell prompt. You use bash, and you want to +explore your command history using the up and down arrow keys. If you +have enabled cursor tracking, you will hear two pieces of information. +Speakup speaks both your shell prompt and the current entry from the +command history. You may not want to hear the prompt repeated +each time you move, so you can silence it by specifying a window. Find +the last line of text on the screen. Clear the current window by pressing +the key combination speakup f3. Use the review cursor to find the first +character that follows your shell prompt. Press speakup + f2 twice, to +define a one-line window. The boundaries of the window are the +character following the shell prompt and the end of the line. Now, cycle +through the cursor tracking modes using keypad asterisk, until Speakup +says "read window." Move through your history using your arrow keys. +You will notice that Speakup no longer speaks the redundant prompt. + +Some folks like to turn cursor tracking off while they are using the +lynx web browser. You definitely want to turn cursor tracking off when +you are using the alsamixer application. Otherwise, you won't be able +to hear your mixer settings while you are using the arrow keys. + +11. Cut and Paste + +One of Speakup's more useful features is the ability to cut and paste +text on the screen. This means that you can capture information from a +program, and paste that captured text into a different place in the +program, or into an entirely different program, which may even be +running on a different console. + +For example, in this manual, we have made references to several web +sites. It would be nice if you could cut and paste these urls into your +web browser. Speakup does this quite nicely. Suppose you wanted to +past the following url into your browser: + +http://linux-speakup.org/ + +Use the speakup review keys to position the reading cursor on the first +character of the above url. When the reading cursor is in position, +press the keypad slash key once. Speakup will say, "mark". Next, +position the reading cursor on the rightmost character of the above +url. Press the keypad slash key once again to actually cut the text +from the screen. Speakup will say, "cut". Although we call this +cutting, Speakup does not actually delete the cut text from the screen. +It makes a copy of the text in a special buffer for later pasting. + +Now that you have the url cut from the screen, you can paste it into +your browser, or even paste the url on a command line as an argument to +your browser. + +Suppose you want to start lynx and go to the Speakup site. + +You can switch to a different console with the alt left and right +arrows, or you can switch to a specific console by typing alt and a +function key. These are not Speakup commands, just standard Linux +console capabilities. + +Once you've changed to an appropriate console, and are at a shell prompt, +type the word lynx, followed by a space. Now press and hold the speakup +key, while you type the keypad slash character. The url will be pasted +onto the command line, just as though you had typed it in. Press the +enter key to execute the command. + +The paste buffer will continue to hold the cut information, until a new +mark and cut operation is carried out. This means you can paste the cut +information as many times as you like before doing another cut +operation. + +You are not limited to cutting and pasting only one line on the screen. +You can also cut and paste rectangular regions of the screen. Just +position the reading cursor at the top left corner of the text to be +cut, mark it with the keypad slash key, then position the reading cursor +at the bottom right corner of the region to be cut, and cut it with the +keypad slash key. + +12. Changing the Pronunciation of Characters + +Through the /speakup/i18n/characters sys entry, Speakup gives you the +ability to change how Speakup pronounces a given character. You could, +for example, change how some punctuation characters are spoken. You can +even change how Speakup will pronounce certain letters. + +You may, for example, wish to change how Speakup pronounces the z +character. The author of Speakup, Kirk Reiser, is Canadian, and thus +believes that the z should be pronounced zed. If you are an American, +you might wish to use the zee pronunciation instead of zed. You can +change the pronunciation of both the upper and lower case z with the +following two commands: + +echo 90 zee >/speakup/characters +echo 122 zee >/speakup/characters + +Let's examine the parts of the two previous commands. They are issued +at the shell prompt, and could be placed in a startup script. + +The word echo tells the shell that you want to have it display the +string of characters that follow the word echo. If you were to just +type: + +echo hello. + +You would get the word hello printed on your screen as soon as you +pressed the enter key. In this case, we are echoing strings that we +want to be redirected into the sys system. + +The numbers 90 and 122 in the above echo commands are the ascii numeric +values for the upper and lower case z, the characters we wish to change. + +The string zee is the pronunciation that we want Speakup to use for the +upper and lower case z. + +The > symbol redirects the output of the echo command to a file, just +like in DOS, or at the Windows command prompt. + +And finally, /speakup/i18n/characters is the file entry in the sys system +where we want the output to be directed. Speakup looks at the numeric +value of the character we want to change, and inserts the pronunciation +string into an internal table. + +You can look at the whole table with the following command: + +cat /speakup/i18n/characters + +Speakup will then print out the entire character pronunciation table. I +won't display it here, but leave you to look at it at your convenience. + +13. Mapping Keys + +Speakup has the capability of allowing you to assign or "map" keys to +internal Speakup commands. This section necessarily assumes you have a +Linux kernel source tree installed, and that it has been patched and +configured with Speakup. How you do this is beyond the scope of this +manual. For this information, visit the Speakup web site at +http://linux-speakup.org/. The reason you'll need the kernel source +tree patched with Speakup is that the genmap utility you'll need for +processing keymaps is in the +/usr/src/linux-<version_number>/drivers/char/speakup directory. The +<version_number> in the above directory path is the version number of +the Linux source tree you are working with. + +So ok, you've gone off and gotten your kernel source tree, and patched +and configured it. Now you can start manipulating keymaps. + +You can either use the +/usr/src/linux-<version_number>/drivers/char/speakup/speakupmap.map file +included with the Speakup source, or you can cut and paste the copy in +section 4 into a separate file. If you use the one in the Speakup +source tree, make sure you make a backup of it before you start making +changes. You have been warned! + +Suppose that you want to swap the key assignments for the Speakup +say_last_char and the Speakup say_first_char commands. The +speakupmap.map lists the key mappings for these two commands as follows: + +spk key_pageup = say_first_char +spk key_pagedown = say_last_char + +You can edit your copy of the speakupmap.map file and swap the command +names on the right side of the = (equals) sign. You did make a backup, +right? The new keymap lines would look like this: + +spk key_pageup = say_last_char +spk key_pagedown = say_first_char + +After you edit your copy of the speakupmap.map file, save it under a new +file name, perhaps newmap.map. Then exit your editor and return to the +shell prompt. + +You are now ready to load your keymap with your swapped key assignments. + Assuming that you saved your new keymap as the file newmap.map, you +would load your keymap into the sys system like this: + +/usr/src/linux-<version_number>/drivers/char/speakup/genmap newmap.map +>/speakup/keymap + +Remember to substitute your kernel version number for the +<version_number> in the above command. Also note that although the +above command wrapped onto two lines in this document, you should type +it all on one line. + +Your say first and say last characters should now be swapped. Pressing +speakup pagedown should read you the first non-whitespace character on +the line your reading cursor is in, and pressing speakup pageup should +read you the last character on the line your reading cursor is in. + +You should note that these new mappings will only stay in effect until +you reboot, or until you load another keymap. + +One final warning. If you try to load a partial map, you will quickly +find that all the mappings you didn't include in your file got deleted +from the working map. Be extremely careful, and always make a backup! +You have been warned! + +14. Internationalizing Speakup + +Speakup indicates various conditions to the user by speaking messages. +For instance, when you move to the left edge of the screen with the +review keys, Speakup says, "left." +Prior to version 3.1.0 of Speakup, all of these messages were in English, +and they could not be changed. If you used a non-English synthesizer, +you still heard English messages, such as "left" and "cursoring on." +In version 3.1.0 or higher, one may load translations for the various +messages via the /sys filesystem. + +The directory /speakup/i18n contains several collections of messages. +Each group of messages is stored in its own file. +The following section lists all of these files, along with a brief description +of each. + +14.1. Files Under the i18n Subdirectory + +* announcements: +This file contains various general announcements, most of which cannot +be categorized. You will find messages such as "You killed Speakup", +"I'm alive", "leaving help", "parked", "unparked", and others. +You will also find the names of the screen edges and cursor tracking modes +here. + +* characters: +See section 12 for a description of this file. + +* chartab: +See section 12. Unlike the rest of the files in the i18n subdirectory, +this one does not contain messages to be spoken. + +* colors: +When you use the "say attributes" function, Speakup says the name of the +foreground and background colors. These names come from the i18n/colors +file. + +* ctl_keys: +Here, you will find names of control keys. These are used with Speakup's +say_control feature. + +* formatted: +This group of messages contains embedded formatting codes, to specify +the type and width of displayed data. If you change these, you must +preserve all of the formatting codes, and they must appear in the order +used by the default messages. + +* function_names: +Here, you will find a list of names for Speakup functions. These are used +by the help system. For example, suppose that you have activated help mode, +and you pressed keypad 3. Speakup says: +"keypad 3 is character, say next." +The message "character, say next" names a Speakup function, and it +comes from this function_names file. + +* key_names: +Again, key_names is used by Speakup's help system. In the previous +example, Speakup said that you pressed "keypad 3." +This name came from the key_names file. + +* states: +This file contains names for key states. +Again, these are part of the help system. For instance, if you had pressed +speakup + keypad 3, you would hear: +"speakup keypad 3 is go to bottom edge." +The speakup key is depressed, so the name of the key state is speakup. +This part of the message comes from the states collection. + +14.2. Loading Your Own Messages + +The files under the i18n subdirectory all follow the same format. +They consist of lines, with one message per line. +Each message is represented by a number, followed by the text of the message. +The number is the position of the message in the given collection. +For example, if you view the file /speakup/i18n/colors, you will see the +following list: + +0 black +1 blue +2 green +3 cyan +4 red +5 magenta +6 yellow +7 white +8 grey + +You can change one message, or you can change a whole group. +To load a whole collection of messages from a new source, simply use +the cp command: +cp ~/my_colors /speakup/i18n/colors +You can change an individual message with the echo command, +as shown in the following example. + +The Spanish name for the color blue is azul. +Looking at the colors file, we see that the name "blue" is at position 1 +within the colors group. Let's change blue to azul: +echo '1 azul' > /speakup/i18n/colors +The next time that Speakup says message 1 from the colors group, it will +say "azul", rather than "blue." + +In the future, translations into various languages will be made available, +and most users will just load the files necessary for their language. + +14.3. No Support for Non-Western-European Languages + +As of the current release, Speakup only supports Western European languages. +Support for the extended characters used by languages outside of the Western +European family of languages is a work in progress. + +15. Using Speakup's Windowing Capability + +Speakup has the capability of defining and manipulating windows on the +screen. Speakup uses the term "Window", to mean a user defined area of +the screen. The key strokes for defining and manipulating Speakup +windows are as follows: + +speakup + f2 -- Set the bounds of the window. +Speakup + f3 -- clear the current window definition. +speakup + f4 -- Toggle window silence on and off. +speakup + keypad plus -- Say the currently defined window. + +These capabilities are useful for tracking a certain part of the screen +without rereading the whole screen, or for silencing a part of the +screen that is constantly changing, such as a clock or status line. + +There is no way to save these window settings, and you can only have one +window defined for each virtual console. There is also no way to have +windows automatically defined for specific applications. + +In order to define a window, use the review keys to move your reading +cursor to the beginning of the area you want to define. Then press +speakup + f2. Speakup will tell you that the window starts at the +indicated row and column position. Then move the reading cursor to the +end of the area to be defined as a window, and press speakup + f2 again. + If there is more than one line in the window, Speakup will tell you +that the window ends at the indicated row and column position. If there +is only one line in the window, then Speakup will tell you that the +window is the specified line on the screen. If you are only defining a +one line window, you can just press speakup + f2 twice after placing the +reading cursor on the line you want to define as a window. It is not +necessary to position the reading cursor at the end of the line in order +to define the whole line as a window. + +16. Tools for Controlling Speakup + +The speakup distribution includes extra tools (in the tools directory) +which were written to make speakup easier to use. This section will +briefly describe the use of these tools. + +16.1. Speakupconf + +speakupconf began life as a contribution from Steve Holmes, a member of +the speakup community. We would like to thank him for his work on the +early versions of this project. + +This script may be installed as part of your linux distribution, but if +it isn't, the recommended places to put it are /usr/local/bin or +/usr/bin. This script can be run by any user, so it does not require +root privileges. + +Speakupconf allows you to save and load your Speakup settings. It works +by reading and writing the /sys files described above. + +The directory that speakupconf uses to store your settings depends on +whether it is run from the root account. If you execute speakupconf as +root, it uses the directory /etc/speakup. Otherwise, it uses the directory +~/.speakup, where ~ is your home directory. +Anyone who needs to use Speakup from your console can load his own custom +settings with this script. + +speakupconf takes one required argument: load or save. +Use the command +speakupconf save +to save your Speakup settings, and +speakupconf load +to load them into Speakup. +A second argument may be specified to use an alternate directory to +load or save the speakup parameters. + +16.2. Talkwith + +Charles Hallenbeck, another member of the speakup community, wrote the +initial versions of this script, and we would also like to thank him for +his work on it. + +This script needs root privileges to run, so if it is not installed as +part of your linux distribution, the recommended places to install it +are /usr/local/sbin or /usr/sbin. + +Talkwith allows you to switch synthesizers on the fly. It takes a synthesizer +name as an argument. For instance, +talkwith dectlk +causes Speakup to use the DecTalk Express. If you wish to switch to a +software synthesizer, you must also indicate which daemon you wish to +use. There are two possible choices: +spd and espeakup. spd is an abbreviation for speechd-up. +If you wish to use espeakup for software synthesis, give the command +talkwith soft espeakup +To use speechd-up, type: +talkwith soft spd +Any arguments that follow the name of the daemon are passed to the daemon +when it is invoked. For instance: +talkwith espeakup --default-voice=fr +causes espeakup to use the French voice. +Note that talkwith must always be executed with root privileges. + +Talkwith does not attempt to load your settings after the new +synthesizer is activated. You can use speakupconf to load your settings +if desired. + + GNU Free Documentation License + Version 1.2, November 2002 + + + Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + +0. PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document "free" in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +1. APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The "Document", below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as "you". You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A "Secondary Section" is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (Thus, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The "Invariant Sections" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The "Cover Texts" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A "Transparent" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not "Transparent" is called "Opaque". + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The "Title Page" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section "Entitled XYZ" means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as "Acknowledgements", +"Dedications", "Endorsements", or "History".) To "Preserve the Title" +of such a section when you modify the Document means that it remains a +section "Entitled XYZ" according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + + +2. VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +3. COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +4. MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +A. Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +B. List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement. +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. +D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +F. Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +H. Include an unaltered copy of this License. +I. Preserve the section Entitled "History", Preserve its Title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section Entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section all + the substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. +N. Do not retitle any existing section to be Entitled "Endorsements" + or to conflict in title with any Invariant Section. +O. Preserve any Warranty Disclaimers. + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +5. COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled "History" +in the various original documents, forming one section Entitled +"History"; likewise combine any sections Entitled "Acknowledgements", +and any sections Entitled "Dedications". You must delete all sections +Entitled "Endorsements". + + +6. COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +7. AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an "aggregate" if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + + +8. TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled "Acknowledgements", +"Dedications", or "History", the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + + +9. TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +10. FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +https://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + + Copyright (c) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +The End. diff --git a/Documentation/admin-guide/sysctl/fs.rst b/Documentation/admin-guide/sysctl/fs.rst index 2a45119e3331..f48277a0a850 100644 --- a/Documentation/admin-guide/sysctl/fs.rst +++ b/Documentation/admin-guide/sysctl/fs.rst @@ -261,7 +261,7 @@ directories like /tmp. The common method of exploitation of this flaw is to cross privilege boundaries when following a given symlink (i.e. a root process follows a symlink belonging to another user). For a likely incomplete list of hundreds of examples across the years, please see: -http://cve.mitre.org/cgi-bin/cvekey.cgi?keyword=/tmp +https://cve.mitre.org/cgi-bin/cvekey.cgi?keyword=/tmp When set to "0", symlink following behavior is unrestricted. diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 83acf5025488..2ae9669eb22c 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -235,7 +235,7 @@ This toggle indicates whether unprivileged users are prevented from using ``dmesg(8)`` to view messages from the kernel's log buffer. When ``dmesg_restrict`` is set to 0 there are no restrictions. -When ``dmesg_restrict`` is set set to 1, users must have +When ``dmesg_restrict`` is set to 1, users must have ``CAP_SYSLOG`` to use ``dmesg(8)``. The kernel config option ``CONFIG_SECURITY_DMESG_RESTRICT`` sets the @@ -335,8 +335,8 @@ Path for the hotplug policy agent. Default value is "``/sbin/hotplug``". -hung_task_all_cpu_backtrace: -================ +hung_task_all_cpu_backtrace +=========================== If this option is set, the kernel will send an NMI to all CPUs to dump their backtraces when a hung task is detected. This file shows up if @@ -646,8 +646,8 @@ rate for each task. scanned for a given scan. -oops_all_cpu_backtrace: -================ +oops_all_cpu_backtrace +====================== If this option is set, the kernel will send an NMI to all CPUs to dump their backtraces when an oops event occurs. It should be used as a last @@ -996,6 +996,38 @@ pty See Documentation/filesystems/devpts.rst. +random +====== + +This is a directory, with the following entries: + +* ``boot_id``: a UUID generated the first time this is retrieved, and + unvarying after that; + +* ``entropy_avail``: the pool's entropy count, in bits; + +* ``poolsize``: the entropy pool size, in bits; + +* ``urandom_min_reseed_secs``: obsolete (used to determine the minimum + number of seconds between urandom pool reseeding). + +* ``uuid``: a UUID generated every time this is retrieved (this can + thus be used to generate UUIDs at will); + +* ``write_wakeup_threshold``: when the entropy count drops below this + (as a number of bits), processes waiting to write to ``/dev/random`` + are woken up. + +If ``drivers/char/random.c`` is built with ``ADD_INTERRUPT_BENCH`` +defined, these additional entries are present: + +* ``add_interrupt_avg_cycles``: the average number of cycles between + interrupts used to feed the pool; + +* ``add_interrupt_avg_deviation``: the standard deviation seen on the + number of cycles between interrupts used to feed the pool. + + randomize_va_space ================== @@ -1062,6 +1094,60 @@ Enables/disables scheduler statistics. Enabling this feature incurs a small amount of overhead in the scheduler but is useful for debugging and performance tuning. +sched_util_clamp_min: +===================== + +Max allowed *minimum* utilization. + +Default value is 1024, which is the maximum possible value. + +It means that any requested uclamp.min value cannot be greater than +sched_util_clamp_min, i.e., it is restricted to the range +[0:sched_util_clamp_min]. + +sched_util_clamp_max: +===================== + +Max allowed *maximum* utilization. + +Default value is 1024, which is the maximum possible value. + +It means that any requested uclamp.max value cannot be greater than +sched_util_clamp_max, i.e., it is restricted to the range +[0:sched_util_clamp_max]. + +sched_util_clamp_min_rt_default: +================================ + +By default Linux is tuned for performance. Which means that RT tasks always run +at the highest frequency and most capable (highest capacity) CPU (in +heterogeneous systems). + +Uclamp achieves this by setting the requested uclamp.min of all RT tasks to +1024 by default, which effectively boosts the tasks to run at the highest +frequency and biases them to run on the biggest CPU. + +This knob allows admins to change the default behavior when uclamp is being +used. In battery powered devices particularly, running at the maximum +capacity and frequency will increase energy consumption and shorten the battery +life. + +This knob is only effective for RT tasks which the user hasn't modified their +requested uclamp.min value via sched_setattr() syscall. + +This knob will not escape the range constraint imposed by sched_util_clamp_min +defined above. + +For example if + + sched_util_clamp_min_rt_default = 800 + sched_util_clamp_min = 600 + +Then the boost will be clamped to 600 because 800 is outside of the permissible +range of [0:600]. This could happen for instance if a powersave mode will +restrict all boosts temporarily by modifying sched_util_clamp_min. As soon as +this restriction is lifted, the requested sched_util_clamp_min_rt_default +will take effect. seccomp ======= diff --git a/Documentation/admin-guide/sysctl/vm.rst b/Documentation/admin-guide/sysctl/vm.rst index d46d5b7013c6..d997cc3c26d0 100644 --- a/Documentation/admin-guide/sysctl/vm.rst +++ b/Documentation/admin-guide/sysctl/vm.rst @@ -583,7 +583,7 @@ trimming of allocations is initiated. The default value is 1. -See Documentation/nommu-mmap.txt for more information. +See Documentation/admin-guide/mm/nommu-mmap.rst for more information. numa_zonelist_order diff --git a/Documentation/admin-guide/tainted-kernels.rst b/Documentation/admin-guide/tainted-kernels.rst index 71e9184a9079..abf804719890 100644 --- a/Documentation/admin-guide/tainted-kernels.rst +++ b/Documentation/admin-guide/tainted-kernels.rst @@ -38,7 +38,7 @@ either letters or blanks. In above example it looks like this:: Tainted: P W O -The meaning of those characters is explained in the table below. In tis case +The meaning of those characters is explained in the table below. In this case the kernel got tainted earlier because a proprietary Module (``P``) was loaded, a warning occurred (``W``), and an externally-built module was loaded (``O``). To decode other letters use the table below. @@ -61,7 +61,7 @@ this on the machine that had the statements in the logs that were quoted earlier * Proprietary module was loaded (#0) * Kernel issued warning (#9) * Externally-built ('out-of-tree') module was loaded (#12) - See Documentation/admin-guide/tainted-kernels.rst in the the Linux kernel or + See Documentation/admin-guide/tainted-kernels.rst in the Linux kernel or https://www.kernel.org/doc/html/latest/admin-guide/tainted-kernels.html for a more details explanation of the various taint flags. Raw taint value as int/string: 4609/'P W O ' diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-guide/thunderbolt.rst index 10c4f0ce2ad0..613cb24c76c7 100644 --- a/Documentation/admin-guide/thunderbolt.rst +++ b/Documentation/admin-guide/thunderbolt.rst @@ -173,8 +173,8 @@ following ``udev`` rule:: ACTION=="add", SUBSYSTEM=="thunderbolt", ATTRS{iommu_dma_protection}=="1", ATTR{authorized}=="0", ATTR{authorized}="1" -Upgrading NVM on Thunderbolt device or host -------------------------------------------- +Upgrading NVM on Thunderbolt device, host or retimer +---------------------------------------------------- Since most of the functionality is handled in firmware running on a host controller or a device, it is important that the firmware can be upgraded to the latest where possible bugs in it have been fixed. @@ -185,9 +185,10 @@ for some machines: `Thunderbolt Updates <https://thunderbolttechnology.net/updates>`_ -Before you upgrade firmware on a device or host, please make sure it is a -suitable upgrade. Failing to do that may render the device (or host) in a -state where it cannot be used properly anymore without special tools! +Before you upgrade firmware on a device, host or retimer, please make +sure it is a suitable upgrade. Failing to do that may render the device +in a state where it cannot be used properly anymore without special +tools! Host NVM upgrade on Apple Macs is not supported. diff --git a/Documentation/admin-guide/xfs.rst b/Documentation/admin-guide/xfs.rst index ad911be5b5e9..f461d6c33534 100644 --- a/Documentation/admin-guide/xfs.rst +++ b/Documentation/admin-guide/xfs.rst @@ -133,7 +133,7 @@ When mounting an XFS filesystem, the following options are accepted. logbsize must be an integer multiple of the log stripe unit configured at **mkfs(8)** time. - The default value for for version 1 logs is 32768, while the + The default value for version 1 logs is 32768, while the default value for version 2 logs is MAX(32768, log_sunit). logdev=device and rtdev=device diff --git a/Documentation/arm/arm.rst b/Documentation/arm/arm.rst index 2edc509df92a..99d660fdf73f 100644 --- a/Documentation/arm/arm.rst +++ b/Documentation/arm/arm.rst @@ -184,10 +184,8 @@ Kernel entry (head.S) We group machine (or platform) support code into machine classes. A class typically based around one or more system on a chip devices, and acts as a natural container around the actual implementations. These - classes are given directories - arch/arm/mach-<class> and - arch/arm/mach-<class> - which contain the source files to/include/mach - support the machine class. This directories also contain any machine - specific supporting code. + classes are given directories - arch/arm/mach-<class> - which contain + the source files and include/mach/ to support the machine class. For example, the SA1100 class is based upon the SA1100 and SA1110 SoC devices, and contains the code to support the way the on-board and off- diff --git a/Documentation/arm/booting.rst b/Documentation/arm/booting.rst index 4babb6c6ae1e..a2263451dc2c 100644 --- a/Documentation/arm/booting.rst +++ b/Documentation/arm/booting.rst @@ -128,7 +128,7 @@ it. The recommended placement is in the first 16KiB of RAM. The boot loader must load a device tree image (dtb) into system ram at a 64bit aligned address and initialize it with the boot data. The -dtb format is documented in Documentation/devicetree/booting-without-of.txt. +dtb format is documented in Documentation/devicetree/booting-without-of.rst. The kernel will look for the dtb magic value of 0xd00dfeed at the dtb physical address to determine if a dtb has been passed instead of a tagged list. diff --git a/Documentation/arm64/acpi_object_usage.rst b/Documentation/arm64/acpi_object_usage.rst index d51b69dc624d..377e9d224db0 100644 --- a/Documentation/arm64/acpi_object_usage.rst +++ b/Documentation/arm64/acpi_object_usage.rst @@ -220,7 +220,7 @@ LPIT Signature Reserved (signature == "LPIT") x86 only table as of ACPI 5.1; starting with ACPI 6.0, processor descriptions and power states on ARM platforms should use the DSDT and define processor container devices (_HID ACPI0010, Section 8.4, - and more specifically 8.4.3 and and 8.4.4). + and more specifically 8.4.3 and 8.4.4). MADT Section 5.2.12 (signature == "APIC") diff --git a/Documentation/arm64/arm-acpi.rst b/Documentation/arm64/arm-acpi.rst index 872dbbc73d4a..47ecb9930dde 100644 --- a/Documentation/arm64/arm-acpi.rst +++ b/Documentation/arm64/arm-acpi.rst @@ -273,7 +273,7 @@ only use the _DSD Device Properties UUID [5]: - UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301 - - http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf + - https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf The UEFI Forum provides a mechanism for registering device properties [4] so that they may be used across all operating systems supporting ACPI. @@ -470,7 +470,7 @@ likely be willing to assist in submitting ECRs. Linux Code ---------- -Individual items specific to Linux on ARM, contained in the the Linux +Individual items specific to Linux on ARM, contained in the Linux source code, are in the list that follows: ACPI_OS_NAME diff --git a/Documentation/arm64/cpu-feature-registers.rst b/Documentation/arm64/cpu-feature-registers.rst index 314fa5bc2655..f28853f80089 100644 --- a/Documentation/arm64/cpu-feature-registers.rst +++ b/Documentation/arm64/cpu-feature-registers.rst @@ -171,6 +171,7 @@ infrastructure: 3) ID_AA64PFR1_EL1 - Processor Feature Register 1 + +------------------------------+---------+---------+ | Name | bits | visible | +------------------------------+---------+---------+ @@ -181,6 +182,7 @@ infrastructure: 4) MIDR_EL1 - Main ID Register + +------------------------------+---------+---------+ | Name | bits | visible | +------------------------------+---------+---------+ diff --git a/Documentation/arm64/index.rst b/Documentation/arm64/index.rst index 09cbb4ed2237..d9665d83c53a 100644 --- a/Documentation/arm64/index.rst +++ b/Documentation/arm64/index.rst @@ -14,6 +14,7 @@ ARM64 Architecture hugetlbpage legacy_instructions memory + perf pointer-authentication silicon-errata sve diff --git a/Documentation/arm64/perf.txt b/Documentation/arm64/perf.rst index 0d6a7d87d49e..9c76a97baf28 100644 --- a/Documentation/arm64/perf.txt +++ b/Documentation/arm64/perf.rst @@ -1,8 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== Perf Event Attributes ===================== -Author: Andrew Murray <andrew.murray@arm.com> -Date: 2019-03-06 +:Author: Andrew Murray <andrew.murray@arm.com> +:Date: 2019-03-06 exclude_user ------------ diff --git a/Documentation/arm64/silicon-errata.rst b/Documentation/arm64/silicon-errata.rst index 936cf2a59ca4..3f7c3a7e8a2b 100644 --- a/Documentation/arm64/silicon-errata.rst +++ b/Documentation/arm64/silicon-errata.rst @@ -147,6 +147,14 @@ stable kernels. +----------------+-----------------+-----------------+-----------------------------+ | Qualcomm Tech. | Falkor v{1,2} | E1041 | QCOM_FALKOR_ERRATUM_1041 | +----------------+-----------------+-----------------+-----------------------------+ +| Qualcomm Tech. | Kryo4xx Gold | N/A | ARM64_ERRATUM_1463225 | ++----------------+-----------------+-----------------+-----------------------------+ +| Qualcomm Tech. | Kryo4xx Gold | N/A | ARM64_ERRATUM_1418040 | ++----------------+-----------------+-----------------+-----------------------------+ +| Qualcomm Tech. | Kryo4xx Silver | N/A | ARM64_ERRATUM_1530923 | ++----------------+-----------------+-----------------+-----------------------------+ +| Qualcomm Tech. | Kryo4xx Silver | N/A | ARM64_ERRATUM_1024718 | ++----------------+-----------------+-----------------+-----------------------------+ +----------------+-----------------+-----------------+-----------------------------+ | Fujitsu | A64FX | E#010001 | FUJITSU_ERRATUM_010001 | +----------------+-----------------+-----------------+-----------------------------+ diff --git a/Documentation/arm64/sve.rst b/Documentation/arm64/sve.rst index 5689c74c8082..03137154299e 100644 --- a/Documentation/arm64/sve.rst +++ b/Documentation/arm64/sve.rst @@ -186,7 +186,7 @@ prctl(PR_SVE_SET_VL, unsigned long arg) flags: - PR_SVE_SET_VL_INHERIT + PR_SVE_VL_INHERIT Inherit the current vector length across execve(). Otherwise, the vector length is reset to the system default at execve(). (See @@ -247,7 +247,7 @@ prctl(PR_SVE_GET_VL) The following flag may be OR-ed into the result: - PR_SVE_SET_VL_INHERIT + PR_SVE_VL_INHERIT Vector length will be inherited across execve(). @@ -393,7 +393,7 @@ The regset data starts with struct user_sve_header, containing: * At every execve() call, the new vector length of the new process is set to the system default vector length, unless - * PR_SVE_SET_VL_INHERIT (or equivalently SVE_PT_VL_INHERIT) is set for the + * PR_SVE_VL_INHERIT (or equivalently SVE_PT_VL_INHERIT) is set for the calling thread, or * a deferred vector length change is pending, established via the @@ -494,7 +494,7 @@ Appendix B. ARMv8-A FP/SIMD programmer's model Note: This section is for information only and not intended to be complete or to replace any architectural specification. -Refer to [4] for for more information. +Refer to [4] for more information. ARMv8-A defines the following floating-point / SIMD register state: diff --git a/Documentation/atomic_t.txt b/Documentation/atomic_t.txt index 0ab747e0d5ac..0f1fdedf36bb 100644 --- a/Documentation/atomic_t.txt +++ b/Documentation/atomic_t.txt @@ -85,21 +85,21 @@ smp_store_release() respectively. Therefore, if you find yourself only using the Non-RMW operations of atomic_t, you do not in fact need atomic_t at all and are doing it wrong. -A subtle detail of atomic_set{}() is that it should be observable to the RMW -ops. That is: +A note for the implementation of atomic_set{}() is that it must not break the +atomicity of the RMW ops. That is: - C atomic-set + C Atomic-RMW-ops-are-atomic-WRT-atomic_set { - atomic_set(v, 1); + atomic_t v = ATOMIC_INIT(1); } - P1(atomic_t *v) + P0(atomic_t *v) { - atomic_add_unless(v, 1, 0); + (void)atomic_add_unless(v, 1, 0); } - P2(atomic_t *v) + P1(atomic_t *v) { atomic_set(v, 0); } @@ -233,19 +233,19 @@ as well. Similarly, something like: is an ACQUIRE pattern (though very much not typical), but again the barrier is strictly stronger than ACQUIRE. As illustrated: - C strong-acquire + C Atomic-RMW+mb__after_atomic-is-stronger-than-acquire { } - P1(int *x, atomic_t *y) + P0(int *x, atomic_t *y) { r0 = READ_ONCE(*x); smp_rmb(); r1 = atomic_read(y); } - P2(int *x, atomic_t *y) + P1(int *x, atomic_t *y) { atomic_inc(y); smp_mb__after_atomic(); @@ -253,14 +253,14 @@ strictly stronger than ACQUIRE. As illustrated: } exists - (r0=1 /\ r1=0) + (0:r0=1 /\ 0:r1=0) This should not happen; but a hypothetical atomic_inc_acquire() -- (void)atomic_fetch_inc_acquire() for instance -- would allow the outcome, because it would not order the W part of the RMW against the following WRITE_ONCE. Thus: - P1 P2 + P0 P1 t = LL.acq *y (0) t++; diff --git a/Documentation/block/bfq-iosched.rst b/Documentation/block/bfq-iosched.rst index 0d237d402860..19d4d1570cee 100644 --- a/Documentation/block/bfq-iosched.rst +++ b/Documentation/block/bfq-iosched.rst @@ -492,13 +492,6 @@ set max_budget to higher values than those to which BFQ would have set it with auto-tuning. An alternative way to achieve this goal is to just increase the value of timeout_sync, leaving max_budget equal to 0. -weights -------- - -Read-only parameter, used to show the weights of the currently active -BFQ queues. - - 4. Group scheduling with BFQ ============================ @@ -566,7 +559,7 @@ Parameters to set For each group, there is only the following parameter to set. weight (namely blkio.bfq.weight or io.bfq-weight): the weight of the -group inside its parent. Available values: 1..10000 (default 100). The +group inside its parent. Available values: 1..1000 (default 100). The linear mapping between ioprio and weights, described at the beginning of the tunable section, is still valid, but all weights higher than IOPRIO_BE_NR*10 are mapped to ioprio 0. diff --git a/Documentation/block/biodoc.rst b/Documentation/block/biodoc.rst index b964796ec9c7..1d4d71e391af 100644 --- a/Documentation/block/biodoc.rst +++ b/Documentation/block/biodoc.rst @@ -196,7 +196,7 @@ a virtual address mapping (unlike the earlier scheme of virtual address do not have a corresponding kernel virtual address space mapping) and low-memory pages. -Note: Please refer to Documentation/DMA-API-HOWTO.txt for a discussion +Note: Please refer to :doc:`/core-api/dma-api-howto` for a discussion on PCI high mem DMA aspects and mapping of scatter gather lists, and support for 64 bit PCI. @@ -1036,7 +1036,7 @@ Now the generic block layer performs partition-remapping early and thus provides drivers with a sector number relative to whole device, rather than having to take partition number into account in order to arrive at the true sector number. The routine blk_partition_remap() is invoked by -generic_make_request even before invoking the queue specific make_request_fn, +submit_bio_noacct even before invoking the queue specific ->submit_bio, so the i/o scheduler also gets to operate on whole disk sector numbers. This should typically not require changes to block drivers, it just never gets to invoke its own partition sector offset calculations since all bios diff --git a/Documentation/block/blk-mq.rst b/Documentation/block/blk-mq.rst new file mode 100644 index 000000000000..88c56afcb070 --- /dev/null +++ b/Documentation/block/blk-mq.rst @@ -0,0 +1,153 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================================ +Multi-Queue Block IO Queueing Mechanism (blk-mq) +================================================ + +The Multi-Queue Block IO Queueing Mechanism is an API to enable fast storage +devices to achieve a huge number of input/output operations per second (IOPS) +through queueing and submitting IO requests to block devices simultaneously, +benefiting from the parallelism offered by modern storage devices. + +Introduction +============ + +Background +---------- + +Magnetic hard disks have been the de facto standard from the beginning of the +development of the kernel. The Block IO subsystem aimed to achieve the best +performance possible for those devices with a high penalty when doing random +access, and the bottleneck was the mechanical moving parts, a lot slower than +any layer on the storage stack. One example of such optimization technique +involves ordering read/write requests according to the current position of the +hard disk head. + +However, with the development of Solid State Drives and Non-Volatile Memories +without mechanical parts nor random access penalty and capable of performing +high parallel access, the bottleneck of the stack had moved from the storage +device to the operating system. In order to take advantage of the parallelism +in those devices' design, the multi-queue mechanism was introduced. + +The former design had a single queue to store block IO requests with a single +lock. That did not scale well in SMP systems due to dirty data in cache and the +bottleneck of having a single lock for multiple processors. This setup also +suffered with congestion when different processes (or the same process, moving +to different CPUs) wanted to perform block IO. Instead of this, the blk-mq API +spawns multiple queues with individual entry points local to the CPU, removing +the need for a lock. A deeper explanation on how this works is covered in the +following section (`Operation`_). + +Operation +--------- + +When the userspace performs IO to a block device (reading or writing a file, +for instance), blk-mq takes action: it will store and manage IO requests to +the block device, acting as middleware between the userspace (and a file +system, if present) and the block device driver. + +blk-mq has two group of queues: software staging queues and hardware dispatch +queues. When the request arrives at the block layer, it will try the shortest +path possible: send it directly to the hardware queue. However, there are two +cases that it might not do that: if there's an IO scheduler attached at the +layer or if we want to try to merge requests. In both cases, requests will be +sent to the software queue. + +Then, after the requests are processed by software queues, they will be placed +at the hardware queue, a second stage queue were the hardware has direct access +to process those requests. However, if the hardware does not have enough +resources to accept more requests, blk-mq will places requests on a temporary +queue, to be sent in the future, when the hardware is able. + +Software staging queues +~~~~~~~~~~~~~~~~~~~~~~~ + +The block IO subsystem adds requests in the software staging queues +(represented by struct :c:type:`blk_mq_ctx`) in case that they weren't sent +directly to the driver. A request is one or more BIOs. They arrived at the +block layer through the data structure struct :c:type:`bio`. The block layer +will then build a new structure from it, the struct :c:type:`request` that will +be used to communicate with the device driver. Each queue has its own lock and +the number of queues is defined by a per-CPU or per-node basis. + +The staging queue can be used to merge requests for adjacent sectors. For +instance, requests for sector 3-6, 6-7, 7-9 can become one request for 3-9. +Even if random access to SSDs and NVMs have the same time of response compared +to sequential access, grouped requests for sequential access decreases the +number of individual requests. This technique of merging requests is called +plugging. + +Along with that, the requests can be reordered to ensure fairness of system +resources (e.g. to ensure that no application suffers from starvation) and/or to +improve IO performance, by an IO scheduler. + +IO Schedulers +^^^^^^^^^^^^^ + +There are several schedulers implemented by the block layer, each one following +a heuristic to improve the IO performance. They are "pluggable" (as in plug +and play), in the sense of they can be selected at run time using sysfs. You +can read more about Linux's IO schedulers `here +<https://www.kernel.org/doc/html/latest/block/index.html>`_. The scheduling +happens only between requests in the same queue, so it is not possible to merge +requests from different queues, otherwise there would be cache trashing and a +need to have a lock for each queue. After the scheduling, the requests are +eligible to be sent to the hardware. One of the possible schedulers to be +selected is the NONE scheduler, the most straightforward one. It will just +place requests on whatever software queue the process is running on, without +any reordering. When the device starts processing requests in the hardware +queue (a.k.a. run the hardware queue), the software queues mapped to that +hardware queue will be drained in sequence according to their mapping. + +Hardware dispatch queues +~~~~~~~~~~~~~~~~~~~~~~~~ + +The hardware queue (represented by struct :c:type:`blk_mq_hw_ctx`) is a struct +used by device drivers to map the device submission queues (or device DMA ring +buffer), and are the last step of the block layer submission code before the +low level device driver taking ownership of the request. To run this queue, the +block layer removes requests from the associated software queues and tries to +dispatch to the hardware. + +If it's not possible to send the requests directly to hardware, they will be +added to a linked list (:c:type:`hctx->dispatch`) of requests. Then, +next time the block layer runs a queue, it will send the requests laying at the +:c:type:`dispatch` list first, to ensure a fairness dispatch with those +requests that were ready to be sent first. The number of hardware queues +depends on the number of hardware contexts supported by the hardware and its +device driver, but it will not be more than the number of cores of the system. +There is no reordering at this stage, and each software queue has a set of +hardware queues to send requests for. + +.. note:: + + Neither the block layer nor the device protocols guarantee + the order of completion of requests. This must be handled by + higher layers, like the filesystem. + +Tag-based completion +~~~~~~~~~~~~~~~~~~~~ + +In order to indicate which request has been completed, every request is +identified by an integer, ranging from 0 to the dispatch queue size. This tag +is generated by the block layer and later reused by the device driver, removing +the need to create a redundant identifier. When a request is completed in the +drive, the tag is sent back to the block layer to notify it of the finalization. +This removes the need to do a linear search to find out which IO has been +completed. + +Further reading +--------------- + +- `Linux Block IO: Introducing Multi-queue SSD Access on Multi-core Systems <http://kernel.dk/blk-mq.pdf>`_ + +- `NOOP scheduler <https://en.wikipedia.org/wiki/Noop_scheduler>`_ + +- `Null block device driver <https://www.kernel.org/doc/html/latest/block/null_blk.html>`_ + +Source code documentation +========================= + +.. kernel-doc:: include/linux/blk-mq.h + +.. kernel-doc:: block/blk-mq.c diff --git a/Documentation/block/index.rst b/Documentation/block/index.rst index 026addfc69bc..86dcf7159f99 100644 --- a/Documentation/block/index.rst +++ b/Documentation/block/index.rst @@ -10,6 +10,7 @@ Block bfq-iosched biodoc biovecs + blk-mq capability cmdline-partition data-integrity diff --git a/Documentation/block/pr.rst b/Documentation/block/pr.rst index 30ea1c2e39eb..c893d6da8e04 100644 --- a/Documentation/block/pr.rst +++ b/Documentation/block/pr.rst @@ -9,7 +9,7 @@ access to block devices to specific initiators in a shared storage setup. This document gives a general overview of the support ioctl commands. -For a more detailed reference please refer the the SCSI Primary +For a more detailed reference please refer to the SCSI Primary Commands standard, specifically the section on Reservations and the "PERSISTENT RESERVE IN" and "PERSISTENT RESERVE OUT" commands. diff --git a/Documentation/block/queue-sysfs.rst b/Documentation/block/queue-sysfs.rst index 6a8513af9201..f261a5c84170 100644 --- a/Documentation/block/queue-sysfs.rst +++ b/Documentation/block/queue-sysfs.rst @@ -117,6 +117,20 @@ Maximum number of elements in a DMA scatter/gather list with integrity data that will be submitted by the block layer core to the associated block driver. +max_active_zones (RO) +--------------------- +For zoned block devices (zoned attribute indicating "host-managed" or +"host-aware"), the sum of zones belonging to any of the zone states: +EXPLICIT OPEN, IMPLICIT OPEN or CLOSED, is limited by this value. +If this value is 0, there is no limit. + +max_open_zones (RO) +------------------- +For zoned block devices (zoned attribute indicating "host-managed" or +"host-aware"), the sum of zones belonging to any of the zone states: +EXPLICIT OPEN or IMPLICIT OPEN, is limited by this value. +If this value is 0, there is no limit. + max_sectors_kb (RW) ------------------- This is the maximum number of kilobytes that the block layer will allow diff --git a/Documentation/block/writeback_cache_control.rst b/Documentation/block/writeback_cache_control.rst index 2c752c57c14c..b208488d0aae 100644 --- a/Documentation/block/writeback_cache_control.rst +++ b/Documentation/block/writeback_cache_control.rst @@ -47,7 +47,7 @@ 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 +Implementation details for bio based block drivers -------------------------------------------------------------- These drivers will always see the REQ_PREFLUSH and REQ_FUA bits as they sit diff --git a/Documentation/bpf/bpf_devel_QA.rst b/Documentation/bpf/bpf_devel_QA.rst index 0b3db91dc100..a26aa1b9b259 100644 --- a/Documentation/bpf/bpf_devel_QA.rst +++ b/Documentation/bpf/bpf_devel_QA.rst @@ -643,5 +643,6 @@ when: .. _selftests: ../../tools/testing/selftests/bpf/ .. _Documentation/dev-tools/kselftest.rst: https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html +.. _Documentation/bpf/btf.rst: btf.rst Happy BPF hacking! diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst index 4d565d202ce3..b5361b8621c9 100644 --- a/Documentation/bpf/btf.rst +++ b/Documentation/bpf/btf.rst @@ -691,6 +691,42 @@ kernel API, the ``insn_off`` is the instruction offset in the unit of ``struct bpf_insn``. For ELF API, the ``insn_off`` is the byte offset from the beginning of section (``btf_ext_info_sec->sec_name_off``). +4.2 .BTF_ids section +==================== + +The .BTF_ids section encodes BTF ID values that are used within the kernel. + +This section is created during the kernel compilation with the help of +macros defined in ``include/linux/btf_ids.h`` header file. Kernel code can +use them to create lists and sets (sorted lists) of BTF ID values. + +The ``BTF_ID_LIST`` and ``BTF_ID`` macros define unsorted list of BTF ID values, +with following syntax:: + + BTF_ID_LIST(list) + BTF_ID(type1, name1) + BTF_ID(type2, name2) + +resulting in following layout in .BTF_ids section:: + + __BTF_ID__type1__name1__1: + .zero 4 + __BTF_ID__type2__name2__2: + .zero 4 + +The ``u32 list[];`` variable is defined to access the list. + +The ``BTF_ID_UNUSED`` macro defines 4 zero bytes. It's used when we +want to define unused entry in BTF_ID_LIST, like:: + + BTF_ID_LIST(bpf_skb_output_btf_ids) + BTF_ID(struct, sk_buff) + BTF_ID_UNUSED + BTF_ID(struct, task_struct) + +All the BTF ID lists and sets are compiled in the .BTF_ids section and +resolved during the linking phase of kernel build by ``resolve_btfids`` tool. + 5. Using BTF ************ diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst index 38b4db8be7a2..d46429be334e 100644 --- a/Documentation/bpf/index.rst +++ b/Documentation/bpf/index.rst @@ -5,10 +5,10 @@ BPF Documentation This directory contains documentation for the BPF (Berkeley Packet Filter) facility, with a focus on the extended BPF version (eBPF). -This kernel side documentation is still work in progress. The main +This kernel side documentation is still work in progress. The main textual documentation is (for historical reasons) described in -`Documentation/networking/filter.rst`_, which describe both classical -and extended BPF instruction-set. +:ref:`networking-filter`, which describe both classical and extended +BPF instruction-set. The Cilium project also maintains a `BPF and XDP Reference Guide`_ that goes into great technical depth about the BPF Architecture. @@ -48,6 +48,15 @@ Program types bpf_lsm +Map types +========= + +.. toctree:: + :maxdepth: 1 + + map_cgroup_storage + + Testing and debugging BPF ========================= @@ -58,8 +67,16 @@ Testing and debugging BPF s390 +Other +===== + +.. toctree:: + :maxdepth: 1 + + ringbuf + .. Links: -.. _Documentation/networking/filter.rst: ../networking/filter.txt +.. _networking-filter: ../networking/filter.rst .. _man-pages: https://www.kernel.org/doc/man-pages/ -.. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html -.. _BPF and XDP Reference Guide: http://cilium.readthedocs.io/en/latest/bpf/ +.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html +.. _BPF and XDP Reference Guide: https://docs.cilium.io/en/latest/bpf/ diff --git a/Documentation/bpf/map_cgroup_storage.rst b/Documentation/bpf/map_cgroup_storage.rst new file mode 100644 index 000000000000..cab9543017bf --- /dev/null +++ b/Documentation/bpf/map_cgroup_storage.rst @@ -0,0 +1,169 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. Copyright (C) 2020 Google LLC. + +=========================== +BPF_MAP_TYPE_CGROUP_STORAGE +=========================== + +The ``BPF_MAP_TYPE_CGROUP_STORAGE`` map type represents a local fix-sized +storage. It is only available with ``CONFIG_CGROUP_BPF``, and to programs that +attach to cgroups; the programs are made available by the same Kconfig. The +storage is identified by the cgroup the program is attached to. + +The map provide a local storage at the cgroup that the BPF program is attached +to. It provides a faster and simpler access than the general purpose hash +table, which performs a hash table lookups, and requires user to track live +cgroups on their own. + +This document describes the usage and semantics of the +``BPF_MAP_TYPE_CGROUP_STORAGE`` map type. Some of its behaviors was changed in +Linux 5.9 and this document will describe the differences. + +Usage +===== + +The map uses key of type of either ``__u64 cgroup_inode_id`` or +``struct bpf_cgroup_storage_key``, declared in ``linux/bpf.h``:: + + struct bpf_cgroup_storage_key { + __u64 cgroup_inode_id; + __u32 attach_type; + }; + +``cgroup_inode_id`` is the inode id of the cgroup directory. +``attach_type`` is the the program's attach type. + +Linux 5.9 added support for type ``__u64 cgroup_inode_id`` as the key type. +When this key type is used, then all attach types of the particular cgroup and +map will share the same storage. Otherwise, if the type is +``struct bpf_cgroup_storage_key``, then programs of different attach types +be isolated and see different storages. + +To access the storage in a program, use ``bpf_get_local_storage``:: + + void *bpf_get_local_storage(void *map, u64 flags) + +``flags`` is reserved for future use and must be 0. + +There is no implicit synchronization. Storages of ``BPF_MAP_TYPE_CGROUP_STORAGE`` +can be accessed by multiple programs across different CPUs, and user should +take care of synchronization by themselves. The bpf infrastructure provides +``struct bpf_spin_lock`` to synchronize the storage. See +``tools/testing/selftests/bpf/progs/test_spin_lock.c``. + +Examples +======== + +Usage with key type as ``struct bpf_cgroup_storage_key``:: + + #include <bpf/bpf.h> + + struct { + __uint(type, BPF_MAP_TYPE_CGROUP_STORAGE); + __type(key, struct bpf_cgroup_storage_key); + __type(value, __u32); + } cgroup_storage SEC(".maps"); + + int program(struct __sk_buff *skb) + { + __u32 *ptr = bpf_get_local_storage(&cgroup_storage, 0); + __sync_fetch_and_add(ptr, 1); + + return 0; + } + +Userspace accessing map declared above:: + + #include <linux/bpf.h> + #include <linux/libbpf.h> + + __u32 map_lookup(struct bpf_map *map, __u64 cgrp, enum bpf_attach_type type) + { + struct bpf_cgroup_storage_key = { + .cgroup_inode_id = cgrp, + .attach_type = type, + }; + __u32 value; + bpf_map_lookup_elem(bpf_map__fd(map), &key, &value); + // error checking omitted + return value; + } + +Alternatively, using just ``__u64 cgroup_inode_id`` as key type:: + + #include <bpf/bpf.h> + + struct { + __uint(type, BPF_MAP_TYPE_CGROUP_STORAGE); + __type(key, __u64); + __type(value, __u32); + } cgroup_storage SEC(".maps"); + + int program(struct __sk_buff *skb) + { + __u32 *ptr = bpf_get_local_storage(&cgroup_storage, 0); + __sync_fetch_and_add(ptr, 1); + + return 0; + } + +And userspace:: + + #include <linux/bpf.h> + #include <linux/libbpf.h> + + __u32 map_lookup(struct bpf_map *map, __u64 cgrp, enum bpf_attach_type type) + { + __u32 value; + bpf_map_lookup_elem(bpf_map__fd(map), &cgrp, &value); + // error checking omitted + return value; + } + +Semantics +========= + +``BPF_MAP_TYPE_PERCPU_CGROUP_STORAGE`` is a variant of this map type. This +per-CPU variant will have different memory regions for each CPU for each +storage. The non-per-CPU will have the same memory region for each storage. + +Prior to Linux 5.9, the lifetime of a storage is precisely per-attachment, and +for a single ``CGROUP_STORAGE`` map, there can be at most one program loaded +that uses the map. A program may be attached to multiple cgroups or have +multiple attach types, and each attach creates a fresh zeroed storage. The +storage is freed upon detach. + +There is a one-to-one association between the map of each type (per-CPU and +non-per-CPU) and the BPF program during load verification time. As a result, +each map can only be used by one BPF program and each BPF program can only use +one storage map of each type. Because of map can only be used by one BPF +program, sharing of this cgroup's storage with other BPF programs were +impossible. + +Since Linux 5.9, storage can be shared by multiple programs. When a program is +attached to a cgroup, the kernel would create a new storage only if the map +does not already contain an entry for the cgroup and attach type pair, or else +the old storage is reused for the new attachment. If the map is attach type +shared, then attach type is simply ignored during comparison. Storage is freed +only when either the map or the cgroup attached to is being freed. Detaching +will not directly free the storage, but it may cause the reference to the map +to reach zero and indirectly freeing all storage in the map. + +The map is not associated with any BPF program, thus making sharing possible. +However, the BPF program can still only associate with one map of each type +(per-CPU and non-per-CPU). A BPF program cannot use more than one +``BPF_MAP_TYPE_CGROUP_STORAGE`` or more than one +``BPF_MAP_TYPE_PERCPU_CGROUP_STORAGE``. + +In all versions, userspace may use the the attach parameters of cgroup and +attach type pair in ``struct bpf_cgroup_storage_key`` as the key to the BPF map +APIs to read or update the storage for a given attachment. For Linux 5.9 +attach type shared storages, only the first value in the struct, cgroup inode +id, is used during comparison, so userspace may just specify a ``__u64`` +directly. + +The storage is bound at attach time. Even if the program is attached to parent +and triggers in child, the storage still belongs to the parent. + +Userspace cannot create a new entry in the map or delete an existing entry. +Program test runs always use a temporary storage. diff --git a/Documentation/bpf/prog_cgroup_sockopt.rst b/Documentation/bpf/prog_cgroup_sockopt.rst index c47d974629ae..172f957204bf 100644 --- a/Documentation/bpf/prog_cgroup_sockopt.rst +++ b/Documentation/bpf/prog_cgroup_sockopt.rst @@ -86,6 +86,20 @@ then the next program in the chain (A) will see those changes, *not* the original input ``setsockopt`` arguments. The potentially modified values will be then passed down to the kernel. +Large optval +============ +When the ``optval`` is greater than the ``PAGE_SIZE``, the BPF program +can access only the first ``PAGE_SIZE`` of that data. So it has to options: + +* Set ``optlen`` to zero, which indicates that the kernel should + use the original buffer from the userspace. Any modifications + done by the BPF program to the ``optval`` are ignored. +* Set ``optlen`` to the value less than ``PAGE_SIZE``, which + indicates that the kernel should use BPF's trimmed ``optval``. + +When the BPF program returns with the ``optlen`` greater than +``PAGE_SIZE``, the userspace will receive ``EFAULT`` errno. + Example ======= diff --git a/Documentation/cdrom/cdrom-standard.rst b/Documentation/cdrom/cdrom-standard.rst index dde4f7f7fdbf..2de905810590 100644 --- a/Documentation/cdrom/cdrom-standard.rst +++ b/Documentation/cdrom/cdrom-standard.rst @@ -157,7 +157,6 @@ with the kernel as a block device by registering the following general cdrom_release, /∗ release ∗/ NULL, /∗ fsync ∗/ NULL, /∗ fasync ∗/ - cdrom_media_changed, /∗ media change ∗/ NULL /∗ revalidate ∗/ }; @@ -368,19 +367,6 @@ which may or may not be in the drive). If the drive is not a changer, :: - int media_changed(struct cdrom_device_info *cdi, int disc_nr) - -This function is very similar to the original function in $struct -file_operations*. It returns 1 if the medium of the device *cdi->dev* -has changed since the last call, and 0 otherwise. The parameter -*disc_nr* identifies a specific slot in a juke-box, it should be -ignored for single-disc drives. Note that by `re-routing` this -function through *cdrom_media_changed()*, we can implement separate -queues for the VFS and a new *ioctl()* function that can report device -changes to software (e. g., an auto-mounting daemon). - -:: - int tray_move(struct cdrom_device_info *cdi, int position) This function, if implemented, should control the tray movement. (No @@ -917,9 +903,7 @@ commands can be identified by the underscores in their names. maximum number of discs in the juke-box found in the *cdrom_dops*. `CDROM_MEDIA_CHANGED` Returns 1 if a disc has been changed since the last call. - Note that calls to *cdrom_media_changed* by the VFS are treated - by an independent queue, so both mechanisms will detect a - media change once. For juke-boxes, an extra argument *arg* + For juke-boxes, an extra argument *arg* specifies the slot for which the information is given. The special value *CDSL_CURRENT* requests that information about the currently selected slot be returned. diff --git a/Documentation/bus-virt-phys-mapping.txt b/Documentation/core-api/bus-virt-phys-mapping.rst index 4bb07c2f3e7d..c7bc99cd2e21 100644 --- a/Documentation/bus-virt-phys-mapping.txt +++ b/Documentation/core-api/bus-virt-phys-mapping.rst @@ -8,7 +8,7 @@ How to access I/O mapped memory from within device drivers The virt_to_bus() and bus_to_virt() functions have been superseded by the functionality provided by the PCI DMA interface - (see Documentation/DMA-API-HOWTO.txt). They continue + (see :doc:`/core-api/dma-api-howto`). They continue to be documented below for historical purposes, but new code must not use them. --davidm 00/12/12 diff --git a/Documentation/core-api/cpu_hotplug.rst b/Documentation/core-api/cpu_hotplug.rst index 4a50ab7817f7..298c9c8bea9a 100644 --- a/Documentation/core-api/cpu_hotplug.rst +++ b/Documentation/core-api/cpu_hotplug.rst @@ -35,8 +35,8 @@ Command Line Switches other CPUs later online. ``nr_cpus=n`` - Restrict the total amount CPUs the kernel will support. If the number - supplied here is lower than the number of physically available CPUs than + Restrict the total amount of CPUs the kernel will support. If the number + supplied here is lower than the number of physically available CPUs, then those CPUs can not be brought online later. ``additional_cpus=n`` @@ -50,13 +50,6 @@ Command Line Switches This option is limited to the X86 and S390 architecture. -``cede_offline={"off","on"}`` - Use this option to disable/enable putting offlined processors to an extended - ``H_CEDE`` state on supported pseries platforms. If nothing is specified, - ``cede_offline`` is set to "on". - - This option is limited to the PowerPC architecture. - ``cpu0_hotplug`` Allow to shutdown CPU0. diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst index 2d8d2fed7317..3b3abbbb4b9a 100644 --- a/Documentation/core-api/dma-api.rst +++ b/Documentation/core-api/dma-api.rst @@ -5,7 +5,7 @@ Dynamic DMA mapping using the generic device :Author: James E.J. Bottomley <James.Bottomley@HansenPartnership.com> This document describes the DMA API. For a more gentle introduction -of the API (and actual examples), see Documentation/DMA-API-HOWTO.txt. +of the API (and actual examples), see :doc:`/core-api/dma-api-howto`. This API is split into two pieces. Part I describes the basic API. Part II describes extensions for supporting non-consistent memory @@ -206,6 +206,14 @@ others should not be larger than the returned value. :: + bool + dma_need_sync(struct device *dev, dma_addr_t dma_addr); + +Returns %true if dma_sync_single_for_{device,cpu} calls are required to +transfer memory ownership. Returns %false if those calls can be skipped. + +:: + unsigned long dma_get_merge_boundary(struct device *dev); @@ -471,7 +479,7 @@ without the _attrs suffixes, except that they pass an optional dma_attrs. The interpretation of DMA attributes is architecture-specific, and -each attribute should be documented in Documentation/DMA-attributes.txt. +each attribute should be documented in :doc:`/core-api/dma-attributes`. If dma_attrs are 0, the semantics of each of these functions is identical to those of the corresponding function @@ -484,7 +492,7 @@ for DMA:: #include <linux/dma-mapping.h> /* DMA_ATTR_FOO should be defined in linux/dma-mapping.h and - * documented in Documentation/DMA-attributes.txt */ + * documented in Documentation/core-api/dma-attributes.rst */ ... unsigned long attr; diff --git a/Documentation/core-api/dma-isa-lpc.rst b/Documentation/core-api/dma-isa-lpc.rst index b1ec7b16c21f..e59a3d35a93d 100644 --- a/Documentation/core-api/dma-isa-lpc.rst +++ b/Documentation/core-api/dma-isa-lpc.rst @@ -17,7 +17,7 @@ To do ISA style DMA you need to include two headers:: #include <asm/dma.h> The first is the generic DMA API used to convert virtual addresses to -bus addresses (see Documentation/DMA-API.txt for details). +bus addresses (see :doc:`/core-api/dma-api` for details). The second contains the routines specific to ISA DMA transfers. Since this is not present on all platforms make sure you construct your diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index 15ab86112627..69171b1799f2 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -39,6 +39,8 @@ Library functionality that is used throughout the kernel. rbtree generic-radix-tree packing + bus-virt-phys-mapping + this_cpu_ops timekeeping errseq @@ -82,6 +84,7 @@ more memory-management documentation in :doc:`/vm/index`. :maxdepth: 1 memory-allocation + unaligned-memory-access dma-api dma-api-howto dma-attributes diff --git a/Documentation/core-api/kobject.rst b/Documentation/core-api/kobject.rst index e93dc8cf52dd..2739f8b72575 100644 --- a/Documentation/core-api/kobject.rst +++ b/Documentation/core-api/kobject.rst @@ -6,7 +6,7 @@ Everything you never wanted to know about kobjects, ksets, and ktypes :Last updated: December 19, 2007 Based on an original article by Jon Corbet for lwn.net written October 1, -2003 and located at http://lwn.net/Articles/51437/ +2003 and located at https://lwn.net/Articles/51437/ Part of the difficulty in understanding the driver model - and the kobject abstraction upon which it is built - is that there is no obvious starting diff --git a/Documentation/core-api/memory-allocation.rst b/Documentation/core-api/memory-allocation.rst index 4aa82ddd01b8..4446a1ac36cc 100644 --- a/Documentation/core-api/memory-allocation.rst +++ b/Documentation/core-api/memory-allocation.rst @@ -84,6 +84,50 @@ driver for a device with such restrictions, avoid using these flags. And even with hardware with restrictions it is preferable to use `dma_alloc*` APIs. +GFP flags and reclaim behavior +------------------------------ +Memory allocations may trigger direct or background reclaim and it is +useful to understand how hard the page allocator will try to satisfy that +or another request. + + * ``GFP_KERNEL & ~__GFP_RECLAIM`` - optimistic allocation without _any_ + attempt to free memory at all. The most light weight mode which even + doesn't kick the background reclaim. Should be used carefully because it + might deplete the memory and the next user might hit the more aggressive + reclaim. + + * ``GFP_KERNEL & ~__GFP_DIRECT_RECLAIM`` (or ``GFP_NOWAIT``)- optimistic + allocation without any attempt to free memory from the current + context but can wake kswapd to reclaim memory if the zone is below + the low watermark. Can be used from either atomic contexts or when + the request is a performance optimization and there is another + fallback for a slow path. + + * ``(GFP_KERNEL|__GFP_HIGH) & ~__GFP_DIRECT_RECLAIM`` (aka ``GFP_ATOMIC``) - + non sleeping allocation with an expensive fallback so it can access + some portion of memory reserves. Usually used from interrupt/bottom-half + context with an expensive slow path fallback. + + * ``GFP_KERNEL`` - both background and direct reclaim are allowed and the + **default** page allocator behavior is used. That means that not costly + allocation requests are basically no-fail but there is no guarantee of + that behavior so failures have to be checked properly by callers + (e.g. OOM killer victim is allowed to fail currently). + + * ``GFP_KERNEL | __GFP_NORETRY`` - overrides the default allocator behavior + and all allocation requests fail early rather than cause disruptive + reclaim (one round of reclaim in this implementation). The OOM killer + is not invoked. + + * ``GFP_KERNEL | __GFP_RETRY_MAYFAIL`` - overrides the default allocator + behavior and all allocation requests try really hard. The request + will fail if the reclaim cannot make any progress. The OOM killer + won't be triggered. + + * ``GFP_KERNEL | __GFP_NOFAIL`` - overrides the default allocator behavior + and all allocation requests will loop endlessly until they succeed. + This might be really dangerous especially for larger orders. + Selecting memory allocator ========================== diff --git a/Documentation/core-api/padata.rst b/Documentation/core-api/padata.rst index 0830e5b0e821..35175710b43c 100644 --- a/Documentation/core-api/padata.rst +++ b/Documentation/core-api/padata.rst @@ -27,22 +27,11 @@ padata_instance structure for overall control of how jobs are to be run:: #include <linux/padata.h> - struct padata_instance *padata_alloc_possible(const char *name); + struct padata_instance *padata_alloc(const char *name); 'name' simply identifies the instance. -There are functions for enabling and disabling the instance:: - - int padata_start(struct padata_instance *pinst); - void padata_stop(struct padata_instance *pinst); - -These functions are setting or clearing the "PADATA_INIT" flag; if that flag is -not set, other functions will refuse to work. padata_start() returns zero on -success (flag set) or -EINVAL if the padata cpumask contains no active CPU -(flag not set). padata_stop() clears the flag and blocks until the padata -instance is unused. - -Finally, complete padata initialization by allocating a padata_shell:: +Then, complete padata initialization by allocating a padata_shell:: struct padata_shell *padata_alloc_shell(struct padata_instance *pinst); @@ -155,11 +144,10 @@ submitted. Destroying ---------- -Cleaning up a padata instance predictably involves calling the three free +Cleaning up a padata instance predictably involves calling the two free functions that correspond to the allocation in reverse:: void padata_free_shell(struct padata_shell *ps); - void padata_stop(struct padata_instance *pinst); void padata_free(struct padata_instance *pinst); It is the user's responsibility to ensure all outstanding jobs are complete diff --git a/Documentation/core-api/pin_user_pages.rst b/Documentation/core-api/pin_user_pages.rst index 6068266dd303..7ca8c7bac650 100644 --- a/Documentation/core-api/pin_user_pages.rst +++ b/Documentation/core-api/pin_user_pages.rst @@ -33,7 +33,7 @@ all combinations of get*(), pin*(), FOLL_LONGTERM, and more. Also, the pin_user_pages*() APIs are clearly distinct from the get_user_pages*() APIs, so that's a natural dividing line, and a good point to make separate wrapper calls. In other words, use pin_user_pages*() for DMA-pinned pages, and -get_user_pages*() for other cases. There are four cases described later on in +get_user_pages*() for other cases. There are five cases described later on in this document, to further clarify that concept. FOLL_PIN and FOLL_GET are mutually exclusive for a given gup call. However, diff --git a/Documentation/core-api/printk-basics.rst b/Documentation/core-api/printk-basics.rst index 563a9ce5fe1d..965e4281eddd 100644 --- a/Documentation/core-api/printk-basics.rst +++ b/Documentation/core-api/printk-basics.rst @@ -69,7 +69,7 @@ You can check the current *console_loglevel* with:: The result shows the *current*, *default*, *minimum* and *boot-time-default* log levels. -To change the current console_loglevel simply write the the desired level to +To change the current console_loglevel simply write the desired level to ``/proc/sys/kernel/printk``. For example, to print all messages to the console:: # echo 8 > /proc/sys/kernel/printk diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst index 8c9aba262b1e..6d26c5c6ac48 100644 --- a/Documentation/core-api/printk-formats.rst +++ b/Documentation/core-api/printk-formats.rst @@ -317,7 +317,7 @@ colon-separators. Leading zeros are always used. The additional ``c`` specifier can be used with the ``I`` specifier to print a compressed IPv6 address as described by -http://tools.ietf.org/html/rfc5952 +https://tools.ietf.org/html/rfc5952 Passed by reference. @@ -341,7 +341,7 @@ The additional ``p``, ``f``, and ``s`` specifiers are used to specify port flowinfo a ``/`` and scope a ``%``, each followed by the actual value. In case of an IPv6 address the compressed IPv6 address as described by -http://tools.ietf.org/html/rfc5952 is being used if the additional +https://tools.ietf.org/html/rfc5952 is being used if the additional specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in case of additional specifiers ``p``, ``f`` or ``s`` as suggested by https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07 @@ -494,9 +494,11 @@ Time and date %pt[RT]t HH:MM:SS %pt[RT][dt][r] -For printing date and time as represented by +For printing date and time as represented by:: + R struct rtc_time structure T time64_t type + in human readable format. By default year will be incremented by 1900 and month by 1. diff --git a/Documentation/this_cpu_ops.txt b/Documentation/core-api/this_cpu_ops.rst index 5cb8b883ae83..5cb8b883ae83 100644 --- a/Documentation/this_cpu_ops.txt +++ b/Documentation/core-api/this_cpu_ops.rst diff --git a/Documentation/process/unaligned-memory-access.rst b/Documentation/core-api/unaligned-memory-access.rst index 1ee82419d8aa..1ee82419d8aa 100644 --- a/Documentation/process/unaligned-memory-access.rst +++ b/Documentation/core-api/unaligned-memory-access.rst diff --git a/Documentation/crypto/api-intro.txt b/Documentation/crypto/api-intro.rst index 45d943fcae5b..15201be0b811 100644 --- a/Documentation/crypto/api-intro.txt +++ b/Documentation/crypto/api-intro.rst @@ -1,7 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 - Scatterlist Cryptographic API - -INTRODUCTION +============================= +Scatterlist Cryptographic API +============================= + +Introduction +============ The Scatterlist Crypto API takes page vectors (scatterlists) as arguments, and works directly on pages. In some cases (e.g. ECB @@ -13,22 +17,23 @@ so that processing can be applied to paged skb's without the need for linearization. -DETAILS +Details +======= At the lowest level are algorithms, which register dynamically with the API. 'Transforms' are user-instantiated objects, which maintain state, handle all -of the implementation logic (e.g. manipulating page vectors) and provide an -abstraction to the underlying algorithms. However, at the user +of the implementation logic (e.g. manipulating page vectors) and provide an +abstraction to the underlying algorithms. However, at the user level they are very simple. -Conceptually, the API layering looks like this: +Conceptually, the API layering looks like this:: [transform api] (user interface) [transform ops] (per-type logic glue e.g. cipher.c, compress.c) [algorithm api] (for registering algorithms) - + The idea is to make the user interface and algorithm registration API very simple, while hiding the core logic from both. Many good ideas from existing APIs such as Cryptoapi and Nettle have been adapted for this. @@ -44,21 +49,21 @@ one block while the former can operate on an arbitrary amount of data, subject to block size requirements (i.e., non-stream ciphers can only process multiples of blocks). -Here's an example of how to use the API: +Here's an example of how to use the API:: #include <crypto/hash.h> #include <linux/err.h> #include <linux/scatterlist.h> - + struct scatterlist sg[2]; char result[128]; struct crypto_ahash *tfm; struct ahash_request *req; - + tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC); if (IS_ERR(tfm)) fail(); - + /* ... set up the scatterlists ... */ req = ahash_request_alloc(tfm, GFP_ATOMIC); @@ -67,18 +72,19 @@ Here's an example of how to use the API: ahash_request_set_callback(req, 0, NULL, NULL); ahash_request_set_crypt(req, sg, result, 2); - + if (crypto_ahash_digest(req)) fail(); ahash_request_free(req); crypto_free_ahash(tfm); - + Many real examples are available in the regression test module (tcrypt.c). -DEVELOPER NOTES +Developer Notes +=============== Transforms may only be allocated in user context, and cryptographic methods may only be called from softirq and user contexts. For @@ -91,7 +97,8 @@ size (typically 8 bytes). This prevents having to do any copying across non-aligned page fragment boundaries. -ADDING NEW ALGORITHMS +Adding New Algorithms +===================== When submitting a new algorithm for inclusion, a mandatory requirement is that at least a few test vectors from known sources (preferably @@ -119,132 +126,137 @@ Also check the TODO list at the web site listed below to see what people might already be working on. -BUGS +Bugs +==== Send bug reports to: -linux-crypto@vger.kernel.org -Cc: Herbert Xu <herbert@gondor.apana.org.au>, + linux-crypto@vger.kernel.org + +Cc: + Herbert Xu <herbert@gondor.apana.org.au>, David S. Miller <davem@redhat.com> -FURTHER INFORMATION +Further Information +=================== For further patches and various updates, including the current TODO list, see: http://gondor.apana.org.au/~herbert/crypto/ -AUTHORS +Authors +======= -James Morris -David S. Miller -Herbert Xu +- James Morris +- David S. Miller +- Herbert Xu -CREDITS +Credits +======= The following people provided invaluable feedback during the development of the API: - Alexey Kuznetzov - Rusty Russell - Herbert Valerio Riedel - Jeff Garzik - Michael Richardson - Andrew Morton - Ingo Oeser - Christoph Hellwig + - Alexey Kuznetzov + - Rusty Russell + - Herbert Valerio Riedel + - Jeff Garzik + - Michael Richardson + - Andrew Morton + - Ingo Oeser + - Christoph Hellwig Portions of this API were derived from the following projects: - + Kerneli Cryptoapi (http://www.kerneli.org/) - Alexander Kjeldaas - Herbert Valerio Riedel - Kyle McMartin - Jean-Luc Cooke - David Bryson - Clemens Fruhwirth - Tobias Ringstrom - Harald Welte + - Alexander Kjeldaas + - Herbert Valerio Riedel + - Kyle McMartin + - Jean-Luc Cooke + - David Bryson + - Clemens Fruhwirth + - Tobias Ringstrom + - Harald Welte and; - - Nettle (http://www.lysator.liu.se/~nisse/nettle/) - Niels Möller + + Nettle (https://www.lysator.liu.se/~nisse/nettle/) + - Niels Möller Original developers of the crypto algorithms: - Dana L. How (DES) - Andrew Tridgell and Steve French (MD4) - Colin Plumb (MD5) - Steve Reid (SHA1) - Jean-Luc Cooke (SHA256, SHA384, SHA512) - Kazunori Miyazawa / USAGI (HMAC) - Matthew Skala (Twofish) - Dag Arne Osvik (Serpent) - Brian Gladman (AES) - Kartikey Mahendra Bhatt (CAST6) - Jon Oberheide (ARC4) - Jouni Malinen (Michael MIC) - NTT(Nippon Telegraph and Telephone Corporation) (Camellia) + - Dana L. How (DES) + - Andrew Tridgell and Steve French (MD4) + - Colin Plumb (MD5) + - Steve Reid (SHA1) + - Jean-Luc Cooke (SHA256, SHA384, SHA512) + - Kazunori Miyazawa / USAGI (HMAC) + - Matthew Skala (Twofish) + - Dag Arne Osvik (Serpent) + - Brian Gladman (AES) + - Kartikey Mahendra Bhatt (CAST6) + - Jon Oberheide (ARC4) + - Jouni Malinen (Michael MIC) + - NTT(Nippon Telegraph and Telephone Corporation) (Camellia) SHA1 algorithm contributors: - Jean-Francois Dive - + - Jean-Francois Dive + DES algorithm contributors: - Raimar Falke - Gisle Sælensminde - Niels Möller + - Raimar Falke + - Gisle Sælensminde + - Niels Möller Blowfish algorithm contributors: - Herbert Valerio Riedel - Kyle McMartin + - Herbert Valerio Riedel + - Kyle McMartin Twofish algorithm contributors: - Werner Koch - Marc Mutz + - Werner Koch + - Marc Mutz SHA256/384/512 algorithm contributors: - Andrew McDonald - Kyle McMartin - Herbert Valerio Riedel - + - Andrew McDonald + - Kyle McMartin + - Herbert Valerio Riedel + AES algorithm contributors: - Alexander Kjeldaas - Herbert Valerio Riedel - Kyle McMartin - Adam J. Richter - Fruhwirth Clemens (i586) - Linus Torvalds (i586) + - Alexander Kjeldaas + - Herbert Valerio Riedel + - Kyle McMartin + - Adam J. Richter + - Fruhwirth Clemens (i586) + - Linus Torvalds (i586) CAST5 algorithm contributors: - Kartikey Mahendra Bhatt (original developers unknown, FSF copyright). + - Kartikey Mahendra Bhatt (original developers unknown, FSF copyright). TEA/XTEA algorithm contributors: - Aaron Grothe - Michael Ringe + - Aaron Grothe + - Michael Ringe Khazad algorithm contributors: - Aaron Grothe + - Aaron Grothe Whirlpool algorithm contributors: - Aaron Grothe - Jean-Luc Cooke + - Aaron Grothe + - Jean-Luc Cooke Anubis algorithm contributors: - Aaron Grothe + - Aaron Grothe Tiger algorithm contributors: - Aaron Grothe + - Aaron Grothe VIA PadLock contributors: - Michal Ludvig + - Michal Ludvig Camellia algorithm contributors: - NTT(Nippon Telegraph and Telephone Corporation) (Camellia) + - NTT(Nippon Telegraph and Telephone Corporation) (Camellia) Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com> Please send any credits updates or corrections to: Herbert Xu <herbert@gondor.apana.org.au> - diff --git a/Documentation/crypto/asymmetric-keys.txt b/Documentation/crypto/asymmetric-keys.rst index 8763866b11cf..349f44a29392 100644 --- a/Documentation/crypto/asymmetric-keys.txt +++ b/Documentation/crypto/asymmetric-keys.rst @@ -1,8 +1,10 @@ - ============================================= - ASYMMETRIC / PUBLIC-KEY CRYPTOGRAPHY KEY TYPE - ============================================= +.. SPDX-License-Identifier: GPL-2.0 -Contents: +============================================= +Asymmetric / Public-key Cryptography Key Type +============================================= + +.. Contents: - Overview. - Key identification. @@ -13,8 +15,7 @@ Contents: - Keyring link restrictions. -======== -OVERVIEW +Overview ======== The "asymmetric" key type is designed to be a container for the keys used in @@ -42,8 +43,7 @@ key, or it may interpret it as a reference to a key held somewhere else in the system (for example, a TPM). -================== -KEY IDENTIFICATION +Key Identification ================== If a key is added with an empty name, the instantiation data parsers are given @@ -57,49 +57,48 @@ The asymmetric key type's match function can then perform a wider range of comparisons than just the straightforward comparison of the description with the criterion string: - (1) If the criterion string is of the form "id:<hexdigits>" then the match + 1) If the criterion string is of the form "id:<hexdigits>" then the match function will examine a key's fingerprint to see if the hex digits given - after the "id:" match the tail. For instance: + after the "id:" match the tail. For instance:: keyctl search @s asymmetric id:5acc2142 - will match a key with fingerprint: + will match a key with fingerprint:: 1A00 2040 7601 7889 DE11 882C 3823 04AD 5ACC 2142 - (2) If the criterion string is of the form "<subtype>:<hexdigits>" then the + 2) If the criterion string is of the form "<subtype>:<hexdigits>" then the match will match the ID as in (1), but with the added restriction that only keys of the specified subtype (e.g. tpm) will be matched. For - instance: + instance:: keyctl search @s asymmetric tpm:5acc2142 Looking in /proc/keys, the last 8 hex digits of the key fingerprint are -displayed, along with the subtype: +displayed, along with the subtype:: 1a39e171 I----- 1 perm 3f010000 0 0 asymmetric modsign.0: DSA 5acc2142 [] -========================= -ACCESSING ASYMMETRIC KEYS +Accessing Asymmetric Keys ========================= For general access to asymmetric keys from within the kernel, the following -inclusion is required: +inclusion is required:: #include <crypto/public_key.h> This gives access to functions for dealing with asymmetric / public keys. Three enums are defined there for representing public-key cryptography -algorithms: +algorithms:: enum pkey_algo -digest algorithms used by those: +digest algorithms used by those:: enum pkey_hash_algo -and key identifier representations: +and key identifier representations:: enum pkey_id_type @@ -110,25 +109,25 @@ PGP-specific metadata, whereas X.509 has arbitrary certificate identifiers. The operations defined upon a key are: - (1) Signature verification. + 1) Signature verification. Other operations are possible (such as encryption) with the same key data required for verification, but not currently supported, and others (eg. decryption and signature generation) require extra key data. -SIGNATURE VERIFICATION +Signature Verification ---------------------- An operation is provided to perform cryptographic signature verification, using -an asymmetric key to provide or to provide access to the public key. +an asymmetric key to provide or to provide access to the public key:: int verify_signature(const struct key *key, const struct public_key_signature *sig); The caller must have already obtained the key from some source and can then use it to check the signature. The caller must have parsed the signature and -transferred the relevant bits to the structure pointed to by sig. +transferred the relevant bits to the structure pointed to by sig:: struct public_key_signature { u8 *digest; @@ -159,8 +158,7 @@ data; or -ENOMEM if an allocation can't be performed. -EINVAL can be returned if the key argument is the wrong type or is incompletely set up. -======================= -ASYMMETRIC KEY SUBTYPES +Asymmetric Key Subtypes ======================= Asymmetric keys have a subtype that defines the set of operations that can be @@ -171,11 +169,11 @@ The subtype is selected by the key data parser and the parser must initialise the data required for it. The asymmetric key retains a reference on the subtype module. -The subtype definition structure can be found in: +The subtype definition structure can be found in:: #include <keys/asymmetric-subtype.h> -and looks like the following: +and looks like the following:: struct asymmetric_key_subtype { struct module *owner; @@ -198,39 +196,37 @@ the subtype. Currently, the name is only used for print statements. There are a number of operations defined by the subtype: - (1) describe(). + 1) describe(). Mandatory. This allows the subtype to display something in /proc/keys against the key. For instance the name of the public key algorithm type could be displayed. The key type will display the tail of the key identity string after this. - (2) destroy(). + 2) destroy(). Mandatory. This should free the memory associated with the key. The asymmetric key will look after freeing the fingerprint and releasing the reference on the subtype module. - (3) query(). + 3) query(). Mandatory. This is a function for querying the capabilities of a key. - (4) eds_op(). + 4) eds_op(). Optional. This is the entry point for the encryption, decryption and signature creation operations (which are distinguished by the operation ID in the parameter struct). The subtype may do anything it likes to implement an operation, including offloading to hardware. - (5) verify_signature(). + 5) verify_signature(). Optional. This is the entry point for signature verification. The subtype may do anything it likes to implement an operation, including offloading to hardware. - -========================== -INSTANTIATION DATA PARSERS +Instantiation Data Parsers ========================== The asymmetric key type doesn't generally want to store or to deal with a raw @@ -254,11 +250,11 @@ Examples of blob formats for which parsers could be implemented include: During key instantiation each parser in the list is tried until one doesn't return -EBADMSG. -The parser definition structure can be found in: +The parser definition structure can be found in:: #include <keys/asymmetric-parser.h> -and looks like the following: +and looks like the following:: struct asymmetric_key_parser { struct module *owner; @@ -273,7 +269,7 @@ the parser. There is currently only a single operation defined by the parser, and it is mandatory: - (1) parse(). + 1) parse(). This is called to preparse the key from the key creation and update paths. In particular, it is called during the key creation _before_ a key is @@ -282,7 +278,7 @@ mandatory: The caller passes a pointer to the following struct with all of the fields cleared, except for data, datalen and quotalen [see - Documentation/security/keys/core.rst]. + Documentation/security/keys/core.rst]:: struct key_preparsed_payload { char *description; @@ -321,7 +317,7 @@ mandatory: public-key algorithm such as RSA and DSA this will likely be a printable hex version of the key's fingerprint. -Functions are provided to register and unregister parsers: +Functions are provided to register and unregister parsers:: int register_asymmetric_key_parser(struct asymmetric_key_parser *parser); void unregister_asymmetric_key_parser(struct asymmetric_key_parser *subtype); @@ -330,8 +326,7 @@ Parsers may not have the same name. The names are otherwise only used for displaying in debugging messages. -========================= -KEYRING LINK RESTRICTIONS +Keyring Link Restrictions ========================= Keyrings created from userspace using add_key can be configured to check the @@ -340,7 +335,7 @@ allowed to link. Several restriction methods are available: - (1) Restrict using the kernel builtin trusted keyring + 1) Restrict using the kernel builtin trusted keyring - Option string used with KEYCTL_RESTRICT_KEYRING: - "builtin_trusted" @@ -350,7 +345,7 @@ Several restriction methods are available: rejected. The ca_keys kernel parameter also affects which keys are used for signature verification. - (2) Restrict using the kernel builtin and secondary trusted keyrings + 2) Restrict using the kernel builtin and secondary trusted keyrings - Option string used with KEYCTL_RESTRICT_KEYRING: - "builtin_and_secondary_trusted" @@ -361,7 +356,7 @@ Several restriction methods are available: kernel parameter also affects which keys are used for signature verification. - (3) Restrict using a separate key or keyring + 3) Restrict using a separate key or keyring - Option string used with KEYCTL_RESTRICT_KEYRING: - "key_or_keyring:<key or keyring serial number>[:chain]" @@ -378,7 +373,7 @@ Several restriction methods are available: certificate in order (starting closest to the root) to a keyring. For instance, one keyring can be populated with links to a set of root certificates, with a separate, restricted keyring set up for each - certificate chain to be validated: + certificate chain to be validated:: # Create and populate a keyring for root certificates root_id=`keyctl add keyring root-certs "" @s` @@ -400,7 +395,7 @@ Several restriction methods are available: one of the root certificates. A single keyring can be used to verify a chain of signatures by - restricting the keyring after linking the root certificate: + restricting the keyring after linking the root certificate:: # Create a keyring for the certificate chain and add the root chain2_id=`keyctl add keyring chain2 "" @s` diff --git a/Documentation/crypto/async-tx-api.txt b/Documentation/crypto/async-tx-api.rst index 7bf1be20d93a..bfc773991bdc 100644 --- a/Documentation/crypto/async-tx-api.txt +++ b/Documentation/crypto/async-tx-api.rst @@ -1,27 +1,32 @@ - Asynchronous Transfers/Transforms API +.. SPDX-License-Identifier: GPL-2.0 -1 INTRODUCTION +===================================== +Asynchronous Transfers/Transforms API +===================================== -2 GENEALOGY +.. Contents -3 USAGE -3.1 General format of the API -3.2 Supported operations -3.3 Descriptor management -3.4 When does the operation execute? -3.5 When does the operation complete? -3.6 Constraints -3.7 Example + 1. INTRODUCTION -4 DMAENGINE DRIVER DEVELOPER NOTES -4.1 Conformance points -4.2 "My application needs exclusive control of hardware channels" + 2 GENEALOGY -5 SOURCE + 3 USAGE + 3.1 General format of the API + 3.2 Supported operations + 3.3 Descriptor management + 3.4 When does the operation execute? + 3.5 When does the operation complete? + 3.6 Constraints + 3.7 Example ---- + 4 DMAENGINE DRIVER DEVELOPER NOTES + 4.1 Conformance points + 4.2 "My application needs exclusive control of hardware channels" -1 INTRODUCTION + 5 SOURCE + +1. Introduction +=============== The async_tx API provides methods for describing a chain of asynchronous bulk memory transfers/transforms with support for inter-transactional @@ -31,7 +36,8 @@ that is written to the API can optimize for asynchronous operation and the API will fit the chain of operations to the available offload resources. -2 GENEALOGY +2.Genealogy +=========== The API was initially designed to offload the memory copy and xor-parity-calculations of the md-raid5 driver using the offload engines @@ -39,40 +45,52 @@ present in the Intel(R) Xscale series of I/O processors. It also built on the 'dmaengine' layer developed for offloading memory copies in the network stack using Intel(R) I/OAT engines. The following design features surfaced as a result: -1/ implicit synchronous path: users of the API do not need to know if + +1. implicit synchronous path: users of the API do not need to know if the platform they are running on has offload capabilities. The operation will be offloaded when an engine is available and carried out in software otherwise. -2/ cross channel dependency chains: the API allows a chain of dependent +2. cross channel dependency chains: the API allows a chain of dependent operations to be submitted, like xor->copy->xor in the raid5 case. The API automatically handles cases where the transition from one operation to another implies a hardware channel switch. -3/ dmaengine extensions to support multiple clients and operation types +3. dmaengine extensions to support multiple clients and operation types beyond 'memcpy' -3 USAGE +3. Usage +======== + +3.1 General format of the API +----------------------------- + +:: + + struct dma_async_tx_descriptor * + async_<operation>(<op specific parameters>, struct async_submit ctl *submit) -3.1 General format of the API: -struct dma_async_tx_descriptor * -async_<operation>(<op specific parameters>, struct async_submit ctl *submit) +3.2 Supported operations +------------------------ -3.2 Supported operations: -memcpy - memory copy between a source and a destination buffer -memset - fill a destination buffer with a byte value -xor - xor a series of source buffers and write the result to a +======== ==================================================================== +memcpy memory copy between a source and a destination buffer +memset fill a destination buffer with a byte value +xor xor a series of source buffers and write the result to a destination buffer -xor_val - xor a series of source buffers and set a flag if the +xor_val xor a series of source buffers and set a flag if the result is zero. The implementation attempts to prevent writes to memory -pq - generate the p+q (raid6 syndrome) from a series of source buffers -pq_val - validate that a p and or q buffer are in sync with a given series of +pq generate the p+q (raid6 syndrome) from a series of source buffers +pq_val validate that a p and or q buffer are in sync with a given series of sources -datap - (raid6_datap_recov) recover a raid6 data block and the p block +datap (raid6_datap_recov) recover a raid6 data block and the p block from the given sources -2data - (raid6_2data_recov) recover 2 raid6 data blocks from the given +2data (raid6_2data_recov) recover 2 raid6 data blocks from the given sources +======== ==================================================================== + +3.3 Descriptor management +------------------------- -3.3 Descriptor management: The return value is non-NULL and points to a 'descriptor' when the operation has been queued to execute asynchronously. Descriptors are recycled resources, under control of the offload engine driver, to be reused as @@ -82,12 +100,15 @@ before the dependency is submitted. This requires that all descriptors be acknowledged by the application before the offload engine driver is allowed to recycle (or free) the descriptor. A descriptor can be acked by one of the following methods: -1/ setting the ASYNC_TX_ACK flag if no child operations are to be submitted -2/ submitting an unacknowledged descriptor as a dependency to another + +1. setting the ASYNC_TX_ACK flag if no child operations are to be submitted +2. submitting an unacknowledged descriptor as a dependency to another async_tx call will implicitly set the acknowledged state. -3/ calling async_tx_ack() on the descriptor. +3. calling async_tx_ack() on the descriptor. 3.4 When does the operation execute? +------------------------------------ + Operations do not immediately issue after return from the async_<operation> call. Offload engine drivers batch operations to improve performance by reducing the number of mmio cycles needed to @@ -98,12 +119,15 @@ channels since the application has no knowledge of channel to operation mapping. 3.5 When does the operation complete? +------------------------------------- + There are two methods for an application to learn about the completion of an operation. -1/ Call dma_wait_for_async_tx(). This call causes the CPU to spin while + +1. Call dma_wait_for_async_tx(). This call causes the CPU to spin while it polls for the completion of the operation. It handles dependency chains and issuing pending operations. -2/ Specify a completion callback. The callback routine runs in tasklet +2. Specify a completion callback. The callback routine runs in tasklet context if the offload engine driver supports interrupts, or it is called in application context if the operation is carried out synchronously in software. The callback can be set in the call to @@ -111,83 +135,95 @@ of an operation. unknown length it can use the async_trigger_callback() routine to set a completion interrupt/callback at the end of the chain. -3.6 Constraints: -1/ Calls to async_<operation> are not permitted in IRQ context. Other +3.6 Constraints +--------------- + +1. Calls to async_<operation> are not permitted in IRQ context. Other contexts are permitted provided constraint #2 is not violated. -2/ Completion callback routines cannot submit new operations. This +2. Completion callback routines cannot submit new operations. This results in recursion in the synchronous case and spin_locks being acquired twice in the asynchronous case. -3.7 Example: +3.7 Example +----------- + Perform a xor->copy->xor operation where each operation depends on the -result from the previous operation: - -void callback(void *param) -{ - struct completion *cmp = param; - - complete(cmp); -} - -void run_xor_copy_xor(struct page **xor_srcs, - int xor_src_cnt, - struct page *xor_dest, - size_t xor_len, - struct page *copy_src, - struct page *copy_dest, - size_t copy_len) -{ - struct dma_async_tx_descriptor *tx; - addr_conv_t addr_conv[xor_src_cnt]; - struct async_submit_ctl submit; - addr_conv_t addr_conv[NDISKS]; - struct completion cmp; - - init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST, NULL, NULL, NULL, - addr_conv); - tx = async_xor(xor_dest, xor_srcs, 0, xor_src_cnt, xor_len, &submit) - - submit->depend_tx = tx; - tx = async_memcpy(copy_dest, copy_src, 0, 0, copy_len, &submit); - - init_completion(&cmp); - init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST | ASYNC_TX_ACK, tx, - callback, &cmp, addr_conv); - tx = async_xor(xor_dest, xor_srcs, 0, xor_src_cnt, xor_len, &submit); - - async_tx_issue_pending_all(); - - wait_for_completion(&cmp); -} +result from the previous operation:: + + void callback(void *param) + { + struct completion *cmp = param; + + complete(cmp); + } + + void run_xor_copy_xor(struct page **xor_srcs, + int xor_src_cnt, + struct page *xor_dest, + size_t xor_len, + struct page *copy_src, + struct page *copy_dest, + size_t copy_len) + { + struct dma_async_tx_descriptor *tx; + addr_conv_t addr_conv[xor_src_cnt]; + struct async_submit_ctl submit; + addr_conv_t addr_conv[NDISKS]; + struct completion cmp; + + init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST, NULL, NULL, NULL, + addr_conv); + tx = async_xor(xor_dest, xor_srcs, 0, xor_src_cnt, xor_len, &submit) + + submit->depend_tx = tx; + tx = async_memcpy(copy_dest, copy_src, 0, 0, copy_len, &submit); + + init_completion(&cmp); + init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST | ASYNC_TX_ACK, tx, + callback, &cmp, addr_conv); + tx = async_xor(xor_dest, xor_srcs, 0, xor_src_cnt, xor_len, &submit); + + async_tx_issue_pending_all(); + + wait_for_completion(&cmp); + } See include/linux/async_tx.h for more information on the flags. See the ops_run_* and ops_complete_* routines in drivers/md/raid5.c for more implementation examples. -4 DRIVER DEVELOPMENT NOTES +4. Driver Development Notes +=========================== + +4.1 Conformance points +---------------------- -4.1 Conformance points: There are a few conformance points required in dmaengine drivers to accommodate assumptions made by applications using the async_tx API: -1/ Completion callbacks are expected to happen in tasklet context -2/ dma_async_tx_descriptor fields are never manipulated in IRQ context -3/ Use async_tx_run_dependencies() in the descriptor clean up path to + +1. Completion callbacks are expected to happen in tasklet context +2. dma_async_tx_descriptor fields are never manipulated in IRQ context +3. Use async_tx_run_dependencies() in the descriptor clean up path to handle submission of dependent operations 4.2 "My application needs exclusive control of hardware channels" +----------------------------------------------------------------- + Primarily this requirement arises from cases where a DMA engine driver is being used to support device-to-memory operations. A channel that is performing these operations cannot, for many platform specific reasons, be shared. For these cases the dma_request_channel() interface is provided. -The interface is: -struct dma_chan *dma_request_channel(dma_cap_mask_t mask, - dma_filter_fn filter_fn, - void *filter_param); +The interface is:: -Where dma_filter_fn is defined as: -typedef bool (*dma_filter_fn)(struct dma_chan *chan, void *filter_param); + struct dma_chan *dma_request_channel(dma_cap_mask_t mask, + dma_filter_fn filter_fn, + void *filter_param); + +Where dma_filter_fn is defined as:: + + typedef bool (*dma_filter_fn)(struct dma_chan *chan, void *filter_param); When the optional 'filter_fn' parameter is set to NULL dma_request_channel simply returns the first channel that satisfies the @@ -207,19 +243,28 @@ private. Alternatively, it is set when dma_request_channel() finds an unused "public" channel. A couple caveats to note when implementing a driver and consumer: -1/ Once a channel has been privately allocated it will no longer be + +1. Once a channel has been privately allocated it will no longer be considered by the general-purpose allocator even after a call to dma_release_channel(). -2/ Since capabilities are specified at the device level a dma_device +2. Since capabilities are specified at the device level a dma_device with multiple channels will either have all channels public, or all channels private. -5 SOURCE - -include/linux/dmaengine.h: core header file for DMA drivers and api users -drivers/dma/dmaengine.c: offload engine channel management routines -drivers/dma/: location for offload engine drivers -include/linux/async_tx.h: core header file for the async_tx api -crypto/async_tx/async_tx.c: async_tx interface to dmaengine and common code -crypto/async_tx/async_memcpy.c: copy offload -crypto/async_tx/async_xor.c: xor and xor zero sum offload +5. Source +--------- + +include/linux/dmaengine.h: + core header file for DMA drivers and api users +drivers/dma/dmaengine.c: + offload engine channel management routines +drivers/dma/: + location for offload engine drivers +include/linux/async_tx.h: + core header file for the async_tx api +crypto/async_tx/async_tx.c: + async_tx interface to dmaengine and common code +crypto/async_tx/async_memcpy.c: + copy offload +crypto/async_tx/async_xor.c: + xor and xor zero sum offload diff --git a/Documentation/crypto/descore-readme.txt b/Documentation/crypto/descore-readme.rst index 16e9e6350755..45bd9c8babf4 100644 --- a/Documentation/crypto/descore-readme.txt +++ b/Documentation/crypto/descore-readme.rst @@ -1,8 +1,20 @@ -Below is the original README file from the descore.shar package. +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + +=========================================== +Fast & Portable DES encryption & decryption +=========================================== + +.. note:: + + Below is the original README file from the descore.shar package, + converted to ReST format. + ------------------------------------------------------------------------------ des - fast & portable DES encryption & decryption. -Copyright (C) 1992 Dana L. How + +Copyright |copy| 1992 Dana L. How This program is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by @@ -20,13 +32,12 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. Author's address: how@isl.stanford.edu -$Id: README,v 1.15 1992/05/20 00:25:32 how E $ - - -==>> To compile after untarring/unsharring, just `make' <<== +.. README,v 1.15 1992/05/20 00:25:32 how E +==>> To compile after untarring/unsharring, just ``make`` <<== This package was designed with the following goals: + 1. Highest possible encryption/decryption PERFORMANCE. 2. PORTABILITY to any byte-addressable host with a 32bit unsigned C type 3. Plug-compatible replacement for KERBEROS's low-level routines. @@ -36,7 +47,7 @@ register-starved machines. My discussions with Richard Outerbridge, 71755.204@compuserve.com, sparked a number of these enhancements. To more rapidly understand the code in this package, inspect desSmallFips.i -(created by typing `make') BEFORE you tackle desCode.h. The latter is set +(created by typing ``make``) BEFORE you tackle desCode.h. The latter is set up in a parameterized fashion so it can easily be modified by speed-daemon hackers in pursuit of that last microsecond. You will find it more illuminating to inspect one specific implementation, @@ -47,11 +58,13 @@ performance comparison to other available des code which i could compile on a SPARCStation 1 (cc -O4, gcc -O2): this code (byte-order independent): - 30us per encryption (options: 64k tables, no IP/FP) - 33us per encryption (options: 64k tables, FIPS standard bit ordering) - 45us per encryption (options: 2k tables, no IP/FP) - 48us per encryption (options: 2k tables, FIPS standard bit ordering) - 275us to set a new key (uses 1k of key tables) + + - 30us per encryption (options: 64k tables, no IP/FP) + - 33us per encryption (options: 64k tables, FIPS standard bit ordering) + - 45us per encryption (options: 2k tables, no IP/FP) + - 48us per encryption (options: 2k tables, FIPS standard bit ordering) + - 275us to set a new key (uses 1k of key tables) + this has the quickest encryption/decryption routines i've seen. since i was interested in fast des filters rather than crypt(3) and password cracking, i haven't really bothered yet to speed up @@ -63,15 +76,20 @@ this code (byte-order independent): are highly variable because of cache effects). kerberos des replacement from australia (version 1.95): - 53us per encryption (uses 2k of tables) - 96us to set a new key (uses 2.25k of key tables) + + - 53us per encryption (uses 2k of tables) + - 96us to set a new key (uses 2.25k of key tables) + so despite the author's inclusion of some of the performance improvements i had suggested to him, this package's encryption/decryption is still slower on the sparc and 68000. more specifically, 19-40% slower on the 68020 and 11-35% slower on the sparc, depending on the compiler; in full gory detail (ALT_ECB is a libdes variant): + + =============== ============== =============== ================= compiler machine desCore libdes ALT_ECB slower by + =============== ============== =============== ================= gcc 2.1 -O2 Sun 3/110 304 uS 369.5uS 461.8uS 22% cc -O1 Sun 3/110 336 uS 436.6uS 399.3uS 19% cc -O2 Sun 3/110 360 uS 532.4uS 505.1uS 40% @@ -79,10 +97,15 @@ kerberos des replacement from australia (version 1.95): gcc 2.1 -O2 Sun 4/50 48 uS 53.4uS 57.5uS 11% cc -O2 Sun 4/50 48 uS 64.6uS 64.7uS 35% cc -O4 Sun 4/50 48 uS 64.7uS 64.9uS 35% + =============== ============== =============== ================= + (my time measurements are not as accurate as his). + the comments in my first release of desCore on version 1.92: - 68us per encryption (uses 2k of tables) - 96us to set a new key (uses 2.25k of key tables) + + - 68us per encryption (uses 2k of tables) + - 96us to set a new key (uses 2.25k of key tables) + this is a very nice package which implements the most important of the optimizations which i did in my encryption routines. it's a bit weak on common low-level optimizations which is why @@ -91,48 +114,60 @@ kerberos des replacement from australia (version 1.95): speed up the key-setting routines with impressive results. (at some point i may do the same in my package). he also implements the rest of the mit des library. + (code from eay@psych.psy.uq.oz.au via comp.sources.misc) fast crypt(3) package from denmark: + the des routine here is buried inside a loop to do the crypt function and i didn't feel like ripping it out and measuring performance. his code takes 26 sparc instructions to compute one des iteration; above, Quick (64k) takes 21 and Small (2k) takes 37. he claims to use 280k of tables but the iteration calculation seems to use only 128k. his tables and code are machine independent. + (code from glad@daimi.aau.dk via alt.sources or comp.sources.misc) swedish reimplementation of Kerberos des library - 108us per encryption (uses 34k worth of tables) - 134us to set a new key (uses 32k of key tables to get this speed!) + + - 108us per encryption (uses 34k worth of tables) + - 134us to set a new key (uses 32k of key tables to get this speed!) + the tables used seem to be machine-independent; he seems to have included a lot of special case code - so that, e.g., `long' loads can be used instead of 4 `char' loads + so that, e.g., ``long`` loads can be used instead of 4 ``char`` loads when the machine's architecture allows it. + (code obtained from chalmers.se:pub/des) crack 3.3c package from england: + as in crypt above, the des routine is buried in a loop. it's also very modified for crypt. his iteration code uses 16k of tables and appears to be slow. + (code obtained from aem@aber.ac.uk via alt.sources or comp.sources.misc) -``highly optimized'' and tweaked Kerberos/Athena code (byte-order dependent): - 165us per encryption (uses 6k worth of tables) - 478us to set a new key (uses <1k of key tables) +``highly optimized`` and tweaked Kerberos/Athena code (byte-order dependent): + + - 165us per encryption (uses 6k worth of tables) + - 478us to set a new key (uses <1k of key tables) + so despite the comments in this code, it was possible to get faster code AND smaller tables, as well as making the tables machine-independent. (code obtained from prep.ai.mit.edu) UC Berkeley code (depends on machine-endedness): - 226us per encryption -10848us to set a new key + - 226us per encryption + - 10848us to set a new key + table sizes are unclear, but they don't look very small (code obtained from wuarchive.wustl.edu) motivation and history +====================== a while ago i wanted some des routines and the routines documented on sun's man pages either didn't exist or dumped core. i had heard of kerberos, @@ -142,10 +177,10 @@ it was too convoluted, the code had been written without taking advantage of the regular structure of operations such as IP, E, and FP (i.e. the author didn't sit down and think before coding), it was excessively slow, the author had attempted to clarify the code -by adding MORE statements to make the data movement more `consistent' +by adding MORE statements to make the data movement more ``consistent`` instead of simplifying his implementation and cutting down on all data movement (in particular, his use of L1, R1, L2, R2), and it was full of -idiotic `tweaks' for particular machines which failed to deliver significant +idiotic ``tweaks`` for particular machines which failed to deliver significant speedups but which did obfuscate everything. so i took the test data from his verification program and rewrote everything else. @@ -167,12 +202,13 @@ than versions hand-written in assembly for the sparc! porting notes +============= one thing i did not want to do was write an enormous mess which depended on endedness and other machine quirks, and which necessarily produced different code and different lookup tables for different machines. see the kerberos code for an example -of what i didn't want to do; all their endedness-specific `optimizations' +of what i didn't want to do; all their endedness-specific ``optimizations`` obfuscate the code and in the end were slower than a simpler machine independent approach. however, there are always some portability considerations of some kind, and i have included some options @@ -184,8 +220,8 @@ perhaps some will still regard the result as a mess! i assume word pointers can be freely cast to and from char pointers. note that 99% of C programs make these assumptions. i always use unsigned char's if the high bit could be set. -2) the typedef `word' means a 32 bit unsigned integral type. - if `unsigned long' is not 32 bits, change the typedef in desCore.h. +2) the typedef ``word`` means a 32 bit unsigned integral type. + if ``unsigned long`` is not 32 bits, change the typedef in desCore.h. i assume sizeof(word) == 4 EVERYWHERE. the (worst-case) cost of my NOT doing endedness-specific optimizations @@ -195,40 +231,46 @@ the input and output work areas do not need to be word-aligned. OPTIONAL performance optimizations +================================== -1) you should define one of `i386,' `vax,' `mc68000,' or `sparc,' +1) you should define one of ``i386,`` ``vax,`` ``mc68000,`` or ``sparc,`` whichever one is closest to the capabilities of your machine. see the start of desCode.h to see exactly what this selection implies. note that if you select the wrong one, the des code will still work; these are just performance tweaks. -2) for those with functional `asm' keywords: you should change the +2) for those with functional ``asm`` keywords: you should change the ROR and ROL macros to use machine rotate instructions if you have them. this will save 2 instructions and a temporary per use, or about 32 to 40 instructions per en/decryption. + note that gcc is smart enough to translate the ROL/R macros into machine rotates! these optimizations are all rather persnickety, yet with them you should be able to get performance equal to assembly-coding, except that: + 1) with the lack of a bit rotate operator in C, rotates have to be synthesized - from shifts. so access to `asm' will speed things up if your machine + from shifts. so access to ``asm`` will speed things up if your machine has rotates, as explained above in (3) (not necessary if you use gcc). 2) if your machine has less than 12 32-bit registers i doubt your compiler will generate good code. - `i386' tries to configure the code for a 386 by only declaring 3 registers + + ``i386`` tries to configure the code for a 386 by only declaring 3 registers (it appears that gcc can use ebx, esi and edi to hold register variables). however, if you like assembly coding, the 386 does have 7 32-bit registers, - and if you use ALL of them, use `scaled by 8' address modes with displacement + and if you use ALL of them, use ``scaled by 8`` address modes with displacement and other tricks, you can get reasonable routines for DesQuickCore... with about 250 instructions apiece. For DesSmall... it will help to rearrange des_keymap, i.e., now the sbox # is the high part of the index and the 6 bits of data is the low part; it helps to exchange these. + since i have no way to conveniently test it i have not provided my shoehorned 386 version. note that with this release of desCore, gcc is able to put everything in registers(!), and generate about 370 instructions apiece for the DesQuickCore... routines! coding notes +============ the en/decryption routines each use 6 necessary register variables, with 4 being actively used at once during the inner iterations. @@ -236,15 +278,18 @@ if you don't have 4 register variables get a new machine. up to 8 more registers are used to hold constants in some configurations. i assume that the use of a constant is more expensive than using a register: + a) additionally, i have tried to put the larger constants in registers. registering priority was by the following: - anything more than 12 bits (bad for RISC and CISC) - greater than 127 in value (can't use movq or byte immediate on CISC) - 9-127 (may not be able to use CISC shift immediate or add/sub quick), - 1-8 were never registered, being the cheapest constants. + + - anything more than 12 bits (bad for RISC and CISC) + - greater than 127 in value (can't use movq or byte immediate on CISC) + - 9-127 (may not be able to use CISC shift immediate or add/sub quick), + - 1-8 were never registered, being the cheapest constants. + b) the compiler may be too stupid to realize table and table+256 should be assigned to different constant registers and instead repetitively - do the arithmetic, so i assign these to explicit `m' register variables + do the arithmetic, so i assign these to explicit ``m`` register variables when possible and helpful. i assume that indexing is cheaper or equivalent to auto increment/decrement, @@ -253,25 +298,31 @@ this assumption is reversed for 68k and vax. i assume that addresses can be cheaply formed from two registers, or from a register and a small constant. -for the 68000, the `two registers and small offset' form is used sparingly. +for the 68000, the ``two registers and small offset`` form is used sparingly. all index scaling is done explicitly - no hidden shifts by log2(sizeof). the code is written so that even a dumb compiler should never need more than one hidden temporary, increasing the chance that everything will fit in the registers. KEEP THIS MORE SUBTLE POINT IN MIND IF YOU REWRITE ANYTHING. + (actually, there are some code fragments now which do require two temps, but fixing it would either break the structure of the macros or require declaring another temporary). special efficient data format +============================== + +bits are manipulated in this arrangement most of the time (S7 S5 S3 S1):: -bits are manipulated in this arrangement most of the time (S7 S5 S3 S1): 003130292827xxxx242322212019xxxx161514131211xxxx080706050403xxxx + (the x bits are still there, i'm just emphasizing where the S boxes are). -bits are rotated left 4 when computing S6 S4 S2 S0: +bits are rotated left 4 when computing S6 S4 S2 S0:: + 282726252423xxxx201918171615xxxx121110090807xxxx040302010031xxxx + the rightmost two bits are usually cleared so the lower byte can be used as an index into an sbox mapping table. the next two x'd bits are set to various values to access different parts of the tables. @@ -288,7 +339,7 @@ datatypes: must be long-aligned. DesQuickInit() - call this before using any other routine with `Quick' in its name. + call this before using any other routine with ``Quick`` in its name. it generates the special 64k table these routines need. DesQuickDone() frees this table @@ -298,6 +349,7 @@ DesMethod(m, k) which must have odd parity (or -1 is returned) and which must not be a (semi-)weak key (or -2 is returned). normally DesMethod() returns 0. + m is filled in from k so that when one of the routines below is called with m, the routine will act like standard des en/decryption with the key k. if you use DesMethod, @@ -308,19 +360,26 @@ DesMethod(m, k) will be set to magic constants which speed up the encryption/decryption on some machines. and yes, each byte controls a specific sbox during a specific iteration. + you really shouldn't use the 768bit format directly; i should provide a routine that converts 128 6-bit bytes (specified in S-box mapping order or something) into the right format for you. this would entail some byte concatenation and rotation. Des{Small|Quick}{Fips|Core}{Encrypt|Decrypt}(d, m, s) - performs des on the 8 bytes at s into the 8 bytes at d. (d,s: char *). + performs des on the 8 bytes at s into the 8 bytes at + ``d. (d,s: char *)``. + uses m as a 768bit key as explained above. + the Encrypt|Decrypt choice is obvious. + Fips|Core determines whether a completely standard FIPS initial and final permutation is done; if not, then the data is loaded and stored in a nonstandard bit order (FIPS w/o IP/FP). + Fips slows down Quick by 10%, Small by 9%. + Small|Quick determines whether you use the normal routine or the crazy quick one which gobbles up 64k more of memory. Small is 50% slower then Quick, but Quick needs 32 times as much @@ -329,15 +388,17 @@ Des{Small|Quick}{Fips|Core}{Encrypt|Decrypt}(d, m, s) Getting it to compile on your machine +===================================== there are no machine-dependencies in the code (see porting), -except perhaps the `now()' macro in desTest.c. +except perhaps the ``now()`` macro in desTest.c. ALL generated tables are machine independent. you should edit the Makefile with the appropriate optimization flags for your compiler (MAX optimization). Speeding up kerberos (and/or its des library) +============================================= note that i have included a kerberos-compatible interface in desUtil.c through the functions des_key_sched() and des_ecb_encrypt(). @@ -347,6 +408,7 @@ you should not need to #include desCore.h; just include the header file provided with the kerberos library. Other uses +========== the macros in desCode.h would be very useful for putting inline des functions in more complicated encryption routines. diff --git a/Documentation/crypto/index.rst b/Documentation/crypto/index.rst index c4ff5d791233..21338fa92642 100644 --- a/Documentation/crypto/index.rst +++ b/Documentation/crypto/index.rst @@ -17,9 +17,14 @@ for cryptographic use cases, as well as programming examples. :maxdepth: 2 intro + api-intro architecture + + async-tx-api + asymmetric-keys devel-algos userspace-if crypto_engine api api-samples + descore-readme diff --git a/Documentation/crypto/userspace-if.rst b/Documentation/crypto/userspace-if.rst index ff86befa61e0..52019e905900 100644 --- a/Documentation/crypto/userspace-if.rst +++ b/Documentation/crypto/userspace-if.rst @@ -23,7 +23,7 @@ user space, however. This includes the difference between synchronous and asynchronous invocations. The user space API call is fully synchronous. -[1] http://www.chronox.de/libkcapi.html +[1] https://www.chronox.de/libkcapi.html User Space API General Remarks ------------------------------ @@ -384,4 +384,4 @@ Please see [1] for libkcapi which provides an easy-to-use wrapper around the aforementioned Netlink kernel interface. [1] also contains a test application that invokes all libkcapi API calls. -[1] http://www.chronox.de/libkcapi.html +[1] https://www.chronox.de/libkcapi.html diff --git a/Documentation/dev-tools/coccinelle.rst b/Documentation/dev-tools/coccinelle.rst index 70274c3f5f5a..6c791af1c859 100644 --- a/Documentation/dev-tools/coccinelle.rst +++ b/Documentation/dev-tools/coccinelle.rst @@ -85,7 +85,7 @@ Four basic modes are defined: ``patch``, ``report``, ``context``, and file:line:column-column: message - ``context`` highlights lines of interest and their context in a - diff-like style.Lines of interest are indicated with ``-``. + diff-like style. Lines of interest are indicated with ``-``. - ``org`` generates a report in the Org mode format of Emacs. @@ -119,7 +119,7 @@ For each semantic patch, a commit message is proposed. It gives a description of the problem being checked by the semantic patch, and includes a reference to Coccinelle. -As any static code analyzer, Coccinelle produces false +As with any static code analyzer, Coccinelle produces false positives. Thus, reports must be carefully checked, and patches reviewed. @@ -135,18 +135,18 @@ the parallelism, set the J= variable. For example, to run across 4 CPUs:: make coccicheck MODE=report J=4 -As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization, +As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization; if support for this is detected you will benefit from parmap parallelization. When parmap is enabled coccicheck will enable dynamic load balancing by using -``--chunksize 1`` argument, this ensures we keep feeding threads with work +``--chunksize 1`` argument. This ensures we keep feeding threads with work one by one, so that we avoid the situation where most work gets done by only a few threads. With dynamic load balancing, if a thread finishes early we keep feeding it more work. When parmap is enabled, if an error occurs in Coccinelle, this error -value is propagated back, the return value of the ``make coccicheck`` -captures this return value. +value is propagated back, and the return value of the ``make coccicheck`` +command captures this return value. Using Coccinelle with a single semantic patch --------------------------------------------- @@ -183,7 +183,7 @@ To check only newly edited code, use the value 2 for the C flag, i.e.:: make C=2 CHECK="scripts/coccicheck" -In these modes, which works on a file basis, there is no information +In these modes, which work on a file basis, there is no information about semantic patches displayed, and no commit message proposed. This runs every semantic patch in scripts/coccinelle by default. The @@ -198,12 +198,12 @@ Debugging Coccinelle SmPL patches Using coccicheck is best as it provides in the spatch command line include options matching the options used when we compile the kernel. -You can learn what these options are by using V=1, you could then +You can learn what these options are by using V=1; you could then manually run Coccinelle with debug options added. Alternatively you can debug running Coccinelle against SmPL patches -by asking for stderr to be redirected to stderr, by default stderr -is redirected to /dev/null, if you'd like to capture stderr you +by asking for stderr to be redirected to stderr. By default stderr +is redirected to /dev/null; if you'd like to capture stderr you can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For instance:: @@ -211,8 +211,8 @@ instance:: make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err cat cocci.err -You can use SPFLAGS to add debugging flags, for instance you may want to -add both --profile --show-trying to SPFLAGS when debugging. For instance +You can use SPFLAGS to add debugging flags; for instance you may want to +add both --profile --show-trying to SPFLAGS when debugging. For example you may want to use:: rm -f err.log @@ -229,7 +229,7 @@ DEBUG_FILE support is only supported when using coccinelle >= 1.0.2. -------------------- Coccinelle supports reading .cocciconfig for default Coccinelle options that -should be used every time spatch is spawned, the order of precedence for +should be used every time spatch is spawned. The order of precedence for variables for .cocciconfig is as follows: - Your current user's home directory is processed first @@ -237,7 +237,7 @@ variables for .cocciconfig is as follows: - The directory provided with the --dir option is processed last, if used Since coccicheck runs through make, it naturally runs from the kernel -proper dir, as such the second rule above would be implied for picking up a +proper dir; as such the second rule above would be implied for picking up a .cocciconfig when using ``make coccicheck``. ``make coccicheck`` also supports using M= targets. If you do not supply @@ -260,13 +260,13 @@ If not using the kernel's coccicheck target, keep the above precedence order logic of .cocciconfig reading. If using the kernel's coccicheck target, override any of the kernel's .coccicheck's settings using SPFLAGS. -We help Coccinelle when used against Linux with a set of sensible defaults +We help Coccinelle when used against Linux with a set of sensible default options for Linux with our own Linux .cocciconfig. This hints to coccinelle -git can be used for ``git grep`` queries over coccigrep. A timeout of 200 +that git can be used for ``git grep`` queries over coccigrep. A timeout of 200 seconds should suffice for now. The options picked up by coccinelle when reading a .cocciconfig do not appear -as arguments to spatch processes running on your system, to confirm what +as arguments to spatch processes running on your system. To confirm what options will be used by Coccinelle run:: spatch --print-options-only @@ -290,7 +290,7 @@ given to it when options are in conflict. :: Coccinelle supports idutils as well but requires coccinelle >= 1.0.6. When no ID file is specified coccinelle assumes your ID database file -is in the file .id-utils.index on the top level of the kernel, coccinelle +is in the file .id-utils.index on the top level of the kernel. Coccinelle carries a script scripts/idutils_index.sh which creates the database with:: mkid -i C --output .id-utils.index @@ -317,7 +317,7 @@ SmPL patch specific options --------------------------- SmPL patches can have their own requirements for options passed -to Coccinelle. SmPL patch specific options can be provided by +to Coccinelle. SmPL patch-specific options can be provided by providing them at the top of the SmPL patch, for instance:: // Options: --no-includes --include-headers @@ -327,7 +327,7 @@ SmPL patch Coccinelle requirements As Coccinelle features get added some more advanced SmPL patches may require newer versions of Coccinelle. If an SmPL patch requires -at least a version of Coccinelle, this can be specified as follows, +a minimum version of Coccinelle, this can be specified as follows, as an example if requiring at least Coccinelle >= 1.0.5:: // Requires: 1.0.5 diff --git a/Documentation/dev-tools/gcov.rst b/Documentation/dev-tools/gcov.rst index 7bd013596217..9e989baae154 100644 --- a/Documentation/dev-tools/gcov.rst +++ b/Documentation/dev-tools/gcov.rst @@ -22,7 +22,7 @@ Possible uses: * minimizing kernel configurations (do I need this option if the associated code is never run?) -.. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html +.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html .. _lcov: http://ltp.sourceforge.net/coverage/lcov.php @@ -171,7 +171,7 @@ Note on compilers GCC and LLVM gcov tools are not necessarily compatible. Use gcov_ to work with GCC-generated .gcno and .gcda files, and use llvm-cov_ for Clang. -.. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html +.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html .. _llvm-cov: https://llvm.org/docs/CommandGuide/llvm-cov.html Build differences between GCC and Clang gcov are handled by Kconfig. It diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index c652d740735d..38fd5681fade 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -13,11 +13,8 @@ KASAN uses compile-time instrumentation to insert validity checks before every memory access, and therefore requires a compiler version that supports that. Generic KASAN is supported in both GCC and Clang. With GCC it requires version -4.9.2 or later for basic support and version 5.0 or later for detection of -out-of-bounds accesses for stack and global variables and for inline -instrumentation mode (see the Usage section). With Clang it requires version -7.0.0 or later and it doesn't support detection of out-of-bounds accesses for -global variables yet. +8.3.0 or later. With Clang it requires version 7.0.0 or later, but detection of +out-of-bounds accesses for global variables is only supported since Clang 11. Tag-based KASAN is only supported in Clang and requires version 7.0.0 or later. @@ -193,6 +190,9 @@ function calls GCC directly inserts the code to check the shadow memory. This option significantly enlarges kernel but it gives x1.1-x2 performance boost over outline instrumented kernel. +Generic KASAN prints up to 2 call_rcu() call stacks in reports, the last one +and the second to last. + Software tag-based KASAN ~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/dev-tools/kcsan.rst b/Documentation/dev-tools/kcsan.rst index ce4bbd918648..be7a0b0e1f28 100644 --- a/Documentation/dev-tools/kcsan.rst +++ b/Documentation/dev-tools/kcsan.rst @@ -8,7 +8,8 @@ approach to detect races. KCSAN's primary purpose is to detect `data races`_. Usage ----- -KCSAN requires Clang version 11 or later. +KCSAN is supported by both GCC and Clang. With GCC we require version 11 or +later, and with Clang also require version 11 or later. To enable KCSAN configure the kernel with:: @@ -114,12 +115,6 @@ the below options are available: To dynamically limit for which functions to generate reports, see the `DebugFS interface`_ blacklist/whitelist feature. - For ``__always_inline`` functions, replace ``__always_inline`` with - ``__no_kcsan_or_inline`` (which implies ``__always_inline``):: - - static __no_kcsan_or_inline void foo(void) { - ... - * To disable data race detection for a particular compilation unit, add to the ``Makefile``:: diff --git a/Documentation/dev-tools/kgdb.rst b/Documentation/dev-tools/kgdb.rst index 61293f40bc6e..0e52e966a153 100644 --- a/Documentation/dev-tools/kgdb.rst +++ b/Documentation/dev-tools/kgdb.rst @@ -872,7 +872,7 @@ The kgdboc driver contains logic to configure communications with an attached keyboard. The keyboard infrastructure is only compiled into the kernel when ``CONFIG_KDB_KEYBOARD=y`` is set in the kernel configuration. -The core polled keyboard driver driver for PS/2 type keyboards is in +The core polled keyboard driver for PS/2 type keyboards is in ``drivers/char/kdb_keyboard.c``. This driver is hooked into the debug core when kgdboc populates the callback in the array called :c:type:`kdb_poll_funcs[]`. The :c:func:`kdb_get_kbd_char` is the top-level diff --git a/Documentation/dev-tools/kmemleak.rst b/Documentation/dev-tools/kmemleak.rst index fce262883984..a41a2d238af2 100644 --- a/Documentation/dev-tools/kmemleak.rst +++ b/Documentation/dev-tools/kmemleak.rst @@ -8,8 +8,6 @@ with the difference that the orphan objects are not freed but only reported via /sys/kernel/debug/kmemleak. A similar method is used by the Valgrind tool (``memcheck --leak-check``) to detect the memory leaks in user-space applications. -Kmemleak is supported on x86, arm, arm64, powerpc, sparc, sh, microblaze, mips, -s390, nds32, arc and xtensa. Usage ----- diff --git a/Documentation/dev-tools/kunit/faq.rst b/Documentation/dev-tools/kunit/faq.rst index ea55b2467653..1628862e7024 100644 --- a/Documentation/dev-tools/kunit/faq.rst +++ b/Documentation/dev-tools/kunit/faq.rst @@ -61,3 +61,43 @@ test, or an end-to-end test. kernel by installing a production configuration of the kernel on production hardware with a production userspace and then trying to exercise some behavior that depends on interactions between the hardware, the kernel, and userspace. + +KUnit isn't working, what should I do? +====================================== + +Unfortunately, there are a number of things which can break, but here are some +things to try. + +1. Try running ``./tools/testing/kunit/kunit.py run`` with the ``--raw_output`` + parameter. This might show details or error messages hidden by the kunit_tool + parser. +2. Instead of running ``kunit.py run``, try running ``kunit.py config``, + ``kunit.py build``, and ``kunit.py exec`` independently. This can help track + down where an issue is occurring. (If you think the parser is at fault, you + can run it manually against stdin or a file with ``kunit.py parse``.) +3. Running the UML kernel directly can often reveal issues or error messages + kunit_tool ignores. This should be as simple as running ``./vmlinux`` after + building the UML kernel (e.g., by using ``kunit.py build``). Note that UML + has some unusual requirements (such as the host having a tmpfs filesystem + mounted), and has had issues in the past when built statically and the host + has KASLR enabled. (On older host kernels, you may need to run ``setarch + `uname -m` -R ./vmlinux`` to disable KASLR.) +4. Make sure the kernel .config has ``CONFIG_KUNIT=y`` and at least one test + (e.g. ``CONFIG_KUNIT_EXAMPLE_TEST=y``). kunit_tool will keep its .config + around, so you can see what config was used after running ``kunit.py run``. + It also preserves any config changes you might make, so you can + enable/disable things with ``make ARCH=um menuconfig`` or similar, and then + re-run kunit_tool. +5. Try to run ``make ARCH=um defconfig`` before running ``kunit.py run``. This + may help clean up any residual config items which could be causing problems. +6. Finally, try running KUnit outside UML. KUnit and KUnit tests can run be + built into any kernel, or can be built as a module and loaded at runtime. + Doing so should allow you to determine if UML is causing the issue you're + seeing. When tests are built-in, they will execute when the kernel boots, and + modules will automatically execute associated tests when loaded. Test results + can be collected from ``/sys/kernel/debug/kunit/<test suite>/results``, and + can be parsed with ``kunit.py parse``. For more details, see "KUnit on + non-UML architectures" in :doc:`usage`. + +If none of the above tricks help, you are always welcome to email any issues to +kunit-dev@googlegroups.com. diff --git a/Documentation/dev-tools/kunit/kunit-tool.rst b/Documentation/dev-tools/kunit/kunit-tool.rst index 949af2da81e5..29ae2fee8123 100644 --- a/Documentation/dev-tools/kunit/kunit-tool.rst +++ b/Documentation/dev-tools/kunit/kunit-tool.rst @@ -19,13 +19,13 @@ compiles the kernel as a standalone Linux executable that can be run like any other program directly inside of a host operating system. To be clear, it does not require any virtualization support: it is just a regular program. -What is a kunitconfig? -====================== +What is a .kunitconfig? +======================= It's just a defconfig that kunit_tool looks for in the base directory. kunit_tool uses it to generate a .config as you might expect. In addition, it verifies that the generated .config contains the CONFIG options in the -kunitconfig; the reason it does this is so that it is easy to be sure that a +.kunitconfig; the reason it does this is so that it is easy to be sure that a CONFIG that enables a test actually ends up in the .config. How do I use kunit_tool? @@ -46,16 +46,9 @@ However, you most likely want to use it with the following options: - ``--timeout`` sets a maximum amount of time to allow tests to run. - ``--jobs`` sets the number of threads to use to build the kernel. -If you just want to use the defconfig that ships with the kernel, you can -append the ``--defconfig`` flag as well: - -.. code-block:: bash - - ./tools/testing/kunit/kunit.py run --timeout=30 --jobs=`nproc --all` --defconfig - .. note:: - This command is particularly helpful for getting started because it - just works. No kunitconfig needs to be present. + This command will work even without a .kunitconfig file: if no + .kunitconfig is present, a default one will be used instead. For a list of all the flags supported by kunit_tool, you can run: diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst index bb112cf70624..d23385e3e159 100644 --- a/Documentation/dev-tools/kunit/start.rst +++ b/Documentation/dev-tools/kunit/start.rst @@ -18,7 +18,7 @@ The wrapper can be run with: .. code-block:: bash - ./tools/testing/kunit/kunit.py run --defconfig + ./tools/testing/kunit/kunit.py run For more information on this wrapper (also called kunit_tool) check out the :doc:`kunit-tool` page. diff --git a/Documentation/dev-tools/sparse.rst b/Documentation/dev-tools/sparse.rst index 6f4870528226..02102be7ff49 100644 --- a/Documentation/dev-tools/sparse.rst +++ b/Documentation/dev-tools/sparse.rst @@ -9,6 +9,8 @@ Sparse is a semantic checker for C programs; it can be used to find a number of potential problems with kernel code. See https://lwn.net/Articles/689907/ for an overview of sparse; this document contains some kernel-specific sparse information. +More information on sparse, mainly about its internals, can be found in +its official pages at https://sparse.docs.kernel.org. Using sparse for typechecking @@ -73,8 +75,8 @@ sparse would otherwise report a context imbalance. Getting sparse -------------- -You can get latest released versions from the Sparse homepage at -https://sparse.wiki.kernel.org/index.php/Main_Page +You can get tarballs of the latest released versions from: +https://www.kernel.org/pub/software/devel/sparse/dist/ Alternatively, you can get snapshots of the latest development version of sparse using git to clone:: diff --git a/Documentation/devicetree/bindings/Makefile b/Documentation/devicetree/bindings/Makefile index a63898954068..91c4d00e96d3 100644 --- a/Documentation/devicetree/bindings/Makefile +++ b/Documentation/devicetree/bindings/Makefile @@ -2,7 +2,6 @@ DT_DOC_CHECKER ?= dt-doc-validate DT_EXTRACT_EX ?= dt-extract-example DT_MK_SCHEMA ?= dt-mk-schema -DT_MK_SCHEMA_USERONLY_FLAG := $(if $(DT_SCHEMA_FILES), -u) DT_SCHEMA_MIN_VERSION = 2020.5 @@ -35,21 +34,40 @@ quiet_cmd_mk_schema = SCHEMA $@ DT_DOCS = $(shell $(find_cmd) | sed -e 's|^$(srctree)/||') -DT_SCHEMA_FILES ?= $(DT_DOCS) - -extra-$(CHECK_DT_BINDING) += $(patsubst $(src)/%.yaml,%.example.dts, $(DT_SCHEMA_FILES)) -extra-$(CHECK_DT_BINDING) += $(patsubst $(src)/%.yaml,%.example.dt.yaml, $(DT_SCHEMA_FILES)) -extra-$(CHECK_DT_BINDING) += processed-schema-examples.yaml - override DTC_FLAGS := \ -Wno-avoid_unnecessary_addr_size \ - -Wno-graph_child_address + -Wno-graph_child_address \ + -Wno-interrupt_provider $(obj)/processed-schema-examples.yaml: $(DT_DOCS) check_dtschema_version FORCE $(call if_changed,mk_schema) -$(obj)/processed-schema.yaml: DT_MK_SCHEMA_FLAGS := $(DT_MK_SCHEMA_USERONLY_FLAG) +ifeq ($(DT_SCHEMA_FILES),) + +# Unless DT_SCHEMA_FILES is specified, use the full schema for dtbs_check too. +# Just copy processed-schema-examples.yaml + +$(obj)/processed-schema.yaml: $(obj)/processed-schema-examples.yaml FORCE + $(call if_changed,copy) + +DT_SCHEMA_FILES = $(DT_DOCS) + +else + +# If DT_SCHEMA_FILES is specified, use it for processed-schema.yaml + +$(obj)/processed-schema.yaml: DT_MK_SCHEMA_FLAGS := -u $(obj)/processed-schema.yaml: $(DT_SCHEMA_FILES) check_dtschema_version FORCE $(call if_changed,mk_schema) -extra-y += processed-schema.yaml +endif + +extra-$(CHECK_DT_BINDING) += $(patsubst $(src)/%.yaml,%.example.dts, $(DT_SCHEMA_FILES)) +extra-$(CHECK_DT_BINDING) += $(patsubst $(src)/%.yaml,%.example.dt.yaml, $(DT_SCHEMA_FILES)) +extra-$(CHECK_DT_BINDING) += processed-schema-examples.yaml +extra-$(CHECK_DTBS) += processed-schema.yaml + +# Hack: avoid 'Argument list too long' error for 'make clean'. Remove most of +# build artifacts here before they are processed by scripts/Makefile.clean +clean-files = $(shell find $(obj) \( -name '*.example.dts' -o \ + -name '*.example.dt.yaml' \) -delete 2>/dev/null) diff --git a/Documentation/devicetree/bindings/arm/al,alpine.yaml b/Documentation/devicetree/bindings/arm/al,alpine.yaml deleted file mode 100644 index a70dff277e05..000000000000 --- a/Documentation/devicetree/bindings/arm/al,alpine.yaml +++ /dev/null @@ -1,21 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/arm/al,alpine.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Annapurna Labs Alpine Platform Device Tree Bindings - -maintainers: - - Tsahee Zidenberg <tsahee@annapurnalabs.com> - - Antoine Tenart <antoine.tenart@bootlin.com> - -properties: - compatible: - items: - - const: al,alpine - model: - items: - - const: "Annapurna Labs Alpine Dev Board" - -... diff --git a/Documentation/devicetree/bindings/arm/amazon,al.yaml b/Documentation/devicetree/bindings/arm/amazon,al.yaml new file mode 100644 index 000000000000..a3a4d710bd02 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/amazon,al.yaml @@ -0,0 +1,33 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/amazon,al.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amazon's Annapurna Labs Alpine Platform Device Tree Bindings + +maintainers: + - Hanna Hawa <hhhawa@amazon.com> + - Talel Shenhar <talel@amazon.com>, <talelshenhar@gmail.com> + - Ronen Krupnik <ronenk@amazon.com> + +properties: + compatible: + oneOf: + - description: Boards with Alpine V1 SoC + items: + - const: al,alpine + + - description: Boards with Alpine V2 SoC + items: + - enum: + - al,alpine-v2-evp + - const: al,alpine-v2 + + - description: Boards with Alpine V3 SoC + items: + - enum: + - amazon,al-alpine-v3-evp + - const: amazon,al-alpine-v3 + +... diff --git a/Documentation/devicetree/bindings/arm/amlogic.yaml b/Documentation/devicetree/bindings/arm/amlogic.yaml index 378229fa8310..5eba9f48823e 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.yaml +++ b/Documentation/devicetree/bindings/arm/amlogic.yaml @@ -121,6 +121,7 @@ properties: - libretech,aml-s912-pc - nexbox,a1 - tronsmart,vega-s96 + - wetek,core2 - const: amlogic,s912 - const: amlogic,meson-gxm diff --git a/Documentation/devicetree/bindings/arm/arm,scmi.txt b/Documentation/devicetree/bindings/arm/arm,scmi.txt index 1f293ea24cd8..55deb68230eb 100644 --- a/Documentation/devicetree/bindings/arm/arm,scmi.txt +++ b/Documentation/devicetree/bindings/arm/arm,scmi.txt @@ -102,7 +102,7 @@ Required sub-node properties: [0] http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/index.html [1] Documentation/devicetree/bindings/clock/clock-bindings.txt [2] Documentation/devicetree/bindings/power/power-domain.yaml -[3] Documentation/devicetree/bindings/thermal/thermal.txt +[3] Documentation/devicetree/bindings/thermal/thermal*.yaml [4] Documentation/devicetree/bindings/sram/sram.yaml [5] Documentation/devicetree/bindings/reset/reset.txt diff --git a/Documentation/devicetree/bindings/arm/arm,scpi.txt b/Documentation/devicetree/bindings/arm/arm,scpi.txt index dd04d9d9a1b8..bcd6c3ec471e 100644 --- a/Documentation/devicetree/bindings/arm/arm,scpi.txt +++ b/Documentation/devicetree/bindings/arm/arm,scpi.txt @@ -108,7 +108,7 @@ Required properties: [0] http://infocenter.arm.com/help/topic/com.arm.doc.dui0922b/index.html [1] Documentation/devicetree/bindings/clock/clock-bindings.txt -[2] Documentation/devicetree/bindings/thermal/thermal.txt +[2] Documentation/devicetree/bindings/thermal/thermal*.yaml [3] Documentation/devicetree/bindings/sram/sram.yaml [4] Documentation/devicetree/bindings/power/power-domain.yaml diff --git a/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.txt b/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.txt deleted file mode 100644 index 6824b3180ffb..000000000000 --- a/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.txt +++ /dev/null @@ -1,14 +0,0 @@ -Raspberry Pi VideoCore firmware driver - -Required properties: - -- compatible: Should be "raspberrypi,bcm2835-firmware" -- mboxes: Phandle to the firmware device's Mailbox. - (See: ../mailbox/mailbox.txt for more information) - -Example: - -firmware { - compatible = "raspberrypi,bcm2835-firmware"; - mboxes = <&mailbox>; -}; diff --git a/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml b/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml new file mode 100644 index 000000000000..b48ed875eb8e --- /dev/null +++ b/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/bcm/raspberrypi,bcm2835-firmware.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Raspberry Pi VideoCore firmware driver + +maintainers: + - Eric Anholt <eric@anholt.net> + - Stefan Wahren <wahrenst@gmx.net> + +properties: + compatible: + items: + - const: raspberrypi,bcm2835-firmware + - const: simple-bus + + mboxes: + $ref: '/schemas/types.yaml#/definitions/phandle' + description: | + Phandle to the firmware device's Mailbox. + (See: ../mailbox/mailbox.txt for more information) + + clocks: + type: object + + properties: + compatible: + const: raspberrypi,firmware-clocks + + "#clock-cells": + const: 1 + description: > + The argument is the ID of the clocks contained by the + firmware messages. + + required: + - compatible + - "#clock-cells" + + additionalProperties: false + +required: + - compatible + - mboxes + +examples: + - | + firmware { + compatible = "raspberrypi,bcm2835-firmware", "simple-bus"; + mboxes = <&mailbox>; + + firmware_clocks: clocks { + compatible = "raspberrypi,firmware-clocks"; + #clock-cells = <1>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/arm/coresight.txt b/Documentation/devicetree/bindings/arm/coresight.txt index 846f6daae71b..d711676b4a51 100644 --- a/Documentation/devicetree/bindings/arm/coresight.txt +++ b/Documentation/devicetree/bindings/arm/coresight.txt @@ -108,6 +108,13 @@ its hardware characteristcs. * arm,cp14: must be present if the system accesses ETM/PTM management registers via co-processor 14. + * qcom,skip-power-up: boolean. Indicates that an implementation can + skip powering up the trace unit. TRCPDCR.PU does not have to be set + on Qualcomm Technologies Inc. systems since ETMs are in the same power + domain as their CPU cores. This property is required to identify such + systems with hardware errata where the CPU watchdog counter is stopped + when TRCPDCR.PU is set. + * Optional property for TMC: * arm,buffer-size: size of contiguous buffer space for TMC ETR @@ -121,6 +128,12 @@ its hardware characteristcs. * interrupts : Exactly one SPI may be listed for reporting the address error +* Optional property for configurable replicators: + + * qcom,replicator-loses-context: boolean. Indicates that the replicator + will lose register context when AMBA clock is removed which is observed + in some replicator designs. + Graph bindings for Coresight ------------------------------- diff --git a/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt b/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt index 715047444391..6064d98b1031 100644 --- a/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt +++ b/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt @@ -47,7 +47,7 @@ Required properties: &lsio_mu1 1 2 &lsio_mu1 1 3 &lsio_mu1 3 3>; - See Documentation/devicetree/bindings/mailbox/fsl,mu.txt + See Documentation/devicetree/bindings/mailbox/fsl,mu.yaml for detailed mailbox binding. Note: Each mu which supports general interrupt should have an alias correctly @@ -176,7 +176,7 @@ Required properties: "fsl,imx8qxp-sc-thermal" followed by "fsl,imx-sc-thermal"; -- #thermal-sensor-cells: See Documentation/devicetree/bindings/thermal/thermal.txt +- #thermal-sensor-cells: See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for a description. Example (imx8qxp): diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml index 05906e291e38..f63895c8ce2d 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -120,6 +120,8 @@ properties: - fsl,imx6q-sabrelite - fsl,imx6q-sabresd - kontron,imx6q-samx6i # Kontron i.MX6 Dual/Quad SMARC Module + - prt,prti6q # Protonic PRTI6Q board + - prt,prtwd2 # Protonic WD2 board - technexion,imx6q-pico-dwarf # TechNexion i.MX6Q Pico-Dwarf - technexion,imx6q-pico-hobbit # TechNexion i.MX6Q Pico-Hobbit - technexion,imx6q-pico-nymph # TechNexion i.MX6Q Pico-Nymph @@ -172,6 +174,8 @@ properties: - fsl,imx6dl-sabreauto # i.MX6 DualLite/Solo SABRE Automotive Board - fsl,imx6dl-sabresd # i.MX6 DualLite SABRE Smart Device Board - kontron,imx6dl-samx6i # Kontron i.MX6 Solo SMARC Module + - prt,prtrvt # Protonic RVT board + - prt,prtvt7 # Protonic VT7 board - technexion,imx6dl-pico-dwarf # TechNexion i.MX6DL Pico-Dwarf - technexion,imx6dl-pico-hobbit # TechNexion i.MX6DL Pico-Hobbit - technexion,imx6dl-pico-nymph # TechNexion i.MX6DL Pico-Nymph @@ -268,6 +272,7 @@ properties: - armadeus,imx6ull-opos6uldev # OPOS6UL (i.MX6ULL) SoM on OPOS6ULDev board - fsl,imx6ull-14x14-evk # i.MX6 UltraLiteLite 14x14 EVK Board - kontron,imx6ull-n6411-som # Kontron N6411 SOM + - myir,imx6ull-mys-6ulx-eval # MYiR Tech iMX6ULL Evaluation Board - toradex,colibri-imx6ull-eval # Colibri iMX6ULL Module on Colibri Evaluation Board - toradex,colibri-imx6ull-wifi-eval # Colibri iMX6ULL Wi-Fi / Bluetooth Module on Colibri Evaluation Board - const: fsl,imx6ull diff --git a/Documentation/devicetree/bindings/arm/intel,keembay.yaml b/Documentation/devicetree/bindings/arm/intel,keembay.yaml new file mode 100644 index 000000000000..4d925785f504 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/intel,keembay.yaml @@ -0,0 +1,19 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/intel,keembay.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Keem Bay platform device tree bindings + +maintainers: + - Paul J. Murphy <paul.j.murphy@intel.com> + - Daniele Alessandrelli <daniele.alessandrelli@intel.com> + +properties: + compatible: + items: + - enum: + - intel,keembay-evm + - const: intel,keembay +... diff --git a/Documentation/devicetree/bindings/arm/marvell/ap80x-system-controller.txt b/Documentation/devicetree/bindings/arm/marvell/ap80x-system-controller.txt index 098d932fc963..e31511255d8e 100644 --- a/Documentation/devicetree/bindings/arm/marvell/ap80x-system-controller.txt +++ b/Documentation/devicetree/bindings/arm/marvell/ap80x-system-controller.txt @@ -111,7 +111,7 @@ Thermal: -------- For common binding part and usage, refer to -Documentation/devicetree/bindings/thermal/thermal.txt +Documentation/devicetree/bindings/thermal/thermal*.yaml The thermal IP can probe the temperature all around the processor. It may feature several channels, each of them wired to one sensor. diff --git a/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt b/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt index f982a8ed9396..a21f7709596c 100644 --- a/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt +++ b/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt @@ -203,7 +203,7 @@ It is possible to setup an overheat interrupt by giving at least one critical point to any subnode of the thermal-zone node. For common binding part and usage, refer to -Documentation/devicetree/bindings/thermal/thermal.txt +Documentation/devicetree/bindings/thermal/thermal*.yaml Required properties: - compatible: must be one of: diff --git a/Documentation/devicetree/bindings/arm/mediatek.yaml b/Documentation/devicetree/bindings/arm/mediatek.yaml index abc544dde692..30908963ae26 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek.yaml @@ -114,4 +114,9 @@ properties: - enum: - mediatek,mt8183-evb - const: mediatek,mt8183 + - description: Google Krane (Lenovo IdeaPad Duet, 10e,...) + items: + - const: google,krane-sku176 + - const: google,krane + - const: mediatek,mt8183 ... diff --git a/Documentation/devicetree/bindings/arm/microchip,sparx5.yaml b/Documentation/devicetree/bindings/arm/microchip,sparx5.yaml new file mode 100644 index 000000000000..ecf6fa12e6ad --- /dev/null +++ b/Documentation/devicetree/bindings/arm/microchip,sparx5.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/microchip,sparx5.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip Sparx5 Boards Device Tree Bindings + +maintainers: + - Lars Povlsen <lars.povlsen@microchip.com> + +description: |+ + The Microchip Sparx5 SoC is a ARMv8-based used in a family of + gigabit TSN-capable gigabit switches. + + The SparX-5 Ethernet switch family provides a rich set of switching + features such as advanced TCAM-based VLAN and QoS processing + enabling delivery of differentiated services, and security through + TCAM-based frame processing using versatile content aware processor + (VCAP) + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - description: The Sparx5 pcb125 board is a modular board, + which has both spi-nor and eMMC storage. The modular design + allows for connection of different network ports. + items: + - const: microchip,sparx5-pcb125 + - const: microchip,sparx5 + + - description: The Sparx5 pcb134 is a pizzabox form factor + gigabit switch with 20 SFP ports. It features spi-nor and + either spi-nand or eMMC storage (mount option). + items: + - const: microchip,sparx5-pcb134 + - const: microchip,sparx5 + + - description: The Sparx5 pcb135 is a pizzabox form factor + gigabit switch with 48+4 Cu ports. It features spi-nor and + either spi-nand or eMMC storage (mount option). + items: + - const: microchip,sparx5-pcb135 + - const: microchip,sparx5 + + axi@600000000: + type: object + description: the root node in the Sparx5 platforms must contain + an axi bus child node. They are always at physical address + 0x600000000 in all the Sparx5 variants. + properties: + compatible: + items: + - const: simple-bus + + required: + - compatible + +required: + - compatible + - axi@600000000 + +... diff --git a/Documentation/devicetree/bindings/arm/mstar/mstar,l3bridge.yaml b/Documentation/devicetree/bindings/arm/mstar/mstar,l3bridge.yaml new file mode 100644 index 000000000000..6816bd68f9cf --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mstar/mstar,l3bridge.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2020 thingy.jp. +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/arm/mstar/mstar,l3bridge.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: MStar/SigmaStar Armv7 SoC l3bridge + +maintainers: + - Daniel Palmer <daniel@thingy.jp> + +description: | + MStar/SigmaStar's Armv7 SoCs have a pipeline in the interface + between the CPU and memory. This means that before DMA capable + devices are allowed to run the pipeline must be flushed to ensure + everything is in memory. + + The l3bridge region contains registers that allow such a flush + to be triggered. + + This node is used by the platform code to find where the registers + are and install a barrier that triggers the required pipeline flush. + +properties: + compatible: + items: + - const: mstar,l3bridge + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + l3bridge: l3bridge@1f204400 { + compatible = "mstar,l3bridge"; + reg = <0x1f204400 0x200>; + }; diff --git a/Documentation/devicetree/bindings/arm/mstar/mstar.yaml b/Documentation/devicetree/bindings/arm/mstar/mstar.yaml new file mode 100644 index 000000000000..c2f980b00b06 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mstar/mstar.yaml @@ -0,0 +1,33 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/mstar/mstar.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MStar platforms device tree bindings + +maintainers: + - Daniel Palmer <daniel@thingy.jp> + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - description: infinity boards + items: + - enum: + - thingyjp,breadbee-crust # thingy.jp BreadBee Crust + - const: mstar,infinity + + - description: infinity3 boards + items: + - enum: + - thingyjp,breadbee # thingy.jp BreadBee + - const: mstar,infinity3 + + - description: mercury5 boards + items: + - enum: + - 70mai,midrived08 # 70mai midrive d08 + - const: mstar,mercury5 diff --git a/Documentation/devicetree/bindings/arm/nvidia,tegra194-ccplex.yaml b/Documentation/devicetree/bindings/arm/nvidia,tegra194-ccplex.yaml new file mode 100644 index 000000000000..1043e4be4fca --- /dev/null +++ b/Documentation/devicetree/bindings/arm/nvidia,tegra194-ccplex.yaml @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/arm/nvidia,tegra194-ccplex.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: NVIDIA Tegra194 CPU Complex device tree bindings + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jonathan Hunter <jonathanh@nvidia.com> + - Sumit Gupta <sumitg@nvidia.com> + +description: |+ + Tegra194 SOC has homogeneous architecture where each cluster has two + symmetric cores. Compatible string in "cpus" node represents the CPU + Complex having all clusters. + +properties: + $nodename: + const: cpus + + compatible: + enum: + - nvidia,tegra194-ccplex + + nvidia,bpmp: + $ref: '/schemas/types.yaml#/definitions/phandle' + description: | + Specifies the bpmp node that needs to be queried to get + operating point data for all CPUs. + +examples: + - | + cpus { + compatible = "nvidia,tegra194-ccplex"; + nvidia,bpmp = <&bpmp>; + #address-cells = <1>; + #size-cells = <0>; + + cpu0_0: cpu@0 { + compatible = "nvidia,tegra194-carmel"; + device_type = "cpu"; + reg = <0x0>; + enable-method = "psci"; + }; + + cpu0_1: cpu@1 { + compatible = "nvidia,tegra194-carmel"; + device_type = "cpu"; + reg = <0x001>; + enable-method = "psci"; + }; + + cpu1_0: cpu@100 { + compatible = "nvidia,tegra194-carmel"; + device_type = "cpu"; + reg = <0x100>; + enable-method = "psci"; + }; + + cpu1_1: cpu@101 { + compatible = "nvidia,tegra194-carmel"; + device_type = "cpu"; + reg = <0x101>; + enable-method = "psci"; + }; + }; +... diff --git a/Documentation/devicetree/bindings/arm/renesas.yaml b/Documentation/devicetree/bindings/arm/renesas.yaml index b7d2e921150a..0d4dabb4a164 100644 --- a/Documentation/devicetree/bindings/arm/renesas.yaml +++ b/Documentation/devicetree/bindings/arm/renesas.yaml @@ -118,6 +118,7 @@ properties: items: - enum: - hoperun,hihope-rzg2m # HopeRun HiHope RZ/G2M platform + - beacon,beacon-rzg2m # Beacon EmbeddedWorks RZ/G2M Kit - const: renesas,r8a774a1 - items: @@ -150,6 +151,18 @@ properties: - const: si-linux,cat874 - const: renesas,r8a774c0 + - description: RZ/G2H (R8A774E1) + items: + - enum: + - hoperun,hihope-rzg2h # HopeRun HiHope RZ/G2H platform + - const: renesas,r8a774e1 + + - items: + - enum: + - hoperun,hihope-rzg2-ex # HopeRun expansion board for HiHope RZ/G2 platforms + - const: hoperun,hihope-rzg2h + - const: renesas,r8a774e1 + - description: R-Car M1A (R8A77781) items: - enum: diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml index d4a4045092df..db2e35796795 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -435,6 +435,12 @@ properties: - const: radxa,rockpi4 - const: rockchip,rk3399 + - description: Radxa ROCK Pi N8 + items: + - const: radxa,rockpi-n8 + - const: vamrs,rk3288-vmarc-som + - const: rockchip,rk3288 + - description: Radxa ROCK Pi N10 items: - const: radxa,rockpi-n10 diff --git a/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml b/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml index cf5db5e273f3..6f1cd0103c74 100644 --- a/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml +++ b/Documentation/devicetree/bindings/arm/stm32/st,stm32-syscon.yaml @@ -16,6 +16,9 @@ properties: - items: - enum: - st,stm32mp157-syscfg + - st,stm32mp151-pwr-mcu + - st,stm32-syscfg + - st,stm32-power-config - const: syscon reg: @@ -27,7 +30,16 @@ properties: required: - compatible - reg - - clocks + +if: + properties: + compatible: + contains: + enum: + - st,stm32mp157-syscfg +then: + required: + - clocks additionalProperties: false diff --git a/Documentation/devicetree/bindings/arm/sunxi.yaml b/Documentation/devicetree/bindings/arm/sunxi.yaml index 87817ff0cd35..efc9118233b4 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi.yaml @@ -657,6 +657,11 @@ properties: - const: pine64,pinephone-1.1 - const: allwinner,sun50i-a64 + - description: Pine64 PinePhone (1.2) + items: + - const: pine64,pinephone-1.2 + - const: allwinner,sun50i-a64 + - description: Pine64 PineTab items: - const: pine64,pinetab diff --git a/Documentation/devicetree/bindings/arm/tegra.yaml b/Documentation/devicetree/bindings/arm/tegra.yaml index 60b38eb5c61a..e0b3debaee9e 100644 --- a/Documentation/devicetree/bindings/arm/tegra.yaml +++ b/Documentation/devicetree/bindings/arm/tegra.yaml @@ -35,6 +35,9 @@ properties: - const: toradex,colibri_t20 - const: nvidia,tegra20 - items: + - const: acer,picasso + - const: nvidia,tegra20 + - items: - enum: - nvidia,beaver - const: nvidia,tegra30 @@ -60,6 +63,13 @@ properties: - const: toradex,colibri_t30 - const: nvidia,tegra30 - items: + - const: asus,grouper + - const: nvidia,tegra30 + - items: + - const: asus,tilapia + - const: asus,grouper + - const: nvidia,tegra30 + - items: - enum: - nvidia,dalmore - nvidia,roth @@ -101,3 +111,11 @@ properties: - enum: - nvidia,p2972-0000 - const: nvidia,tegra194 + - description: Jetson Xavier NX + items: + - const: nvidia,p3668-0000 + - const: nvidia,tegra194 + - description: Jetson Xavier NX Developer Kit + items: + - const: nvidia,p3509-0000+p3668-0000 + - const: nvidia,tegra194 diff --git a/Documentation/devicetree/bindings/bus/mti,mips-cdmm.yaml b/Documentation/devicetree/bindings/bus/mti,mips-cdmm.yaml new file mode 100644 index 000000000000..9cc2d5f1beef --- /dev/null +++ b/Documentation/devicetree/bindings/bus/mti,mips-cdmm.yaml @@ -0,0 +1,35 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/bus/mti,mips-cdmm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MIPS Common Device Memory Map + +description: | + Defines a location of the MIPS Common Device Memory Map registers. + +maintainers: + - James Hogan <jhogan@kernel.org> + +properties: + compatible: + const: mti,mips-cdmm + + reg: + description: | + Base address and size of an unoccupied memory region, which will be + used to map the MIPS CDMM registers block. + maxItems: 1 + +required: + - compatible + - reg + +examples: + - | + cdmm@1bde8000 { + compatible = "mti,mips-cdmm"; + reg = <0x1bde8000 0x8000>; + }; +... diff --git a/Documentation/devicetree/bindings/bus/socionext,uniphier-system-bus.yaml b/Documentation/devicetree/bindings/bus/socionext,uniphier-system-bus.yaml index c4c9119e4a20..a0c6c5d2b70f 100644 --- a/Documentation/devicetree/bindings/bus/socionext,uniphier-system-bus.yaml +++ b/Documentation/devicetree/bindings/bus/socionext,uniphier-system-bus.yaml @@ -80,14 +80,14 @@ examples: ranges = <1 0x00000000 0x42000000 0x02000000>, <5 0x00000000 0x46000000 0x01000000>; - ethernet@1,01f00000 { + ethernet@1,1f00000 { compatible = "smsc,lan9115"; reg = <1 0x01f00000 0x1000>; interrupts = <0 48 4>; phy-mode = "mii"; }; - uart@5,00200000 { + serial@5,200000 { compatible = "ns16550a"; reg = <5 0x00200000 0x20>; interrupts = <0 49 4>; diff --git a/Documentation/devicetree/bindings/clock/brcm,bcm2711-dvp.yaml b/Documentation/devicetree/bindings/clock/brcm,bcm2711-dvp.yaml new file mode 100644 index 000000000000..08543ecbe35b --- /dev/null +++ b/Documentation/devicetree/bindings/clock/brcm,bcm2711-dvp.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/brcm,bcm2711-dvp.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom BCM2711 HDMI DVP Device Tree Bindings + +maintainers: + - Maxime Ripard <mripard@kernel.org> + +properties: + "#clock-cells": + const: 1 + + "#reset-cells": + const: 1 + + compatible: + const: brcm,brcm2711-dvp + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - "#clock-cells" + - "#reset-cells" + - compatible + - reg + - clocks + +additionalProperties: false + +examples: + - | + dvp: clock@7ef00000 { + compatible = "brcm,brcm2711-dvp"; + reg = <0x7ef00000 0x10>; + clocks = <&clk_108MHz>; + #clock-cells = <1>; + #reset-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/brcm,bcm63xx-clocks.txt b/Documentation/devicetree/bindings/clock/brcm,bcm63xx-clocks.txt index 3041657e2f96..3e7ca5530775 100644 --- a/Documentation/devicetree/bindings/clock/brcm,bcm63xx-clocks.txt +++ b/Documentation/devicetree/bindings/clock/brcm,bcm63xx-clocks.txt @@ -3,6 +3,8 @@ Gated Clock Controller Bindings for MIPS based BCM63XX SoCs Required properties: - compatible: must be one of: "brcm,bcm3368-clocks" + "brcm,bcm6318-clocks" + "brcm,bcm6318-ubus-clocks" "brcm,bcm6328-clocks" "brcm,bcm6358-clocks" "brcm,bcm6362-clocks" diff --git a/Documentation/devicetree/bindings/clock/clock-bindings.txt b/Documentation/devicetree/bindings/clock/clock-bindings.txt index 8a55fdcf96ee..f2ea53832ac6 100644 --- a/Documentation/devicetree/bindings/clock/clock-bindings.txt +++ b/Documentation/devicetree/bindings/clock/clock-bindings.txt @@ -9,7 +9,7 @@ specifier is an array of zero, one or more cells identifying the clock output on a device. The length of a clock specifier is defined by the value of a #clock-cells property in the clock provider node. -[1] http://patchwork.ozlabs.org/patch/31551/ +[1] https://patchwork.ozlabs.org/patch/31551/ ==Clock providers== diff --git a/Documentation/devicetree/bindings/clock/idt,versaclock5.txt b/Documentation/devicetree/bindings/clock/idt,versaclock5.txt index bcff681a4bd0..6165b6ddb1a9 100644 --- a/Documentation/devicetree/bindings/clock/idt,versaclock5.txt +++ b/Documentation/devicetree/bindings/clock/idt,versaclock5.txt @@ -31,6 +31,29 @@ Required properties: - 5p49v5933 and - 5p49v5935: (optional) property not present or "clkin". +For all output ports, a corresponding, optional child node named OUT1, +OUT2, etc. can represent a each output, and the node can be used to +specify the following: + +- itd,mode: can be one of the following: + - VC5_LVPECL + - VC5_CMOS + - VC5_HCSL33 + - VC5_LVDS + - VC5_CMOS2 + - VC5_CMOSD + - VC5_HCSL25 + +- idt,voltage-microvolts: can be one of the following + - 1800000 + - 2500000 + - 3300000 +- idt,slew-percent: Percent of normal, can be one of + - 80 + - 85 + - 90 + - 100 + ==Mapping between clock specifier and physical pins== When referencing the provided clock in the DT using phandle and @@ -81,6 +104,16 @@ i2c-master-node { /* Connect XIN input to 25MHz reference */ clocks = <&ref25m>; clock-names = "xin"; + + OUT1 { + itd,mode = <VC5_CMOS>; + idt,voltage-microvolts = <1800000>; + idt,slew-percent = <80>; + }; + OUT2 { + ... + }; + ... }; }; diff --git a/Documentation/devicetree/bindings/clock/imx27-clock.yaml b/Documentation/devicetree/bindings/clock/imx27-clock.yaml index b5f3ed084ea0..a75365453dbc 100644 --- a/Documentation/devicetree/bindings/clock/imx27-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx27-clock.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Clock bindings for Freescale i.MX27 maintainers: - - Fabio Estevam <fabio.estevam@freescale.com> + - Fabio Estevam <fabio.estevam@nxp.com> description: | The clock consumer should specify the desired clock by having the clock diff --git a/Documentation/devicetree/bindings/clock/imx31-clock.yaml b/Documentation/devicetree/bindings/clock/imx31-clock.yaml index 1b6f75d3928a..a25a374b3b2a 100644 --- a/Documentation/devicetree/bindings/clock/imx31-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx31-clock.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Clock bindings for Freescale i.MX31 maintainers: - - Fabio Estevam <fabio.estevam@freescale.com> + - Fabio Estevam <fabio.estevam@nxp.com> description: | The clock consumer should specify the desired clock by having the clock diff --git a/Documentation/devicetree/bindings/clock/imx35-clock.yaml b/Documentation/devicetree/bindings/clock/imx35-clock.yaml index bd871da6fc7c..3e20ccaf8131 100644 --- a/Documentation/devicetree/bindings/clock/imx35-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx35-clock.yaml @@ -130,7 +130,7 @@ examples: #clock-cells = <1>; }; - esdhc@53fb4000 { + mmc@53fb4000 { compatible = "fsl,imx35-esdhc"; reg = <0x53fb4000 0x4000>; interrupts = <7>; diff --git a/Documentation/devicetree/bindings/clock/imx5-clock.yaml b/Documentation/devicetree/bindings/clock/imx5-clock.yaml index f5c2b3d7a910..4d9e7c73dce9 100644 --- a/Documentation/devicetree/bindings/clock/imx5-clock.yaml +++ b/Documentation/devicetree/bindings/clock/imx5-clock.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Clock bindings for Freescale i.MX5 maintainers: - - Fabio Estevam <fabio.estevam@freescale.com> + - Fabio Estevam <fabio.estevam@nxp.com> description: | The clock consumer should specify the desired clock by having the clock diff --git a/Documentation/devicetree/bindings/clock/imx7ulp-clock.txt b/Documentation/devicetree/bindings/clock/imx7ulp-clock.txt deleted file mode 100644 index 93d89adb7afe..000000000000 --- a/Documentation/devicetree/bindings/clock/imx7ulp-clock.txt +++ /dev/null @@ -1,103 +0,0 @@ -* Clock bindings for Freescale i.MX7ULP - -i.MX7ULP Clock functions are under joint control of the System -Clock Generation (SCG) modules, Peripheral Clock Control (PCC) -modules, and Core Mode Controller (CMC)1 blocks - -The clocking scheme provides clear separation between M4 domain -and A7 domain. Except for a few clock sources shared between two -domains, such as the System Oscillator clock, the Slow IRC (SIRC), -and and the Fast IRC clock (FIRCLK), clock sources and clock -management are separated and contained within each domain. - -M4 clock management consists of SCG0, PCC0, PCC1, and CMC0 modules. -A7 clock management consists of SCG1, PCC2, PCC3, and CMC1 modules. - -Note: this binding doc is only for A7 clock domain. - -System Clock Generation (SCG) modules: ---------------------------------------------------------------------- -The System Clock Generation (SCG) is responsible for clock generation -and distribution across this device. Functions performed by the SCG -include: clock reference selection, generation of clock used to derive -processor, system, peripheral bus and external memory interface clocks, -source selection for peripheral clocks and control of power saving -clock gating mode. - -Required properties: - -- compatible: Should be "fsl,imx7ulp-scg1". -- reg : Should contain registers location and length. -- #clock-cells: Should be <1>. -- clocks: Should contain the fixed input clocks. -- clock-names: Should contain the following clock names: - "rosc", "sosc", "sirc", "firc", "upll", "mpll". - -Peripheral Clock Control (PCC) modules: ---------------------------------------------------------------------- -The Peripheral Clock Control (PCC) is responsible for clock selection, -optional division and clock gating mode for peripherals in their -respected power domain - -Required properties: -- compatible: Should be one of: - "fsl,imx7ulp-pcc2", - "fsl,imx7ulp-pcc3". -- reg : Should contain registers location and length. -- #clock-cells: Should be <1>. -- clocks: Should contain the fixed input clocks. -- clock-names: Should contain the following clock names: - "nic1_bus_clk", "nic1_clk", "ddr_clk", "apll_pfd2", - "apll_pfd1", "apll_pfd0", "upll", "sosc_bus_clk", - "mpll", "firc_bus_clk", "rosc", "spll_bus_clk"; - -The clock consumer should specify the desired clock by having the clock -ID in its "clocks" phandle cell. -See include/dt-bindings/clock/imx7ulp-clock.h -for the full list of i.MX7ULP clock IDs of each module. - -Examples: - -#include <dt-bindings/clock/imx7ulp-clock.h> - -scg1: scg1@403e0000 { - compatible = "fsl,imx7ulp-scg1; - reg = <0x403e0000 0x10000>; - clocks = <&rosc>, <&sosc>, <&sirc>, - <&firc>, <&upll>, <&mpll>; - clock-names = "rosc", "sosc", "sirc", - "firc", "upll", "mpll"; - #clock-cells = <1>; -}; - -pcc2: pcc2@403f0000 { - compatible = "fsl,imx7ulp-pcc2"; - reg = <0x403f0000 0x10000>; - #clock-cells = <1>; - clocks = <&scg1 IMX7ULP_CLK_NIC1_BUS_DIV>, - <&scg1 IMX7ULP_CLK_NIC1_DIV>, - <&scg1 IMX7ULP_CLK_DDR_DIV>, - <&scg1 IMX7ULP_CLK_APLL_PFD2>, - <&scg1 IMX7ULP_CLK_APLL_PFD1>, - <&scg1 IMX7ULP_CLK_APLL_PFD0>, - <&scg1 IMX7ULP_CLK_UPLL>, - <&scg1 IMX7ULP_CLK_SOSC_BUS_CLK>, - <&scg1 IMX7ULP_CLK_FIRC_BUS_CLK>, - <&scg1 IMX7ULP_CLK_ROSC>, - <&scg1 IMX7ULP_CLK_SPLL_BUS_CLK>; - clock-names = "nic1_bus_clk", "nic1_clk", "ddr_clk", - "apll_pfd2", "apll_pfd1", "apll_pfd0", - "upll", "sosc_bus_clk", "mpll", - "firc_bus_clk", "rosc", "spll_bus_clk"; -}; - -usdhc1: usdhc@40380000 { - compatible = "fsl,imx7ulp-usdhc"; - reg = <0x40380000 0x10000>; - interrupts = <GIC_SPI 43 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&scg1 IMX7ULP_CLK_NIC1_BUS_DIV>, - <&scg1 IMX7ULP_CLK_NIC1_DIV>, - <&pcc2 IMX7ULP_CLK_USDHC1>; - clock-names ="ipg", "ahb", "per"; - bus-width = <4>; -}; diff --git a/Documentation/devicetree/bindings/clock/imx7ulp-pcc-clock.yaml b/Documentation/devicetree/bindings/clock/imx7ulp-pcc-clock.yaml new file mode 100644 index 000000000000..7caf5cee9199 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/imx7ulp-pcc-clock.yaml @@ -0,0 +1,121 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/imx7ulp-pcc-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Clock bindings for Freescale i.MX7ULP Peripheral Clock Control (PCC) modules + +maintainers: + - A.s. Dong <aisheng.dong@nxp.com> + +description: | + i.MX7ULP Clock functions are under joint control of the System + Clock Generation (SCG) modules, Peripheral Clock Control (PCC) + modules, and Core Mode Controller (CMC)1 blocks + + The clocking scheme provides clear separation between M4 domain + and A7 domain. Except for a few clock sources shared between two + domains, such as the System Oscillator clock, the Slow IRC (SIRC), + and and the Fast IRC clock (FIRCLK), clock sources and clock + management are separated and contained within each domain. + + M4 clock management consists of SCG0, PCC0, PCC1, and CMC0 modules. + A7 clock management consists of SCG1, PCC2, PCC3, and CMC1 modules. + + Note: this binding doc is only for A7 clock domain. + + The Peripheral Clock Control (PCC) is responsible for clock selection, + optional division and clock gating mode for peripherals in their + respected power domain. + + The clock consumer should specify the desired clock by having the clock + ID in its "clocks" phandle cell. + See include/dt-bindings/clock/imx7ulp-clock.h for the full list of + i.MX7ULP clock IDs of each module. + +properties: + compatible: + enum: + - fsl,imx7ulp-pcc2 + - fsl,imx7ulp-pcc3 + + reg: + maxItems: 1 + + '#clock-cells': + const: 1 + + clocks: + items: + - description: nic1 bus clock + - description: nic1 clock + - description: ddr clock + - description: apll pfd2 + - description: apll pfd1 + - description: apll pfd0 + - description: usb pll + - description: system osc bus clock + - description: fast internal reference clock bus + - description: rtc osc + - description: system pll bus clock + + clock-names: + items: + - const: nic1_bus_clk + - const: nic1_clk + - const: ddr_clk + - const: apll_pfd2 + - const: apll_pfd1 + - const: apll_pfd0 + - const: upll + - const: sosc_bus_clk + - const: firc_bus_clk + - const: rosc + - const: spll_bus_clk + +required: + - compatible + - reg + - '#clock-cells' + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imx7ulp-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + clock-controller@403f0000 { + compatible = "fsl,imx7ulp-pcc2"; + reg = <0x403f0000 0x10000>; + #clock-cells = <1>; + clocks = <&scg1 IMX7ULP_CLK_NIC1_BUS_DIV>, + <&scg1 IMX7ULP_CLK_NIC1_DIV>, + <&scg1 IMX7ULP_CLK_DDR_DIV>, + <&scg1 IMX7ULP_CLK_APLL_PFD2>, + <&scg1 IMX7ULP_CLK_APLL_PFD1>, + <&scg1 IMX7ULP_CLK_APLL_PFD0>, + <&scg1 IMX7ULP_CLK_UPLL>, + <&scg1 IMX7ULP_CLK_SOSC_BUS_CLK>, + <&scg1 IMX7ULP_CLK_FIRC_BUS_CLK>, + <&scg1 IMX7ULP_CLK_ROSC>, + <&scg1 IMX7ULP_CLK_SPLL_BUS_CLK>; + clock-names = "nic1_bus_clk", "nic1_clk", "ddr_clk", + "apll_pfd2", "apll_pfd1", "apll_pfd0", + "upll", "sosc_bus_clk", "firc_bus_clk", + "rosc", "spll_bus_clk"; + }; + + mmc@40380000 { + compatible = "fsl,imx7ulp-usdhc"; + reg = <0x40380000 0x10000>; + interrupts = <GIC_SPI 43 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&scg1 IMX7ULP_CLK_NIC1_BUS_DIV>, + <&scg1 IMX7ULP_CLK_NIC1_DIV>, + <&pcc2 IMX7ULP_CLK_USDHC1>; + clock-names ="ipg", "ahb", "per"; + bus-width = <4>; + }; diff --git a/Documentation/devicetree/bindings/clock/imx7ulp-scg-clock.yaml b/Documentation/devicetree/bindings/clock/imx7ulp-scg-clock.yaml new file mode 100644 index 000000000000..ee8efb4ed599 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/imx7ulp-scg-clock.yaml @@ -0,0 +1,99 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/imx7ulp-scg-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Clock bindings for Freescale i.MX7ULP System Clock Generation (SCG) modules + +maintainers: + - A.s. Dong <aisheng.dong@nxp.com> + +description: | + i.MX7ULP Clock functions are under joint control of the System + Clock Generation (SCG) modules, Peripheral Clock Control (PCC) + modules, and Core Mode Controller (CMC)1 blocks + + The clocking scheme provides clear separation between M4 domain + and A7 domain. Except for a few clock sources shared between two + domains, such as the System Oscillator clock, the Slow IRC (SIRC), + and and the Fast IRC clock (FIRCLK), clock sources and clock + management are separated and contained within each domain. + + M4 clock management consists of SCG0, PCC0, PCC1, and CMC0 modules. + A7 clock management consists of SCG1, PCC2, PCC3, and CMC1 modules. + + Note: this binding doc is only for A7 clock domain. + + The System Clock Generation (SCG) is responsible for clock generation + and distribution across this device. Functions performed by the SCG + include: clock reference selection, generation of clock used to derive + processor, system, peripheral bus and external memory interface clocks, + source selection for peripheral clocks and control of power saving + clock gating mode. + + The clock consumer should specify the desired clock by having the clock + ID in its "clocks" phandle cell. + See include/dt-bindings/clock/imx7ulp-clock.h for the full list of + i.MX7ULP clock IDs of each module. + +properties: + compatible: + const: fsl,imx7ulp-scg1 + + reg: + maxItems: 1 + + '#clock-cells': + const: 1 + + clocks: + items: + - description: rtc osc + - description: system osc + - description: slow internal reference clock + - description: fast internal reference clock + - description: usb PLL + + clock-names: + items: + - const: rosc + - const: sosc + - const: sirc + - const: firc + - const: upll + +required: + - compatible + - reg + - '#clock-cells' + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imx7ulp-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + clock-controller@403e0000 { + compatible = "fsl,imx7ulp-scg1"; + reg = <0x403e0000 0x10000>; + clocks = <&rosc>, <&sosc>, <&sirc>, + <&firc>, <&upll>; + clock-names = "rosc", "sosc", "sirc", + "firc", "upll"; + #clock-cells = <1>; + }; + + mmc@40380000 { + compatible = "fsl,imx7ulp-usdhc"; + reg = <0x40380000 0x10000>; + interrupts = <GIC_SPI 43 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&scg1 IMX7ULP_CLK_NIC1_BUS_DIV>, + <&scg1 IMX7ULP_CLK_NIC1_DIV>, + <&pcc2 IMX7ULP_CLK_USDHC1>; + clock-names ="ipg", "ahb", "per"; + bus-width = <4>; + }; diff --git a/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml b/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml index 33f3010f48c3..1d5e9bcce4c8 100644 --- a/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml +++ b/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml @@ -62,7 +62,7 @@ examples: }; mmc@5b010000 { - compatible = "fsl,imx8qxp-usdhc", "fsl,imx7d-usdhc"; + compatible = "fsl,imx8qxp-usdhc"; interrupts = <GIC_SPI 232 IRQ_TYPE_LEVEL_HIGH>; reg = <0x5b010000 0x10000>; clocks = <&conn_lpcg IMX_CONN_LPCG_SDHC0_IPG_CLK>, diff --git a/Documentation/devicetree/bindings/clock/microchip,sparx5-dpll.yaml b/Documentation/devicetree/bindings/clock/microchip,sparx5-dpll.yaml new file mode 100644 index 000000000000..39559a0a598a --- /dev/null +++ b/Documentation/devicetree/bindings/clock/microchip,sparx5-dpll.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/microchip,sparx5-dpll.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip Sparx5 DPLL Clock + +maintainers: + - Lars Povlsen <lars.povlsen@microchip.com> + +description: | + The Sparx5 DPLL clock controller generates and supplies clock to + various peripherals within the SoC. + +properties: + compatible: + const: microchip,sparx5-dpll + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + '#clock-cells': + const: 1 + +required: + - compatible + - reg + - clocks + - '#clock-cells' + +additionalProperties: false + +examples: + # Clock provider for eMMC: + - | + lcpll_clk: lcpll-clk { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <2500000000>; + }; + clks: clock-controller@61110000c { + compatible = "microchip,sparx5-dpll"; + #clock-cells = <1>; + clocks = <&lcpll_clk>; + reg = <0x1110000c 0x24>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml b/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml index 20d2638b4cd2..db3d0ea6bc7a 100644 --- a/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,a53pll.yaml @@ -15,7 +15,9 @@ description: properties: compatible: - const: qcom,msm8916-a53pll + enum: + - qcom,ipq6018-a53pll + - qcom,msm8916-a53pll reg: maxItems: 1 @@ -23,6 +25,14 @@ properties: '#clock-cells': const: 0 + clocks: + items: + - description: board XO clock + + clock-names: + items: + - const: xo + required: - compatible - reg @@ -38,3 +48,12 @@ examples: reg = <0xb016000 0x40>; #clock-cells = <0>; }; + #Example 2 - A53 PLL found on IPQ6018 devices + - | + a53pll_ipq: clock-controller@b116000 { + compatible = "qcom,ipq6018-a53pll"; + reg = <0x0b116000 0x40>; + #clock-cells = <0>; + clocks = <&xo>; + clock-names = "xo"; + }; diff --git a/Documentation/devicetree/bindings/clock/qcom,msm8996-apcc.yaml b/Documentation/devicetree/bindings/clock/qcom,msm8996-apcc.yaml new file mode 100644 index 000000000000..d673edeed98d --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,msm8996-apcc.yaml @@ -0,0 +1,56 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,kryocc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm clock controller for MSM8996 CPUs + +maintainers: + - Loic Poulain <loic.poulain@linaro.org> + +description: | + Qualcomm CPU clock controller for MSM8996 CPUs, clock 0 is for Power cluster + and clock 1 is for Perf cluster. + +properties: + compatible: + enum: + - qcom,msm8996-apcc + + reg: + maxItems: 1 + + '#clock-cells': + const: 1 + + clocks: + items: + - description: Primary PLL clock for power cluster (little) + - description: Primary PLL clock for perf cluster (big) + - description: Alternate PLL clock for power cluster (little) + - description: Alternate PLL clock for perf cluster (big) + + clock-names: + items: + - const: pwrcl_pll + - const: perfcl_pll + - const: pwrcl_alt_pll + - const: perfcl_alt_pll + +required: + - compatible + - reg + - '#clock-cells' + +additionalProperties: false + +examples: + # Example for msm8996 + - | + kryocc: clock-controller@6400000 { + compatible = "qcom,msm8996-apcc"; + reg = <0x6400000 0x90000>; + #clock-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt b/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt index 90a1349bc713..b44a0622fb3a 100644 --- a/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt +++ b/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt @@ -13,13 +13,17 @@ Required properties : "qcom,rpmcc-msm8660", "qcom,rpmcc" "qcom,rpmcc-apq8060", "qcom,rpmcc" "qcom,rpmcc-msm8916", "qcom,rpmcc" + "qcom,rpmcc-msm8936", "qcom,rpmcc" "qcom,rpmcc-msm8974", "qcom,rpmcc" "qcom,rpmcc-msm8976", "qcom,rpmcc" "qcom,rpmcc-apq8064", "qcom,rpmcc" "qcom,rpmcc-ipq806x", "qcom,rpmcc" + "qcom,rpmcc-msm8992",·"qcom,rpmcc" + "qcom,rpmcc-msm8994",·"qcom,rpmcc" "qcom,rpmcc-msm8996", "qcom,rpmcc" "qcom,rpmcc-msm8998", "qcom,rpmcc" "qcom,rpmcc-qcs404", "qcom,rpmcc" + "qcom,rpmcc-sdm660", "qcom,rpmcc" - #clock-cells : shall contain 1 diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-clocks.yaml b/Documentation/devicetree/bindings/clock/renesas,cpg-clocks.yaml new file mode 100644 index 000000000000..b83f4138f2f8 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-clocks.yaml @@ -0,0 +1,241 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/renesas,cpg-clocks.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas Clock Pulse Generator (CPG) + +maintainers: + - Geert Uytterhoeven <geert+renesas@glider.be> + +description: + The Clock Pulse Generator (CPG) generates core clocks for the SoC. It + includes PLLs, and fixed and variable ratio dividers. + + The CPG may also provide a Clock Domain for SoC devices, in combination with + the CPG Module Stop (MSTP) Clocks. + +properties: + compatible: + oneOf: + - const: renesas,r8a73a4-cpg-clocks # R-Mobile APE6 + - const: renesas,r8a7740-cpg-clocks # R-Mobile A1 + - const: renesas,r8a7778-cpg-clocks # R-Car M1 + - const: renesas,r8a7779-cpg-clocks # R-Car H1 + - items: + - enum: + - renesas,r7s72100-cpg-clocks # RZ/A1H + - const: renesas,rz-cpg-clocks # RZ/A1 + - const: renesas,sh73a0-cpg-clocks # SH-Mobile AG5 + + reg: + maxItems: 1 + + clocks: true + + '#clock-cells': + const: 1 + + clock-output-names: true + + renesas,mode: + description: Board-specific settings of the MD_CK* bits on R-Mobile A1 + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 7 + + '#power-domain-cells': + const: 0 + +required: + - compatible + - reg + - clocks + - '#clock-cells' + - clock-output-names + +allOf: + - if: + properties: + compatible: + contains: + const: renesas,r8a73a4-cpg-clocks + then: + properties: + clocks: + items: + - description: extal1 + - description: extal2 + + clock-output-names: + items: + - const: main + - const: pll0 + - const: pll1 + - const: pll2 + - const: pll2s + - const: pll2h + - const: z + - const: z2 + - const: i + - const: m3 + - const: b + - const: m1 + - const: m2 + - const: zx + - const: zs + - const: hp + + - if: + properties: + compatible: + contains: + const: renesas,r8a7740-cpg-clocks + then: + properties: + clocks: + items: + - description: extal1 + - description: extal2 + - description: extalr + + clock-output-names: + items: + - const: system + - const: pllc0 + - const: pllc1 + - const: pllc2 + - const: r + - const: usb24s + - const: i + - const: zg + - const: b + - const: m1 + - const: hp + - const: hpp + - const: usbp + - const: s + - const: zb + - const: m3 + - const: cp + + required: + - renesas,mode + + - if: + properties: + compatible: + contains: + const: renesas,r8a7778-cpg-clocks + then: + properties: + clocks: + maxItems: 1 + + clock-output-names: + items: + - const: plla + - const: pllb + - const: b + - const: out + - const: p + - const: s + - const: s1 + + - if: + properties: + compatible: + contains: + const: renesas,r8a7779-cpg-clocks + then: + properties: + clocks: + maxItems: 1 + + clock-output-names: + items: + - const: plla + - const: z + - const: zs + - const: s + - const: s1 + - const: p + - const: b + - const: out + + - if: + properties: + compatible: + contains: + const: renesas,r7s72100-cpg-clocks + then: + properties: + clocks: + items: + - description: extal1 + - description: usb_x1 + + clock-output-names: + items: + - const: pll + - const: i + - const: g + + - if: + properties: + compatible: + contains: + const: renesas,sh73a0-cpg-clocks + then: + properties: + clocks: + items: + - description: extal1 + - description: extal2 + + clock-output-names: + items: + - const: main + - const: pll0 + - const: pll1 + - const: pll2 + - const: pll3 + - const: dsi0phy + - const: dsi1phy + - const: zg + - const: m3 + - const: b + - const: m1 + - const: m2 + - const: z + - const: zx + - const: hp + + - if: + properties: + compatible: + contains: + enum: + - renesas,r8a7778-cpg-clocks + - renesas,r8a7779-cpg-clocks + - renesas,rz-cpg-clocks + then: + required: + - '#power-domain-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a7740-clock.h> + cpg_clocks: cpg_clocks@e6150000 { + compatible = "renesas,r8a7740-cpg-clocks"; + reg = <0xe6150000 0x10000>; + clocks = <&extal1_clk>, <&extal2_clk>, <&extalr_clk>; + #clock-cells = <1>; + clock-output-names = "system", "pllc0", "pllc1", "pllc2", "r", + "usb24s", "i", "zg", "b", "m1", "hp", "hpp", + "usbp", "s", "zb", "m3", "cp"; + renesas,mode = <0x05>; + }; diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml index c745bd60719a..e13aee8ab61a 100644 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml @@ -33,6 +33,7 @@ properties: - renesas,r8a774a1-cpg-mssr # RZ/G2M - renesas,r8a774b1-cpg-mssr # RZ/G2N - renesas,r8a774c0-cpg-mssr # RZ/G2E + - renesas,r8a774e1-cpg-mssr # RZ/G2H - renesas,r8a7790-cpg-mssr # R-Car H2 - renesas,r8a7791-cpg-mssr # R-Car M2-W - renesas,r8a7792-cpg-mssr # R-Car V2H diff --git a/Documentation/devicetree/bindings/clock/renesas,r8a73a4-cpg-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,r8a73a4-cpg-clocks.txt deleted file mode 100644 index ece92393e80d..000000000000 --- a/Documentation/devicetree/bindings/clock/renesas,r8a73a4-cpg-clocks.txt +++ /dev/null @@ -1,33 +0,0 @@ -* Renesas R8A73A4 Clock Pulse Generator (CPG) - -The CPG generates core clocks for the R8A73A4 SoC. It includes five PLLs -and several fixed ratio dividers. - -Required Properties: - - - compatible: Must be "renesas,r8a73a4-cpg-clocks" - - - reg: Base address and length of the memory resource used by the CPG - - - clocks: Reference to the parent clocks ("extal1" and "extal2") - - - #clock-cells: Must be 1 - - - clock-output-names: The names of the clocks. Supported clocks are "main", - "pll0", "pll1", "pll2", "pll2s", "pll2h", "z", "z2", "i", "m3", "b", - "m1", "m2", "zx", "zs", and "hp". - - -Example -------- - - cpg_clocks: cpg_clocks@e6150000 { - compatible = "renesas,r8a73a4-cpg-clocks"; - reg = <0 0xe6150000 0 0x10000>; - clocks = <&extal1_clk>, <&extal2_clk>; - #clock-cells = <1>; - clock-output-names = "main", "pll0", "pll1", "pll2", - "pll2s", "pll2h", "z", "z2", - "i", "m3", "b", "m1", "m2", - "zx", "zs", "hp"; - }; diff --git a/Documentation/devicetree/bindings/clock/renesas,r8a7740-cpg-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,r8a7740-cpg-clocks.txt deleted file mode 100644 index 2c03302f86ed..000000000000 --- a/Documentation/devicetree/bindings/clock/renesas,r8a7740-cpg-clocks.txt +++ /dev/null @@ -1,41 +0,0 @@ -These bindings should be considered EXPERIMENTAL for now. - -* Renesas R8A7740 Clock Pulse Generator (CPG) - -The CPG generates core clocks for the R8A7740 SoC. It includes three PLLs -and several fixed ratio and variable ratio dividers. - -Required Properties: - - - compatible: Must be "renesas,r8a7740-cpg-clocks" - - - reg: Base address and length of the memory resource used by the CPG - - - clocks: Reference to the three parent clocks - - #clock-cells: Must be 1 - - clock-output-names: The names of the clocks. Supported clocks are - "system", "pllc0", "pllc1", "pllc2", "r", "usb24s", "i", "zg", "b", - "m1", "hp", "hpp", "usbp", "s", "zb", "m3", and "cp". - - - renesas,mode: board-specific settings of the MD_CK* bits - - -Example -------- - -cpg_clocks: cpg_clocks@e6150000 { - compatible = "renesas,r8a7740-cpg-clocks"; - reg = <0xe6150000 0x10000>; - clocks = <&extal1_clk>, <&extal2_clk>, <&extalr_clk>; - #clock-cells = <1>; - clock-output-names = "system", "pllc0", "pllc1", - "pllc2", "r", - "usb24s", - "i", "zg", "b", "m1", "hp", - "hpp", "usbp", "s", "zb", "m3", - "cp"; -}; - -&cpg_clocks { - renesas,mode = <0x05>; -}; diff --git a/Documentation/devicetree/bindings/clock/renesas,r8a7778-cpg-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,r8a7778-cpg-clocks.txt deleted file mode 100644 index 7cc4c0330b53..000000000000 --- a/Documentation/devicetree/bindings/clock/renesas,r8a7778-cpg-clocks.txt +++ /dev/null @@ -1,47 +0,0 @@ -* Renesas R8A7778 Clock Pulse Generator (CPG) - -The CPG generates core clocks for the R8A7778. It includes two PLLs and -several fixed ratio dividers. -The CPG also provides a Clock Domain for SoC devices, in combination with the -CPG Module Stop (MSTP) Clocks. - -Required Properties: - - - compatible: Must be "renesas,r8a7778-cpg-clocks" - - reg: Base address and length of the memory resource used by the CPG - - #clock-cells: Must be 1 - - clock-output-names: The names of the clocks. Supported clocks are - "plla", "pllb", "b", "out", "p", "s", and "s1". - - #power-domain-cells: Must be 0 - -SoC devices that are part of the CPG/MSTP Clock Domain and can be power-managed -through an MSTP clock should refer to the CPG device node in their -"power-domains" property, as documented by the generic PM domain bindings in -Documentation/devicetree/bindings/power/power_domain.txt. - - -Examples --------- - - - CPG device node: - - cpg_clocks: cpg_clocks@ffc80000 { - compatible = "renesas,r8a7778-cpg-clocks"; - reg = <0xffc80000 0x80>; - #clock-cells = <1>; - clocks = <&extal_clk>; - clock-output-names = "plla", "pllb", "b", - "out", "p", "s", "s1"; - #power-domain-cells = <0>; - }; - - - - CPG/MSTP Clock Domain member device node: - - sdhi0: sd@ffe4c000 { - compatible = "renesas,sdhi-r8a7778"; - reg = <0xffe4c000 0x100>; - interrupts = <0 87 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&mstp3_clks R8A7778_CLK_SDHI0>; - power-domains = <&cpg_clocks>; - }; diff --git a/Documentation/devicetree/bindings/clock/renesas,r8a7779-cpg-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,r8a7779-cpg-clocks.txt deleted file mode 100644 index 8c81547c29f5..000000000000 --- a/Documentation/devicetree/bindings/clock/renesas,r8a7779-cpg-clocks.txt +++ /dev/null @@ -1,49 +0,0 @@ -* Renesas R8A7779 Clock Pulse Generator (CPG) - -The CPG generates core clocks for the R8A7779. It includes one PLL and -several fixed ratio dividers. -The CPG also provides a Clock Domain for SoC devices, in combination with the -CPG Module Stop (MSTP) Clocks. - -Required Properties: - - - compatible: Must be "renesas,r8a7779-cpg-clocks" - - reg: Base address and length of the memory resource used by the CPG - - - clocks: Reference to the parent clock - - #clock-cells: Must be 1 - - clock-output-names: The names of the clocks. Supported clocks are "plla", - "z", "zs", "s", "s1", "p", "b", "out". - - #power-domain-cells: Must be 0 - -SoC devices that are part of the CPG/MSTP Clock Domain and can be power-managed -through an MSTP clock should refer to the CPG device node in their -"power-domains" property, as documented by the generic PM domain bindings in -Documentation/devicetree/bindings/power/power_domain.txt. - - -Examples --------- - - - CPG device node: - - cpg_clocks: cpg_clocks@ffc80000 { - compatible = "renesas,r8a7779-cpg-clocks"; - reg = <0xffc80000 0x30>; - clocks = <&extal_clk>; - #clock-cells = <1>; - clock-output-names = "plla", "z", "zs", "s", "s1", "p", - "b", "out"; - #power-domain-cells = <0>; - }; - - - - CPG/MSTP Clock Domain member device node: - - sata: sata@fc600000 { - compatible = "renesas,sata-r8a7779", "renesas,rcar-sata"; - reg = <0xfc600000 0x2000>; - interrupts = <0 100 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&mstp1_clks R8A7779_CLK_SATA>; - power-domains = <&cpg_clocks>; - }; diff --git a/Documentation/devicetree/bindings/clock/renesas,rz-cpg-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,rz-cpg-clocks.txt deleted file mode 100644 index 8ff3e2774ed8..000000000000 --- a/Documentation/devicetree/bindings/clock/renesas,rz-cpg-clocks.txt +++ /dev/null @@ -1,53 +0,0 @@ -* Renesas RZ/A1 Clock Pulse Generator (CPG) - -The CPG generates core clocks for the RZ/A1 SoCs. It includes the PLL, variable -CPU and GPU clocks, and several fixed ratio dividers. -The CPG also provides a Clock Domain for SoC devices, in combination with the -CPG Module Stop (MSTP) Clocks. - -Required Properties: - - - compatible: Must be one of - - "renesas,r7s72100-cpg-clocks" for the r7s72100 CPG - and "renesas,rz-cpg-clocks" as a fallback. - - reg: Base address and length of the memory resource used by the CPG - - clocks: References to possible parent clocks. Order must match clock modes - in the datasheet. For the r7s72100, this is extal, usb_x1. - - #clock-cells: Must be 1 - - clock-output-names: The names of the clocks. Supported clocks are "pll", - "i", and "g" - - #power-domain-cells: Must be 0 - -SoC devices that are part of the CPG/MSTP Clock Domain and can be power-managed -through an MSTP clock should refer to the CPG device node in their -"power-domains" property, as documented by the generic PM domain bindings in -Documentation/devicetree/bindings/power/power_domain.txt. - - -Examples --------- - - - CPG device node: - - cpg_clocks: cpg_clocks@fcfe0000 { - #clock-cells = <1>; - compatible = "renesas,r7s72100-cpg-clocks", - "renesas,rz-cpg-clocks"; - reg = <0xfcfe0000 0x18>; - clocks = <&extal_clk>, <&usb_x1_clk>; - clock-output-names = "pll", "i", "g"; - #power-domain-cells = <0>; - }; - - - - CPG/MSTP Clock Domain member device node: - - mtu2: timer@fcff0000 { - compatible = "renesas,mtu2-r7s72100", "renesas,mtu2"; - reg = <0xfcff0000 0x400>; - interrupts = <0 107 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "tgi0a"; - clocks = <&mstp3_clks R7S72100_CLK_MTU2>; - clock-names = "fck"; - power-domains = <&cpg_clocks>; - }; diff --git a/Documentation/devicetree/bindings/clock/renesas,sh73a0-cpg-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,sh73a0-cpg-clocks.txt deleted file mode 100644 index a8978ec94831..000000000000 --- a/Documentation/devicetree/bindings/clock/renesas,sh73a0-cpg-clocks.txt +++ /dev/null @@ -1,35 +0,0 @@ -These bindings should be considered EXPERIMENTAL for now. - -* Renesas SH73A0 Clock Pulse Generator (CPG) - -The CPG generates core clocks for the SH73A0 SoC. It includes four PLLs -and several fixed ratio dividers. - -Required Properties: - - - compatible: Must be "renesas,sh73a0-cpg-clocks" - - - reg: Base address and length of the memory resource used by the CPG - - - clocks: Reference to the parent clocks ("extal1" and "extal2") - - - #clock-cells: Must be 1 - - - clock-output-names: The names of the clocks. Supported clocks are "main", - "pll0", "pll1", "pll2", "pll3", "dsi0phy", "dsi1phy", "zg", "m3", "b", - "m1", "m2", "z", "zx", and "hp". - - -Example -------- - - cpg_clocks: cpg_clocks@e6150000 { - compatible = "renesas,sh73a0-cpg-clocks"; - reg = <0 0xe6150000 0 0x10000>; - clocks = <&extal1_clk>, <&extal2_clk>; - #clock-cells = <1>; - clock-output-names = "main", "pll0", "pll1", "pll2", - "pll3", "dsi0phy", "dsi1phy", - "zg", "m3", "b", "m1", "m2", - "z", "zx", "hp"; - }; diff --git a/Documentation/devicetree/bindings/clock/silabs,si514.txt b/Documentation/devicetree/bindings/clock/silabs,si514.txt index ea1a9dbc63b6..a4f28ec86f35 100644 --- a/Documentation/devicetree/bindings/clock/silabs,si514.txt +++ b/Documentation/devicetree/bindings/clock/silabs,si514.txt @@ -6,7 +6,7 @@ found in the datasheet[2]. [1] Documentation/devicetree/bindings/clock/clock-bindings.txt [2] Si514 datasheet - http://www.silabs.com/Support%20Documents/TechnicalDocs/si514.pdf + https://www.silabs.com/Support%20Documents/TechnicalDocs/si514.pdf Required properties: - compatible: Shall be "silabs,si514" diff --git a/Documentation/devicetree/bindings/clock/silabs,si5351.txt b/Documentation/devicetree/bindings/clock/silabs,si5351.txt index f00191cad8cd..8fe6f80afade 100644 --- a/Documentation/devicetree/bindings/clock/silabs,si5351.txt +++ b/Documentation/devicetree/bindings/clock/silabs,si5351.txt @@ -2,7 +2,7 @@ Binding for Silicon Labs Si5351a/b/c programmable i2c clock generator. Reference [1] Si5351A/B/C Data Sheet - http://www.silabs.com/Support%20Documents/TechnicalDocs/Si5351.pdf + https://www.silabs.com/Support%20Documents/TechnicalDocs/Si5351.pdf The Si5351a/b/c are programmable i2c clock generators with up to 8 output clocks. Si5351a also has a reduced pin-count package (MSOP10) where only diff --git a/Documentation/devicetree/bindings/clock/silabs,si570.txt b/Documentation/devicetree/bindings/clock/silabs,si570.txt index c09f21e1d98f..901935e929d2 100644 --- a/Documentation/devicetree/bindings/clock/silabs,si570.txt +++ b/Documentation/devicetree/bindings/clock/silabs,si570.txt @@ -7,9 +7,9 @@ found in the data sheets[2][3]. [1] Documentation/devicetree/bindings/clock/clock-bindings.txt [2] Si570/571 Data Sheet - http://www.silabs.com/Support%20Documents/TechnicalDocs/si570.pdf + https://www.silabs.com/Support%20Documents/TechnicalDocs/si570.pdf [3] Si598/599 Data Sheet - http://www.silabs.com/Support%20Documents/TechnicalDocs/si598-99.pdf + https://www.silabs.com/Support%20Documents/TechnicalDocs/si598-99.pdf Required properties: - compatible: Shall be one of "silabs,si570", "silabs,si571", diff --git a/Documentation/devicetree/bindings/clock/ti,cdce706.txt b/Documentation/devicetree/bindings/clock/ti,cdce706.txt index 959d96632f5d..21c3ff764788 100644 --- a/Documentation/devicetree/bindings/clock/ti,cdce706.txt +++ b/Documentation/devicetree/bindings/clock/ti,cdce706.txt @@ -1,7 +1,7 @@ Bindings for Texas Instruments CDCE706 programmable 3-PLL clock synthesizer/multiplier/divider. -Reference: http://www.ti.com/lit/ds/symlink/cdce706.pdf +Reference: https://www.ti.com/lit/ds/symlink/cdce706.pdf I2C device node required properties: - compatible: shall be "ti,cdce706". diff --git a/Documentation/devicetree/bindings/clock/ti,cdce925.txt b/Documentation/devicetree/bindings/clock/ti,cdce925.txt index 26544c85202a..df42ab72718f 100644 --- a/Documentation/devicetree/bindings/clock/ti,cdce925.txt +++ b/Documentation/devicetree/bindings/clock/ti,cdce925.txt @@ -4,10 +4,10 @@ Reference This binding uses the common clock binding[1]. [1] Documentation/devicetree/bindings/clock/clock-bindings.txt -[2] http://www.ti.com/product/cdce913 -[3] http://www.ti.com/product/cdce925 -[4] http://www.ti.com/product/cdce937 -[5] http://www.ti.com/product/cdce949 +[2] https://www.ti.com/product/cdce913 +[3] https://www.ti.com/product/cdce925 +[4] https://www.ti.com/product/cdce937 +[5] https://www.ti.com/product/cdce949 The driver provides clock sources for each output Y1 through Y5. diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt b/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt index 332aed8f4597..56f442374383 100644 --- a/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt @@ -18,7 +18,8 @@ Optional properties: in unit of nanoseconds. - voltage-tolerance: Specify the CPU voltage tolerance in percentage. - #cooling-cells: - Please refer to Documentation/devicetree/bindings/thermal/thermal.txt. + Please refer to + Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml. Examples: diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek.txt b/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek.txt index 0551c78619de..ea4994b35207 100644 --- a/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek.txt +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek.txt @@ -21,8 +21,8 @@ Optional properties: flow is handled by hardware, hence no software "voltage tracking" is needed. - #cooling-cells: - Please refer to Documentation/devicetree/bindings/thermal/thermal.txt - for detail. + For details, please refer to + Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml Example 1 (MT7623 SoC): diff --git a/Documentation/devicetree/bindings/cpufreq/nvidia,tegra20-cpufreq.txt b/Documentation/devicetree/bindings/cpufreq/nvidia,tegra20-cpufreq.txt index daeca6ae6b76..52a24b82fd86 100644 --- a/Documentation/devicetree/bindings/cpufreq/nvidia,tegra20-cpufreq.txt +++ b/Documentation/devicetree/bindings/cpufreq/nvidia,tegra20-cpufreq.txt @@ -5,7 +5,7 @@ Required properties: - clocks: Must contain an entry for the CPU clock. See ../clocks/clock-bindings.txt for details. - operating-points-v2: See ../bindings/opp/opp.txt for details. -- #cooling-cells: Should be 2. See ../thermal/thermal.txt for details. +- #cooling-cells: Should be 2. See ../thermal/thermal-cooling-devices.yaml for details. For each opp entry in 'operating-points-v2' table: - opp-supported-hw: Two bitfields indicating: diff --git a/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml b/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml new file mode 100644 index 000000000000..85ef69ffebed --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/crypto/ti,sa2ul.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: K3 SoC SA2UL crypto module + +maintainers: + - Tero Kristo <t-kristo@ti.com> + +properties: + compatible: + enum: + - ti,j721e-sa2ul + - ti,am654-sa2ul + + reg: + maxItems: 1 + + power-domains: + maxItems: 1 + + dmas: + items: + - description: TX DMA Channel + - description: RX DMA Channel #1 + - description: RX DMA Channel #2 + + dma-names: + items: + - const: tx + - const: rx1 + - const: rx2 + + dma-coherent: true + + "#address-cells": + const: 2 + + "#size-cells": + const: 2 + + ranges: + description: + Address translation for the possible RNG child node for SA2UL + +patternProperties: + "^rng@[a-f0-9]+$": + type: object + description: + Child RNG node for SA2UL + +required: + - compatible + - reg + - power-domains + - dmas + - dma-names + - dma-coherent + +additionalProperties: false + +examples: + - | + #include <dt-bindings/soc/ti,sci_pm_domain.h> + + main_crypto: crypto@4e00000 { + compatible = "ti,j721-sa2ul"; + reg = <0x0 0x4e00000 0x0 0x1200>; + power-domains = <&k3_pds 264 TI_SCI_PD_EXCLUSIVE>; + dmas = <&main_udmap 0xc000>, <&main_udmap 0x4000>, + <&main_udmap 0x4001>; + dma-names = "tx", "rx1", "rx2"; + dma-coherent; + }; diff --git a/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt b/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt index 0ec68141f85a..a10d1f6d85c6 100644 --- a/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt +++ b/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt @@ -18,6 +18,8 @@ Optional properties: format depends on the interrupt controller. It should be a DCF interrupt. When DDR DVFS finishes a DCF interrupt is triggered. +- rockchip,pmu: Phandle to the syscon managing the "PMU general register + files". Following properties relate to DDR timing: diff --git a/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-de2-mixer.yaml b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-de2-mixer.yaml index 1dee641e3ea1..c040eef56518 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-de2-mixer.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-de2-mixer.yaml @@ -36,6 +36,9 @@ properties: - const: bus - const: mod + iommus: + maxItems: 1 + resets: maxItems: 1 diff --git a/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt b/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt deleted file mode 100644 index 26649b4c4dd8..000000000000 --- a/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt +++ /dev/null @@ -1,174 +0,0 @@ -Broadcom VC4 (VideoCore4) GPU - -The VC4 device present on the Raspberry Pi includes a display system -with HDMI output and the HVS (Hardware Video Scaler) for compositing -display planes. - -Required properties for VC4: -- compatible: Should be "brcm,bcm2835-vc4" or "brcm,cygnus-vc4" - -Required properties for Pixel Valve: -- compatible: Should be one of "brcm,bcm2835-pixelvalve0", - "brcm,bcm2835-pixelvalve1", or "brcm,bcm2835-pixelvalve2" -- reg: Physical base address and length of the PV's registers -- interrupts: The interrupt number - See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt - -Required properties for HVS: -- compatible: Should be "brcm,bcm2835-hvs" -- reg: Physical base address and length of the HVS's registers -- interrupts: The interrupt number - See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt - -Required properties for HDMI -- compatible: Should be "brcm,bcm2835-hdmi" -- reg: Physical base address and length of the two register ranges - ("HDMI" and "HD", in that order) -- interrupts: The interrupt numbers - See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt -- ddc: phandle of the I2C controller used for DDC EDID probing -- clocks: a) hdmi: The HDMI state machine clock - b) pixel: The pixel clock. - -Optional properties for HDMI: -- hpd-gpios: The GPIO pin for HDMI hotplug detect (if it doesn't appear - as an interrupt/status bit in the HDMI controller - itself). See bindings/pinctrl/brcm,bcm2835-gpio.txt -- dmas: Should contain one entry pointing to the DMA channel used to - transfer audio data -- dma-names: Should contain "audio-rx" - -Required properties for DPI: -- compatible: Should be "brcm,bcm2835-dpi" -- reg: Physical base address and length of the registers -- clocks: a) core: The core clock the unit runs on - b) pixel: The pixel clock that feeds the pixelvalve -- port: Port node with a single endpoint connecting to the panel - device, as defined in [1] - -Required properties for VEC: -- compatible: Should be "brcm,bcm2835-vec" -- reg: Physical base address and length of the registers -- clocks: The core clock the unit runs on -- interrupts: The interrupt number - See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt - -Required properties for V3D: -- compatible: Should be "brcm,bcm2835-v3d" or "brcm,cygnus-v3d" -- reg: Physical base address and length of the V3D's registers -- interrupts: The interrupt number - See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt - -Optional properties for V3D: -- clocks: The clock the unit runs on - -Required properties for DSI: -- compatible: Should be "brcm,bcm2835-dsi0" or "brcm,bcm2835-dsi1" -- reg: Physical base address and length of the DSI block's registers -- interrupts: The interrupt number - See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt -- clocks: a) phy: The DSI PLL clock feeding the DSI analog PHY - b) escape: The DSI ESC clock from CPRMAN - c) pixel: The DSI pixel clock from CPRMAN -- clock-output-names: - The 3 clocks output from the DSI analog PHY: dsi[01]_byte, - dsi[01]_ddr2, and dsi[01]_ddr - -Required properties for the TXP (writeback) block: -- compatible: Should be "brcm,bcm2835-txp" -- reg: Physical base address and length of the TXP block's registers -- interrupts: The interrupt number - See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt - -[1] Documentation/devicetree/bindings/media/video-interfaces.txt - -Example: -pixelvalve@7e807000 { - compatible = "brcm,bcm2835-pixelvalve2"; - reg = <0x7e807000 0x100>; - interrupts = <2 10>; /* pixelvalve */ -}; - -hvs@7e400000 { - compatible = "brcm,bcm2835-hvs"; - reg = <0x7e400000 0x6000>; - interrupts = <2 1>; -}; - -hdmi: hdmi@7e902000 { - compatible = "brcm,bcm2835-hdmi"; - reg = <0x7e902000 0x600>, - <0x7e808000 0x100>; - interrupts = <2 8>, <2 9>; - ddc = <&i2c2>; - hpd-gpios = <&gpio 46 GPIO_ACTIVE_HIGH>; - clocks = <&clocks BCM2835_PLLH_PIX>, - <&clocks BCM2835_CLOCK_HSM>; - clock-names = "pixel", "hdmi"; -}; - -dpi: dpi@7e208000 { - compatible = "brcm,bcm2835-dpi"; - reg = <0x7e208000 0x8c>; - clocks = <&clocks BCM2835_CLOCK_VPU>, - <&clocks BCM2835_CLOCK_DPI>; - clock-names = "core", "pixel"; - #address-cells = <1>; - #size-cells = <0>; - - port { - dpi_out: endpoint@0 { - remote-endpoint = <&panel_in>; - }; - }; -}; - -dsi1: dsi@7e700000 { - compatible = "brcm,bcm2835-dsi1"; - reg = <0x7e700000 0x8c>; - interrupts = <2 12>; - #address-cells = <1>; - #size-cells = <0>; - #clock-cells = <1>; - - clocks = <&clocks BCM2835_PLLD_DSI1>, - <&clocks BCM2835_CLOCK_DSI1E>, - <&clocks BCM2835_CLOCK_DSI1P>; - clock-names = "phy", "escape", "pixel"; - - clock-output-names = "dsi1_byte", "dsi1_ddr2", "dsi1_ddr"; - - pitouchscreen: panel@0 { - compatible = "raspberrypi,touchscreen"; - reg = <0>; - - <...> - }; -}; - -vec: vec@7e806000 { - compatible = "brcm,bcm2835-vec"; - reg = <0x7e806000 0x1000>; - clocks = <&clocks BCM2835_CLOCK_VEC>; - interrupts = <2 27>; -}; - -v3d: v3d@7ec00000 { - compatible = "brcm,bcm2835-v3d"; - reg = <0x7ec00000 0x1000>; - interrupts = <1 10>; -}; - -vc4: gpu { - compatible = "brcm,bcm2835-vc4"; -}; - -panel: panel { - compatible = "ontat,yx700wv03", "simple-panel"; - - port { - panel_in: endpoint { - remote-endpoint = <&dpi_out>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-dpi.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-dpi.yaml new file mode 100644 index 000000000000..5c1024bbc1b3 --- /dev/null +++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-dpi.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/brcm,bcm2835-dpi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom VC4 (VideoCore4) DPI Controller + +maintainers: + - Eric Anholt <eric@anholt.net> + +properties: + compatible: + const: brcm,bcm2835-dpi + + reg: + maxItems: 1 + + clocks: + items: + - description: The core clock the unit runs on + - description: The pixel clock that feeds the pixelvalve + + clock-names: + items: + - const: core + - const: pixel + + port: + type: object + description: > + Port node with a single endpoint connecting to the panel, as + defined in Documentation/devicetree/bindings/media/video-interfaces.txt. + +required: + - compatible + - reg + - clocks + - clock-names + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/bcm2835.h> + + dpi: dpi@7e208000 { + compatible = "brcm,bcm2835-dpi"; + reg = <0x7e208000 0x8c>; + clocks = <&clocks BCM2835_CLOCK_VPU>, + <&clocks BCM2835_CLOCK_DPI>; + clock-names = "core", "pixel"; + + port { + dpi_out: endpoint { + remote-endpoint = <&panel_in>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-dsi0.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-dsi0.yaml new file mode 100644 index 000000000000..3c643b227a70 --- /dev/null +++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-dsi0.yaml @@ -0,0 +1,84 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/brcm,bcm2835-dsi0.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom VC4 (VideoCore4) DSI Controller + +maintainers: + - Eric Anholt <eric@anholt.net> + +properties: + "#clock-cells": + const: 1 + + compatible: + enum: + - brcm,bcm2835-dsi0 + - brcm,bcm2835-dsi1 + + reg: + maxItems: 1 + + clocks: + items: + - description: The DSI PLL clock feeding the DSI analog PHY + - description: The DSI ESC clock + - description: The DSI pixel clock + + clock-names: + items: + - const: phy + - const: escape + - const: pixel + + clock-output-names: true + # FIXME: The meta-schemas don't seem to allow it for now + # items: + # - description: The DSI byte clock for the PHY + # - description: The DSI DDR2 clock + # - description: The DSI DDR clock + + interrupts: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-names + - clock-output-names + - interrupts + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/bcm2835.h> + + dsi1: dsi@7e700000 { + compatible = "brcm,bcm2835-dsi1"; + reg = <0x7e700000 0x8c>; + interrupts = <2 12>; + #address-cells = <1>; + #size-cells = <0>; + #clock-cells = <1>; + + clocks = <&clocks BCM2835_PLLD_DSI1>, + <&clocks BCM2835_CLOCK_DSI1E>, + <&clocks BCM2835_CLOCK_DSI1P>; + clock-names = "phy", "escape", "pixel"; + + clock-output-names = "dsi1_byte", "dsi1_ddr2", "dsi1_ddr"; + + pitouchscreen: panel@0 { + compatible = "raspberrypi,touchscreen"; + reg = <0>; + + /* ... */ + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-hdmi.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-hdmi.yaml new file mode 100644 index 000000000000..52b3cdac0bdf --- /dev/null +++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-hdmi.yaml @@ -0,0 +1,80 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/brcm,bcm2835-hdmi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom VC4 (VideoCore4) HDMI Controller + +maintainers: + - Eric Anholt <eric@anholt.net> + +properties: + compatible: + const: brcm,bcm2835-hdmi + + reg: + items: + - description: HDMI register range + - description: HD register range + + interrupts: + minItems: 2 + + clocks: + items: + - description: The pixel clock + - description: The HDMI state machine clock + + clock-names: + items: + - const: pixel + - const: hdmi + + ddc: + allOf: + - $ref: /schemas/types.yaml#/definitions/phandle + description: > + Phandle of the I2C controller used for DDC EDID probing + + hpd-gpios: + description: > + The GPIO pin for the HDMI hotplug detect (if it doesn't appear + as an interrupt/status bit in the HDMI controller itself) + + dmas: + maxItems: 1 + description: > + Should contain one entry pointing to the DMA channel used to + transfer audio data. + + dma-names: + const: audio-rx + +required: + - compatible + - reg + - interrupts + - clocks + - ddc + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/bcm2835.h> + #include <dt-bindings/gpio/gpio.h> + + hdmi: hdmi@7e902000 { + compatible = "brcm,bcm2835-hdmi"; + reg = <0x7e902000 0x600>, + <0x7e808000 0x100>; + interrupts = <2 8>, <2 9>; + ddc = <&i2c2>; + hpd-gpios = <&gpio 46 GPIO_ACTIVE_HIGH>; + clocks = <&clocks BCM2835_PLLH_PIX>, + <&clocks BCM2835_CLOCK_HSM>; + clock-names = "pixel", "hdmi"; + }; + +... diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-hvs.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-hvs.yaml new file mode 100644 index 000000000000..02410f8d6d49 --- /dev/null +++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-hvs.yaml @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/brcm,bcm2835-hvs.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom VC4 (VideoCore4) Hardware Video Scaler + +maintainers: + - Eric Anholt <eric@anholt.net> + +properties: + compatible: + const: brcm,bcm2835-hvs + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + hvs@7e400000 { + compatible = "brcm,bcm2835-hvs"; + reg = <0x7e400000 0x6000>; + interrupts = <2 1>; + }; + +... diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-pixelvalve0.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-pixelvalve0.yaml new file mode 100644 index 000000000000..e60791db1fa1 --- /dev/null +++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-pixelvalve0.yaml @@ -0,0 +1,40 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/brcm,bcm2835-pixelvalve0.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom VC4 (VideoCore4) PixelValve + +maintainers: + - Eric Anholt <eric@anholt.net> + +properties: + compatible: + enum: + - brcm,bcm2835-pixelvalve0 + - brcm,bcm2835-pixelvalve1 + - brcm,bcm2835-pixelvalve2 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + pixelvalve@7e807000 { + compatible = "brcm,bcm2835-pixelvalve2"; + reg = <0x7e807000 0x100>; + interrupts = <2 10>; /* pixelvalve */ + }; + +... diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-txp.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-txp.yaml new file mode 100644 index 000000000000..bb186197e471 --- /dev/null +++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-txp.yaml @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/brcm,bcm2835-txp.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom VC4 (VideoCore4) TXP (writeback) Controller + +maintainers: + - Eric Anholt <eric@anholt.net> + +properties: + compatible: + const: brcm,bcm2835-txp + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + txp: txp@7e004000 { + compatible = "brcm,bcm2835-txp"; + reg = <0x7e004000 0x20>; + interrupts = <1 11>; + }; + +... diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-v3d.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-v3d.yaml new file mode 100644 index 000000000000..8a73780f573d --- /dev/null +++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-v3d.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/brcm,bcm2835-v3d.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom VC4 (VideoCore4) V3D GPU + +maintainers: + - Eric Anholt <eric@anholt.net> + +properties: + compatible: + enum: + - brcm,bcm2835-v3d + - brcm,cygnus-v3d + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + v3d: v3d@7ec00000 { + compatible = "brcm,bcm2835-v3d"; + reg = <0x7ec00000 0x1000>; + interrupts = <1 10>; + }; + +... diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-vc4.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-vc4.yaml new file mode 100644 index 000000000000..0dcf0c397375 --- /dev/null +++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-vc4.yaml @@ -0,0 +1,34 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/brcm,bcm2835-vc4.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom VC4 (VideoCore4) GPU + +maintainers: + - Eric Anholt <eric@anholt.net> + +description: > + The VC4 device present on the Raspberry Pi includes a display system + with HDMI output and the HVS (Hardware Video Scaler) for compositing + display planes. + +properties: + compatible: + enum: + - brcm,bcm2835-vc4 + - brcm,cygnus-vc4 + +required: + - compatible + +additionalProperties: false + +examples: + - | + vc4: gpu { + compatible = "brcm,bcm2835-vc4"; + }; + +... diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2835-vec.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2835-vec.yaml new file mode 100644 index 000000000000..d900cc57b4ec --- /dev/null +++ b/Documentation/devicetree/bindings/display/brcm,bcm2835-vec.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/brcm,bcm2835-vec.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom VC4 (VideoCore4) VEC + +maintainers: + - Eric Anholt <eric@anholt.net> + +properties: + compatible: + const: brcm,bcm2835-vec + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/bcm2835.h> + + vec: vec@7e806000 { + compatible = "brcm,bcm2835-vec"; + reg = <0x7e806000 0x1000>; + clocks = <&clocks BCM2835_CLOCK_VEC>; + interrupts = <2 27>; + }; + +... diff --git a/Documentation/devicetree/bindings/display/bridge/nwl-dsi.yaml b/Documentation/devicetree/bindings/display/bridge/nwl-dsi.yaml index 8aff2d68fc33..2c4c34e3bc29 100644 --- a/Documentation/devicetree/bindings/display/bridge/nwl-dsi.yaml +++ b/Documentation/devicetree/bindings/display/bridge/nwl-dsi.yaml @@ -165,6 +165,7 @@ examples: - | #include <dt-bindings/clock/imx8mq-clock.h> + #include <dt-bindings/gpio/gpio.h> #include <dt-bindings/interrupt-controller/arm-gic.h> #include <dt-bindings/reset/imx8mq-reset.h> @@ -191,12 +192,12 @@ examples: phy-names = "dphy"; panel@0 { - #address-cells = <1>; - #size-cells = <0>; compatible = "rocktech,jh057n00900"; reg = <0>; - port@0 { - reg = <0>; + vcc-supply = <®_2v8_p>; + iovcc-supply = <®_1v8_p>; + reset-gpios = <&gpio3 13 GPIO_ACTIVE_LOW>; + port { panel_in: endpoint { remote-endpoint = <&mipi_dsi_out>; }; diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt b/Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt deleted file mode 100644 index c62ce2494ed9..000000000000 --- a/Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt +++ /dev/null @@ -1,85 +0,0 @@ -Renesas R-Car LVDS Encoder -========================== - -These DT bindings describe the LVDS encoder embedded in the Renesas R-Car -Gen2, R-Car Gen3 and RZ/G SoCs. - -Required properties: - -- compatible : Shall contain one of - - "renesas,r8a7743-lvds" for R8A7743 (RZ/G1M) compatible LVDS encoders - - "renesas,r8a7744-lvds" for R8A7744 (RZ/G1N) compatible LVDS encoders - - "renesas,r8a774a1-lvds" for R8A774A1 (RZ/G2M) compatible LVDS encoders - - "renesas,r8a774b1-lvds" for R8A774B1 (RZ/G2N) compatible LVDS encoders - - "renesas,r8a774c0-lvds" for R8A774C0 (RZ/G2E) compatible LVDS encoders - - "renesas,r8a7790-lvds" for R8A7790 (R-Car H2) compatible LVDS encoders - - "renesas,r8a7791-lvds" for R8A7791 (R-Car M2-W) compatible LVDS encoders - - "renesas,r8a7793-lvds" for R8A7793 (R-Car M2-N) compatible LVDS encoders - - "renesas,r8a7795-lvds" for R8A7795 (R-Car H3) compatible LVDS encoders - - "renesas,r8a7796-lvds" for R8A7796 (R-Car M3-W) compatible LVDS encoders - - "renesas,r8a77965-lvds" for R8A77965 (R-Car M3-N) compatible LVDS encoders - - "renesas,r8a77970-lvds" for R8A77970 (R-Car V3M) compatible LVDS encoders - - "renesas,r8a77980-lvds" for R8A77980 (R-Car V3H) compatible LVDS encoders - - "renesas,r8a77990-lvds" for R8A77990 (R-Car E3) compatible LVDS encoders - - "renesas,r8a77995-lvds" for R8A77995 (R-Car D3) compatible LVDS encoders - -- reg: Base address and length for the memory-mapped registers -- clocks: A list of phandles + clock-specifier pairs, one for each entry in - the clock-names property. -- clock-names: Name of the clocks. This property is model-dependent. - - The functional clock, which mandatory for all models, shall be listed - first, and shall be named "fck". - - On R8A77990, R8A77995 and R8A774C0, the LVDS encoder can use the EXTAL or - DU_DOTCLKINx clocks. Those clocks are optional. When supplied they must be - named "extal" and "dclkin.x" respectively, with "x" being the DU_DOTCLKIN - numerical index. - - When the clocks property only contains the functional clock, the - clock-names property may be omitted. -- resets: A phandle + reset specifier for the module reset - -Required nodes: - -The LVDS encoder has two video ports. Their connections are modelled using the -OF graph bindings specified in Documentation/devicetree/bindings/graph.txt. - -- Video port 0 corresponds to the parallel RGB input -- Video port 1 corresponds to the LVDS output - -Each port shall have a single endpoint. - -Optional properties: - -- renesas,companion : phandle to the companion LVDS encoder. This property is - mandatory for the first LVDS encoder on D3 and E3 SoCs, and shall point to - the second encoder to be used as a companion in dual-link mode. It shall not - be set for any other LVDS encoder. - - -Example: - - lvds0: lvds@feb90000 { - compatible = "renesas,r8a77990-lvds"; - reg = <0 0xfeb90000 0 0x20>; - clocks = <&cpg CPG_MOD 727>; - power-domains = <&sysc R8A77990_PD_ALWAYS_ON>; - resets = <&cpg 727>; - - renesas,companion = <&lvds1>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - lvds0_in: endpoint { - remote-endpoint = <&du_out_lvds0>; - }; - }; - port@1 { - reg = <1>; - lvds0_out: endpoint { - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,lvds.yaml b/Documentation/devicetree/bindings/display/bridge/renesas,lvds.yaml new file mode 100644 index 000000000000..98c7330a9485 --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/renesas,lvds.yaml @@ -0,0 +1,248 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/renesas,lvds.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car LVDS Encoder + +maintainers: + - Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> + +description: | + These DT bindings describe the LVDS encoder embedded in the Renesas R-Car + Gen2, R-Car Gen3, RZ/G1 and RZ/G2 SoCs. + +properties: + compatible: + enum: + - renesas,r8a7743-lvds # for RZ/G1M compatible LVDS encoders + - renesas,r8a7744-lvds # for RZ/G1N compatible LVDS encoders + - renesas,r8a774a1-lvds # for RZ/G2M compatible LVDS encoders + - renesas,r8a774b1-lvds # for RZ/G2N compatible LVDS encoders + - renesas,r8a774c0-lvds # for RZ/G2E compatible LVDS encoders + - renesas,r8a7790-lvds # for R-Car H2 compatible LVDS encoders + - renesas,r8a7791-lvds # for R-Car M2-W compatible LVDS encoders + - renesas,r8a7793-lvds # for R-Car M2-N compatible LVDS encoders + - renesas,r8a7795-lvds # for R-Car H3 compatible LVDS encoders + - renesas,r8a7796-lvds # for R-Car M3-W compatible LVDS encoders + - renesas,r8a77965-lvds # for R-Car M3-N compatible LVDS encoders + - renesas,r8a77970-lvds # for R-Car V3M compatible LVDS encoders + - renesas,r8a77980-lvds # for R-Car V3H compatible LVDS encoders + - renesas,r8a77990-lvds # for R-Car E3 compatible LVDS encoders + - renesas,r8a77995-lvds # for R-Car D3 compatible LVDS encoders + + reg: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 4 + + clock-names: + minItems: 1 + maxItems: 4 + + resets: + maxItems: 1 + + ports: + type: object + description: | + This device has two video ports. Their connections are modelled using the + OF graph bindings specified in Documentation/devicetree/bindings/graph.txt. + Each port shall have a single endpoint. + + properties: + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + port@0: + type: object + description: Parallel RGB input port + + port@1: + type: object + description: LVDS output port + + required: + - port@0 + - port@1 + + additionalProperties: false + + power-domains: + maxItems: 1 + + renesas,companion: + $ref: /schemas/types.yaml#/definitions/phandle + description: + phandle to the companion LVDS encoder. This property is mandatory + for the first LVDS encoder on D3 and E3 SoCs, and shall point to + the second encoder to be used as a companion in dual-link mode. It + shall not be set for any other LVDS encoder. + +required: + - compatible + - reg + - clocks + - power-domains + - resets + - ports + +if: + properties: + compatible: + enum: + - renesas,r8a774c0-lvds + - renesas,r8a77990-lvds + - renesas,r8a77995-lvds +then: + properties: + clocks: + minItems: 1 + maxItems: 4 + items: + - description: Functional clock + - description: EXTAL input clock + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + + clock-names: + minItems: 1 + maxItems: 4 + items: + - const: fck + # The LVDS encoder can use the EXTAL or DU_DOTCLKINx clocks. + # These clocks are optional. + - enum: + - extal + - dclkin.0 + - dclkin.1 + - enum: + - extal + - dclkin.0 + - dclkin.1 + - enum: + - extal + - dclkin.0 + - dclkin.1 + + required: + - clock-names + +else: + properties: + clocks: + maxItems: 1 + items: + - description: Functional clock + + clock-names: + maxItems: 1 + items: + - const: fck + + renesas,companion: false + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/renesas-cpg-mssr.h> + #include <dt-bindings/power/r8a7795-sysc.h> + + lvds@feb90000 { + compatible = "renesas,r8a7795-lvds"; + reg = <0xfeb90000 0x14>; + clocks = <&cpg CPG_MOD 727>; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + resets = <&cpg 727>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + lvds_in: endpoint { + remote-endpoint = <&du_out_lvds0>; + }; + }; + port@1 { + reg = <1>; + lvds_out: endpoint { + remote-endpoint = <&panel_in>; + }; + }; + }; + }; + + - | + #include <dt-bindings/clock/renesas-cpg-mssr.h> + #include <dt-bindings/power/r8a77990-sysc.h> + + lvds0: lvds@feb90000 { + compatible = "renesas,r8a77990-lvds"; + reg = <0xfeb90000 0x20>; + clocks = <&cpg CPG_MOD 727>, + <&x13_clk>, + <&extal_clk>; + clock-names = "fck", "dclkin.0", "extal"; + power-domains = <&sysc R8A77990_PD_ALWAYS_ON>; + resets = <&cpg 727>; + + renesas,companion = <&lvds1>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + lvds0_in: endpoint { + remote-endpoint = <&du_out_lvds0>; + }; + }; + port@1 { + reg = <1>; + lvds0_out: endpoint { + remote-endpoint = <&panel_in1>; + }; + }; + }; + }; + + lvds1: lvds@feb90100 { + compatible = "renesas,r8a77990-lvds"; + reg = <0xfeb90100 0x20>; + clocks = <&cpg CPG_MOD 727>, + <&x13_clk>, + <&extal_clk>; + clock-names = "fck", "dclkin.0", "extal"; + power-domains = <&sysc R8A77990_PD_ALWAYS_ON>; + resets = <&cpg 726>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + lvds1_in: endpoint { + remote-endpoint = <&du_out_lvds1>; + }; + }; + port@1 { + reg = <1>; + lvds1_out: endpoint { + remote-endpoint = <&panel_in2>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/bridge/sii902x.txt b/Documentation/devicetree/bindings/display/bridge/sii902x.txt index 6e14e087c0d0..0d1db3f9da84 100644 --- a/Documentation/devicetree/bindings/display/bridge/sii902x.txt +++ b/Documentation/devicetree/bindings/display/bridge/sii902x.txt @@ -37,7 +37,7 @@ Optional properties: simple-card or audio-graph-card binding. See their binding documents on how to describe the way the sii902x device is connected to the rest of the audio system: - Documentation/devicetree/bindings/sound/simple-card.txt + Documentation/devicetree/bindings/sound/simple-card.yaml Documentation/devicetree/bindings/sound/audio-graph-card.txt Note: In case of the audio-graph-card binding the used port index should be 3. diff --git a/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.txt b/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.txt deleted file mode 100644 index 8ec4a7f2623a..000000000000 --- a/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.txt +++ /dev/null @@ -1,87 +0,0 @@ -SN65DSI86 DSI to eDP bridge chip --------------------------------- - -This is the binding for Texas Instruments SN65DSI86 bridge. -http://www.ti.com/general/docs/lit/getliterature.tsp?genericPartNumber=sn65dsi86&fileType=pdf - -Required properties: -- compatible: Must be "ti,sn65dsi86" -- reg: i2c address of the chip, 0x2d as per datasheet -- enable-gpios: gpio specification for bridge_en pin (active high) - -- vccio-supply: A 1.8V supply that powers up the digital IOs. -- vpll-supply: A 1.8V supply that powers up the displayport PLL. -- vcca-supply: A 1.2V supply that powers up the analog circuits. -- vcc-supply: A 1.2V supply that powers up the digital core. - -Optional properties: -- interrupts-extended: Specifier for the SN65DSI86 interrupt line. - -- gpio-controller: Marks the device has a GPIO controller. -- #gpio-cells : Should be two. The first cell is the pin number and - the second cell is used to specify flags. - See ../../gpio/gpio.txt for more information. -- #pwm-cells : Should be one. See ../../pwm/pwm.yaml for description of - the cell formats. - -- clock-names: should be "refclk" -- clocks: Specification for input reference clock. The reference - clock rate must be 12 MHz, 19.2 MHz, 26 MHz, 27 MHz or 38.4 MHz. - -- data-lanes: See ../../media/video-interface.txt -- lane-polarities: See ../../media/video-interface.txt - -- suspend-gpios: specification for GPIO1 pin on bridge (active low) - -Required nodes: -This device has two video ports. Their connections are modelled using the -OF graph bindings specified in Documentation/devicetree/bindings/graph.txt. - -- Video port 0 for DSI input -- Video port 1 for eDP output - -Example -------- - -edp-bridge@2d { - compatible = "ti,sn65dsi86"; - #address-cells = <1>; - #size-cells = <0>; - reg = <0x2d>; - - enable-gpios = <&msmgpio 33 GPIO_ACTIVE_HIGH>; - suspend-gpios = <&msmgpio 34 GPIO_ACTIVE_LOW>; - - interrupts-extended = <&gpio3 4 IRQ_TYPE_EDGE_FALLING>; - - vccio-supply = <&pm8916_l17>; - vcca-supply = <&pm8916_l6>; - vpll-supply = <&pm8916_l17>; - vcc-supply = <&pm8916_l6>; - - clock-names = "refclk"; - clocks = <&input_refclk>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - - edp_bridge_in: endpoint { - remote-endpoint = <&dsi_out>; - }; - }; - - port@1 { - reg = <1>; - - edp_bridge_out: endpoint { - data-lanes = <2 1 3 0>; - lane-polarities = <0 1 0 1>; - remote-endpoint = <&edp_panel_in>; - }; - }; - }; -} diff --git a/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml b/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml new file mode 100644 index 000000000000..f8622bd0f61e --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml @@ -0,0 +1,293 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/ti,sn65dsi86.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: SN65DSI86 DSI to eDP bridge chip + +maintainers: + - Sandeep Panda <spanda@codeaurora.org> + +description: | + The Texas Instruments SN65DSI86 bridge takes MIPI DSI in and outputs eDP. + https://www.ti.com/general/docs/lit/getliterature.tsp?genericPartNumber=sn65dsi86&fileType=pdf + +properties: + compatible: + const: ti,sn65dsi86 + + reg: + const: 0x2d + + enable-gpios: + maxItems: 1 + description: GPIO specifier for bridge_en pin (active high). + + suspend-gpios: + maxItems: 1 + description: GPIO specifier for GPIO1 pin on bridge (active low). + + no-hpd: + type: boolean + description: + Set if the HPD line on the bridge isn't hooked up to anything or is + otherwise unusable. + + vccio-supply: + description: A 1.8V supply that powers the digital IOs. + + vpll-supply: + description: A 1.8V supply that powers the DisplayPort PLL. + + vcca-supply: + description: A 1.2V supply that powers the analog circuits. + + vcc-supply: + description: A 1.2V supply that powers the digital core. + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + description: + Clock specifier for input reference clock. The reference clock rate must + be 12 MHz, 19.2 MHz, 26 MHz, 27 MHz or 38.4 MHz. + + clock-names: + const: refclk + + gpio-controller: true + '#gpio-cells': + const: 2 + description: + First cell is pin number, second cell is flags. GPIO pin numbers are + 1-based to match the datasheet. See ../../gpio/gpio.txt for more + information. + + '#pwm-cells': + const: 1 + description: See ../../pwm/pwm.yaml for description of the cell formats. + + ports: + type: object + additionalProperties: false + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + port@0: + type: object + additionalProperties: false + + description: + Video port for MIPI DSI input + + properties: + reg: + const: 0 + + endpoint: + type: object + additionalProperties: false + properties: + remote-endpoint: true + + required: + - reg + + port@1: + type: object + additionalProperties: false + + description: + Video port for eDP output (panel or connector). + + properties: + reg: + const: 1 + + endpoint: + type: object + additionalProperties: false + + properties: + remote-endpoint: true + + data-lanes: + oneOf: + - minItems: 1 + maxItems: 1 + uniqueItems: true + items: + enum: + - 0 + - 1 + description: + If you have 1 logical lane the bridge supports routing + to either port 0 or port 1. Port 0 is suggested. + See ../../media/video-interface.txt for details. + + - minItems: 2 + maxItems: 2 + uniqueItems: true + items: + enum: + - 0 + - 1 + description: + If you have 2 logical lanes the bridge supports + reordering but only on physical ports 0 and 1. + See ../../media/video-interface.txt for details. + + - minItems: 4 + maxItems: 4 + uniqueItems: true + items: + enum: + - 0 + - 1 + - 2 + - 3 + description: + If you have 4 logical lanes the bridge supports + reordering in any way. + See ../../media/video-interface.txt for details. + + lane-polarities: + minItems: 1 + maxItems: 4 + items: + enum: + - 0 + - 1 + description: See ../../media/video-interface.txt + + dependencies: + lane-polarities: [data-lanes] + + required: + - reg + + required: + - "#address-cells" + - "#size-cells" + - port@0 + - port@1 + +required: + - compatible + - reg + - enable-gpios + - vccio-supply + - vpll-supply + - vcca-supply + - vcc-supply + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + bridge@2d { + compatible = "ti,sn65dsi86"; + reg = <0x2d>; + + interrupt-parent = <&tlmm>; + interrupts = <10 IRQ_TYPE_LEVEL_HIGH>; + + enable-gpios = <&tlmm 102 GPIO_ACTIVE_HIGH>; + + vpll-supply = <&src_pp1800_s4a>; + vccio-supply = <&src_pp1800_s4a>; + vcca-supply = <&src_pp1200_l2a>; + vcc-supply = <&src_pp1200_l2a>; + + clocks = <&rpmhcc RPMH_LN_BB_CLK2>; + clock-names = "refclk"; + + no-hpd; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + endpoint { + remote-endpoint = <&dsi0_out>; + }; + }; + + port@1 { + reg = <1>; + endpoint { + remote-endpoint = <&panel_in_edp>; + }; + }; + }; + }; + }; + - | + #include <dt-bindings/clock/qcom,rpmh.h> + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + bridge@2d { + compatible = "ti,sn65dsi86"; + reg = <0x2d>; + + enable-gpios = <&msmgpio 33 GPIO_ACTIVE_HIGH>; + suspend-gpios = <&msmgpio 34 GPIO_ACTIVE_LOW>; + + interrupts-extended = <&gpio3 4 IRQ_TYPE_EDGE_FALLING>; + + vccio-supply = <&pm8916_l17>; + vcca-supply = <&pm8916_l6>; + vpll-supply = <&pm8916_l17>; + vcc-supply = <&pm8916_l6>; + + clock-names = "refclk"; + clocks = <&input_refclk>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + edp_bridge_in: endpoint { + remote-endpoint = <&dsi_out>; + }; + }; + + port@1 { + reg = <1>; + + edp_bridge_out: endpoint { + data-lanes = <2 1 3 0>; + lane-polarities = <0 1 0 1>; + remote-endpoint = <&edp_panel_in>; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/bridge/ti,tfp410.txt b/Documentation/devicetree/bindings/display/bridge/ti,tfp410.txt deleted file mode 100644 index 5ff4f64ef8e8..000000000000 --- a/Documentation/devicetree/bindings/display/bridge/ti,tfp410.txt +++ /dev/null @@ -1,66 +0,0 @@ -TFP410 DPI to DVI encoder -========================= - -Required properties: -- compatible: "ti,tfp410" - -Optional properties: -- powerdown-gpios: power-down gpio -- reg: I2C address. If and only if present the device node should be placed - into the I2C controller node where the TFP410 I2C is connected to. -- ti,deskew: data de-skew in 350ps increments, from -4 to +3, as configured - through th DK[3:1] pins. This property shall be present only if the TFP410 - is not connected through I2C. - -Required nodes: - -This device has two video ports. Their connections are modeled using the OF -graph bindings specified in [1]. Each port node shall have a single endpoint. - -- Port 0 is the DPI input port. Its endpoint subnode shall contain a - pclk-sample and bus-width property and a remote-endpoint property as specified - in [1]. - - If pclk-sample is not defined, pclk-sample = 0 should be assumed for - backward compatibility. - - If bus-width is not defined then bus-width = 24 should be assumed for - backward compatibility. - bus-width = 24: 24 data lines are connected and single-edge mode - bus-width = 12: 12 data lines are connected and dual-edge mode - -- Port 1 is the DVI output port. Its endpoint subnode shall contain a - remote-endpoint property is specified in [1]. - -[1] Documentation/devicetree/bindings/media/video-interfaces.txt - - -Example -------- - -tfp410: encoder@0 { - compatible = "ti,tfp410"; - powerdown-gpios = <&twl_gpio 2 GPIO_ACTIVE_LOW>; - ti,deskew = <4>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - - tfp410_in: endpoint@0 { - pclk-sample = <1>; - bus-width = <24>; - remote-endpoint = <&dpi_out>; - }; - }; - - port@1 { - reg = <1>; - - tfp410_out: endpoint@0 { - remote-endpoint = <&dvi_connector_in>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/display/bridge/ti,tfp410.yaml b/Documentation/devicetree/bindings/display/bridge/ti,tfp410.yaml new file mode 100644 index 000000000000..605831c1e836 --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/ti,tfp410.yaml @@ -0,0 +1,131 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/ti,tfp410.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TFP410 DPI to DVI encoder + +maintainers: + - Tomi Valkeinen <tomi.valkeinen@ti.com> + - Jyri Sarha <jsarha@ti.com> + +properties: + compatible: + const: ti,tfp410 + + reg: + description: I2C address of the device. + maxItems: 1 + + powerdown-gpios: + maxItems: 1 + + ti,deskew: + description: + Data de-skew value in 350ps increments, from 0 to 7, as configured + through the DK[3:1] pins. The de-skew multiplier is computed as + (DK[3:1] - 4), so it ranges from -4 to 3. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 7 + + ports: + description: + A node containing input and output port nodes with endpoint + definitions as documented in + Documentation/devicetree/bindings/media/video-interfaces.txt + type: object + + properties: + port@0: + description: DPI input port. + type: object + + properties: + reg: + const: 0 + + endpoint: + type: object + + properties: + pclk-sample: + description: + Endpoint sampling edge. + enum: + - 0 # Falling edge + - 1 # Rising edge + default: 0 + + bus-width: + description: + Endpoint bus width. + enum: + - 12 # 12 data lines connected and dual-edge mode + - 24 # 24 data lines connected and single-edge mode + default: 24 + + port@1: + description: DVI output port. + type: object + + properties: + reg: + const: 1 + + endpoint: + type: object + + required: + - port@0 + - port@1 + +required: + - compatible + - ports + +if: + required: + - reg +then: + properties: + ti,deskew: false +else: + required: + - ti,deskew + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + tfp410: encoder { + compatible = "ti,tfp410"; + powerdown-gpios = <&twl_gpio 2 GPIO_ACTIVE_LOW>; + ti,deskew = <3>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + tfp410_in: endpoint { + pclk-sample = <1>; + bus-width = <24>; + remote-endpoint = <&dpi_out>; + }; + }; + + port@1 { + reg = <1>; + tfp410_out: endpoint { + remote-endpoint = <&dvi_connector_in>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/connector/analog-tv-connector.txt b/Documentation/devicetree/bindings/display/connector/analog-tv-connector.txt deleted file mode 100644 index 883bcb2604c7..000000000000 --- a/Documentation/devicetree/bindings/display/connector/analog-tv-connector.txt +++ /dev/null @@ -1,31 +0,0 @@ -Analog TV Connector -=================== - -Required properties: -- compatible: "composite-video-connector" or "svideo-connector" - -Optional properties: -- label: a symbolic name for the connector -- sdtv-standards: limit the supported TV standards on a connector to the given - ones. If not specified all TV standards are allowed. - Possible TV standards are defined in - include/dt-bindings/display/sdtv-standards.h. - -Required nodes: -- Video port for TV input - -Example -------- -#include <dt-bindings/display/sdtv-standards.h> - -tv: connector { - compatible = "composite-video-connector"; - label = "tv"; - sdtv-standards = <(SDTV_STD_PAL | SDTV_STD_NTSC)>; - - port { - tv_connector_in: endpoint { - remote-endpoint = <&venc_out>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/display/connector/analog-tv-connector.yaml b/Documentation/devicetree/bindings/display/connector/analog-tv-connector.yaml new file mode 100644 index 000000000000..eebe88fed999 --- /dev/null +++ b/Documentation/devicetree/bindings/display/connector/analog-tv-connector.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/connector/analog-tv-connector.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog TV Connector + +maintainers: + - Laurent Pinchart <Laurent.pinchart@ideasonboard.com> + +properties: + compatible: + enum: + - composite-video-connector + - svideo-connector + + label: true + + sdtv-standards: + description: + Limit the supported TV standards on a connector to the given ones. If + not specified all TV standards are allowed. Possible TV standards are + defined in include/dt-bindings/display/sdtv-standards.h. + $ref: /schemas/types.yaml#/definitions/uint32 + + port: + description: Connection to controller providing analog TV signals + +required: + - compatible + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/display/sdtv-standards.h> + + connector { + compatible = "composite-video-connector"; + label = "tv"; + sdtv-standards = <(SDTV_STD_PAL | SDTV_STD_NTSC)>; + + port { + tv_connector_in: endpoint { + remote-endpoint = <&venc_out>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/connector/dvi-connector.txt b/Documentation/devicetree/bindings/display/connector/dvi-connector.txt deleted file mode 100644 index 207e42e9eba0..000000000000 --- a/Documentation/devicetree/bindings/display/connector/dvi-connector.txt +++ /dev/null @@ -1,36 +0,0 @@ -DVI Connector -============== - -Required properties: -- compatible: "dvi-connector" - -Optional properties: -- label: a symbolic name for the connector -- ddc-i2c-bus: phandle to the i2c bus that is connected to DVI DDC -- analog: the connector has DVI analog pins -- digital: the connector has DVI digital pins -- dual-link: the connector has pins for DVI dual-link -- hpd-gpios: HPD GPIO number - -Required nodes: -- Video port for DVI input - -Note: One (or both) of 'analog' or 'digital' must be set. - -Example -------- - -dvi0: connector@0 { - compatible = "dvi-connector"; - label = "dvi"; - - digital; - - ddc-i2c-bus = <&i2c3>; - - port { - dvi_connector_in: endpoint { - remote-endpoint = <&tfp410_out>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/display/connector/dvi-connector.yaml b/Documentation/devicetree/bindings/display/connector/dvi-connector.yaml new file mode 100644 index 000000000000..71cb9220fa59 --- /dev/null +++ b/Documentation/devicetree/bindings/display/connector/dvi-connector.yaml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/connector/dvi-connector.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: DVI Connector + +maintainers: + - Laurent Pinchart <Laurent.pinchart@ideasonboard.com> + +properties: + compatible: + const: dvi-connector + + label: true + + hpd-gpios: + description: A GPIO line connected to HPD + maxItems: 1 + + ddc-i2c-bus: + description: phandle link to the I2C controller used for DDC EDID probing + $ref: /schemas/types.yaml#/definitions/phandle + + analog: + type: boolean + description: the connector has DVI analog pins + + digital: + type: boolean + description: the connector has DVI digital pins + + dual-link: + type: boolean + description: the connector has pins for DVI dual-link + + port: + description: Connection to controller providing DVI signals + +required: + - compatible + - port + +anyOf: + - required: + - analog + - required: + - digital + +additionalProperties: false + +examples: + - | + connector { + compatible = "dvi-connector"; + label = "dvi"; + + digital; + + ddc-i2c-bus = <&i2c3>; + + port { + dvi_connector_in: endpoint { + remote-endpoint = <&tfp410_out>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/connector/hdmi-connector.txt b/Documentation/devicetree/bindings/display/connector/hdmi-connector.txt deleted file mode 100644 index aeb07c4bd703..000000000000 --- a/Documentation/devicetree/bindings/display/connector/hdmi-connector.txt +++ /dev/null @@ -1,31 +0,0 @@ -HDMI Connector -============== - -Required properties: -- compatible: "hdmi-connector" -- type: the HDMI connector type: "a", "b", "c", "d" or "e" - -Optional properties: -- label: a symbolic name for the connector -- hpd-gpios: HPD GPIO number -- ddc-i2c-bus: phandle link to the I2C controller used for DDC EDID probing -- ddc-en-gpios: signal to enable DDC bus - -Required nodes: -- Video port for HDMI input - -Example -------- - -hdmi0: connector@1 { - compatible = "hdmi-connector"; - label = "hdmi"; - - type = "a"; - - port { - hdmi_connector_in: endpoint { - remote-endpoint = <&tpd12s015_out>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/display/connector/hdmi-connector.yaml b/Documentation/devicetree/bindings/display/connector/hdmi-connector.yaml new file mode 100644 index 000000000000..14d7128af592 --- /dev/null +++ b/Documentation/devicetree/bindings/display/connector/hdmi-connector.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/connector/hdmi-connector.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: HDMI Connector + +maintainers: + - Laurent Pinchart <Laurent.pinchart@ideasonboard.com> + +properties: + compatible: + const: hdmi-connector + + type: + description: The HDMI connector type + enum: + - a # Standard full size + - b # Never deployed? + - c # Mini + - d # Micro + - e # automotive + + label: true + + hpd-gpios: + description: A GPIO line connected to HPD + maxItems: 1 + + ddc-i2c-bus: + description: phandle link to the I2C controller used for DDC EDID probing + $ref: /schemas/types.yaml#/definitions/phandle + + ddc-en-gpios: + description: GPIO signal to enable DDC bus + maxItems: 1 + + port: + description: Connection to controller providing HDMI signals + +required: + - compatible + - port + - type + +additionalProperties: false + +examples: + - | + connector { + compatible = "hdmi-connector"; + label = "hdmi"; + + type = "a"; + + port { + hdmi_connector_in: endpoint { + remote-endpoint = <&tpd12s015_out>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/connector/vga-connector.txt b/Documentation/devicetree/bindings/display/connector/vga-connector.txt deleted file mode 100644 index c727f298e7ad..000000000000 --- a/Documentation/devicetree/bindings/display/connector/vga-connector.txt +++ /dev/null @@ -1,36 +0,0 @@ -VGA Connector -============= - -Required properties: - -- compatible: "vga-connector" - -Optional properties: - -- label: a symbolic name for the connector corresponding to a hardware label -- ddc-i2c-bus: phandle to the I2C bus that is connected to VGA DDC - -Required nodes: - -The VGA connector internal connections are modeled using the OF graph bindings -specified in Documentation/devicetree/bindings/graph.txt. - -The VGA connector has a single port that must be connected to a video source -port. - - -Example -------- - -vga0: connector@0 { - compatible = "vga-connector"; - label = "vga"; - - ddc-i2c-bus = <&i2c3>; - - port { - vga_connector_in: endpoint { - remote-endpoint = <&adv7123_out>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/display/connector/vga-connector.yaml b/Documentation/devicetree/bindings/display/connector/vga-connector.yaml new file mode 100644 index 000000000000..5782c4bb3252 --- /dev/null +++ b/Documentation/devicetree/bindings/display/connector/vga-connector.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/connector/vga-connector.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: VGA Connector + +maintainers: + - Laurent Pinchart <Laurent.pinchart@ideasonboard.com> + +properties: + compatible: + const: vga-connector + + label: true + + ddc-i2c-bus: + description: phandle link to the I2C controller used for DDC EDID probing + $ref: /schemas/types.yaml#/definitions/phandle + + port: + description: Connection to controller providing VGA signals + +required: + - compatible + - port + +additionalProperties: false + +examples: + - | + connector { + compatible = "vga-connector"; + label = "vga"; + + ddc-i2c-bus = <&i2c3>; + + port { + vga_connector_in: endpoint { + remote-endpoint = <&adv7123_out>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/imx/fsl-imx-drm.txt b/Documentation/devicetree/bindings/display/imx/fsl-imx-drm.txt index 5bf77f6dd19d..5a99490c17b9 100644 --- a/Documentation/devicetree/bindings/display/imx/fsl-imx-drm.txt +++ b/Documentation/devicetree/bindings/display/imx/fsl-imx-drm.txt @@ -68,7 +68,7 @@ Required properties: datasheet - clocks : phandle to the PRE axi clock input, as described in Documentation/devicetree/bindings/clock/clock-bindings.txt and - Documentation/devicetree/bindings/clock/imx6q-clock.txt. + Documentation/devicetree/bindings/clock/imx6q-clock.yaml. - clock-names: should be "axi" - interrupts: should contain the PRE interrupt - fsl,iram: phandle pointing to the mmio-sram device node, that should be @@ -94,7 +94,7 @@ Required properties: datasheet - clocks : phandles to the PRG ipg and axi clock inputs, as described in Documentation/devicetree/bindings/clock/clock-bindings.txt and - Documentation/devicetree/bindings/clock/imx6q-clock.txt. + Documentation/devicetree/bindings/clock/imx6q-clock.yaml. - clock-names: should be "ipg" and "axi" - fsl,pres: phandles to the PRE units attached to this PRG, with the fixed PRE as the first entry and the muxable PREs following. diff --git a/Documentation/devicetree/bindings/display/imx/ldb.txt b/Documentation/devicetree/bindings/display/imx/ldb.txt index 38c637fa39dd..8e6e7d797943 100644 --- a/Documentation/devicetree/bindings/display/imx/ldb.txt +++ b/Documentation/devicetree/bindings/display/imx/ldb.txt @@ -30,8 +30,8 @@ Required properties: "di2_sel" - IPU2 DI0 mux "di3_sel" - IPU2 DI1 mux The needed clock numbers for each are documented in - Documentation/devicetree/bindings/clock/imx5-clock.txt, and in - Documentation/devicetree/bindings/clock/imx6q-clock.txt. + Documentation/devicetree/bindings/clock/imx5-clock.yaml, and in + Documentation/devicetree/bindings/clock/imx6q-clock.yaml. Optional properties: - pinctrl-names : should be "default" on i.MX53, not used on i.MX6q diff --git a/Documentation/devicetree/bindings/display/ingenic,ipu.yaml b/Documentation/devicetree/bindings/display/ingenic,ipu.yaml new file mode 100644 index 000000000000..5bfc33eb32c9 --- /dev/null +++ b/Documentation/devicetree/bindings/display/ingenic,ipu.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/ingenic,ipu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Ingenic SoCs Image Processing Unit (IPU) devicetree bindings + +maintainers: + - Paul Cercueil <paul@crapouillou.net> + +properties: + compatible: + oneOf: + - enum: + - ingenic,jz4725b-ipu + - ingenic,jz4760-ipu + - items: + - const: ingenic,jz4770-ipu + - const: ingenic,jz4760-ipu + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + const: ipu + +patternProperties: + "^ports?$": + description: OF graph bindings (specified in bindings/graph.txt). + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/jz4770-cgu.h> + ipu@13080000 { + compatible = "ingenic,jz4770-ipu", "ingenic,jz4760-ipu"; + reg = <0x13080000 0x800>; + + interrupt-parent = <&intc>; + interrupts = <29>; + + clocks = <&cgu JZ4770_CLK_IPU>; + clock-names = "ipu"; + + port { + ipu_ep: endpoint { + remote-endpoint = <&lcdc_ep>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/ingenic,lcd.txt b/Documentation/devicetree/bindings/display/ingenic,lcd.txt deleted file mode 100644 index 01e3261defb6..000000000000 --- a/Documentation/devicetree/bindings/display/ingenic,lcd.txt +++ /dev/null @@ -1,45 +0,0 @@ -Ingenic JZ47xx LCD driver - -Required properties: -- compatible: one of: - * ingenic,jz4740-lcd - * ingenic,jz4725b-lcd - * ingenic,jz4770-lcd -- reg: LCD registers location and length -- clocks: LCD pixclock and device clock specifiers. - The device clock is only required on the JZ4740. -- clock-names: "lcd_pclk" and "lcd" -- interrupts: Specifies the interrupt line the LCD controller is connected to. - -Example: - -panel { - compatible = "sharp,ls020b1dd01d"; - - backlight = <&backlight>; - power-supply = <&vcc>; - - port { - panel_input: endpoint { - remote-endpoint = <&panel_output>; - }; - }; -}; - - -lcd: lcd-controller@13050000 { - compatible = "ingenic,jz4725b-lcd"; - reg = <0x13050000 0x1000>; - - interrupt-parent = <&intc>; - interrupts = <31>; - - clocks = <&cgu JZ4725B_CLK_LCD>; - clock-names = "lcd"; - - port { - panel_output: endpoint { - remote-endpoint = <&panel_input>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/display/ingenic,lcd.yaml b/Documentation/devicetree/bindings/display/ingenic,lcd.yaml new file mode 100644 index 000000000000..d56db1802fad --- /dev/null +++ b/Documentation/devicetree/bindings/display/ingenic,lcd.yaml @@ -0,0 +1,126 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/ingenic,lcd.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Ingenic SoCs LCD controller devicetree bindings + +maintainers: + - Paul Cercueil <paul@crapouillou.net> + +properties: + $nodename: + pattern: "^lcd-controller@[0-9a-f]+$" + + compatible: + enum: + - ingenic,jz4740-lcd + - ingenic,jz4725b-lcd + - ingenic,jz4770-lcd + - ingenic,jz4780-lcd + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: Pixel clock + - description: Module clock + minItems: 1 + + clock-names: + items: + - const: lcd_pclk + - const: lcd + minItems: 1 + + port: + description: OF graph bindings (specified in bindings/graph.txt). + + ports: + description: OF graph bindings (specified in bindings/graph.txt). + type: object + properties: + port@0: + type: object + description: DPI output, to interface with TFT panels. + + port@8: + type: object + description: Link to the Image Processing Unit (IPU). + (See ingenic,ipu.yaml). + + required: + - port@0 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +if: + properties: + compatible: + contains: + enum: + - ingenic,jz4740-lcd + - ingenic,jz4780-lcd +then: + properties: + clocks: + minItems: 2 + clock-names: + minItems: 2 +else: + properties: + clocks: + maxItems: 1 + clock-names: + maxItems: 1 + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/jz4740-cgu.h> + lcd-controller@13050000 { + compatible = "ingenic,jz4740-lcd"; + reg = <0x13050000 0x1000>; + + interrupt-parent = <&intc>; + interrupts = <30>; + + clocks = <&cgu JZ4740_CLK_LCD_PCLK>, <&cgu JZ4740_CLK_LCD>; + clock-names = "lcd_pclk", "lcd"; + + port { + endpoint { + remote-endpoint = <&panel_input>; + }; + }; + }; + + - | + #include <dt-bindings/clock/jz4725b-cgu.h> + lcd-controller@13050000 { + compatible = "ingenic,jz4725b-lcd"; + reg = <0x13050000 0x1000>; + + interrupt-parent = <&intc>; + interrupts = <31>; + + clocks = <&cgu JZ4725B_CLK_LCD>; + clock-names = "lcd_pclk"; + + port { + endpoint { + remote-endpoint = <&panel_input>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/msm/dsi.txt b/Documentation/devicetree/bindings/display/msm/dsi.txt index af95586c898f..7884fd7a85c1 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi.txt +++ b/Documentation/devicetree/bindings/display/msm/dsi.txt @@ -87,6 +87,7 @@ Required properties: * "qcom,dsi-phy-20nm" * "qcom,dsi-phy-28nm-8960" * "qcom,dsi-phy-14nm" + * "qcom,dsi-phy-14nm-660" * "qcom,dsi-phy-10nm" * "qcom,dsi-phy-10nm-8998" - reg: Physical base address and length of the registers of PLL, PHY. Some diff --git a/Documentation/devicetree/bindings/display/msm/gpu.txt b/Documentation/devicetree/bindings/display/msm/gpu.txt index fd779cd6994d..1af0ff102b50 100644 --- a/Documentation/devicetree/bindings/display/msm/gpu.txt +++ b/Documentation/devicetree/bindings/display/msm/gpu.txt @@ -112,6 +112,34 @@ Example a6xx (with GMU): interconnects = <&rsc_hlos MASTER_GFX3D &rsc_hlos SLAVE_EBI1>; interconnect-names = "gfx-mem"; + gpu_opp_table: opp-table { + compatible = "operating-points-v2"; + + opp-430000000 { + opp-hz = /bits/ 64 <430000000>; + opp-level = <RPMH_REGULATOR_LEVEL_SVS_L1>; + opp-peak-kBps = <5412000>; + }; + + opp-355000000 { + opp-hz = /bits/ 64 <355000000>; + opp-level = <RPMH_REGULATOR_LEVEL_SVS>; + opp-peak-kBps = <3072000>; + }; + + opp-267000000 { + opp-hz = /bits/ 64 <267000000>; + opp-level = <RPMH_REGULATOR_LEVEL_LOW_SVS>; + opp-peak-kBps = <3072000>; + }; + + opp-180000000 { + opp-hz = /bits/ 64 <180000000>; + opp-level = <RPMH_REGULATOR_LEVEL_MIN_SVS>; + opp-peak-kBps = <1804000>; + }; + }; + qcom,gmu = <&gmu>; zap-shader { diff --git a/Documentation/devicetree/bindings/display/panel/arm,versatile-tft-panel.yaml b/Documentation/devicetree/bindings/display/panel/arm,versatile-tft-panel.yaml index 41fd5713c156..be69e0cc50fc 100644 --- a/Documentation/devicetree/bindings/display/panel/arm,versatile-tft-panel.yaml +++ b/Documentation/devicetree/bindings/display/panel/arm,versatile-tft-panel.yaml @@ -33,7 +33,7 @@ additionalProperties: false examples: - | - sysreg { + sysreg@0 { compatible = "arm,versatile-sysreg", "syscon", "simple-mfd"; reg = <0x00000 0x1000>; diff --git a/Documentation/devicetree/bindings/display/panel/innolux,p079zca.txt b/Documentation/devicetree/bindings/display/panel/innolux,p079zca.txt deleted file mode 100644 index 3ab8c7412cf6..000000000000 --- a/Documentation/devicetree/bindings/display/panel/innolux,p079zca.txt +++ /dev/null @@ -1,22 +0,0 @@ -Innolux P079ZCA 7.85" 768x1024 TFT LCD panel - -Required properties: -- compatible: should be "innolux,p079zca" -- reg: DSI virtual channel of the peripheral -- power-supply: phandle of the regulator that provides the supply voltage -- enable-gpios: panel enable gpio - -Optional properties: -- backlight: phandle of the backlight device attached to the panel - -Example: - - &mipi_dsi { - panel@0 { - compatible = "innolux,p079zca"; - reg = <0>; - power-supply = <...>; - backlight = <&backlight>; - enable-gpios = <&gpio1 13 GPIO_ACTIVE_HIGH>; - }; - }; diff --git a/Documentation/devicetree/bindings/display/panel/panel-dsi-cm.txt b/Documentation/devicetree/bindings/display/panel/panel-dsi-cm.txt deleted file mode 100644 index dce48eb9db57..000000000000 --- a/Documentation/devicetree/bindings/display/panel/panel-dsi-cm.txt +++ /dev/null @@ -1,29 +0,0 @@ -Generic MIPI DSI Command Mode Panel -=================================== - -Required properties: -- compatible: "panel-dsi-cm" - -Optional properties: -- label: a symbolic name for the panel -- reset-gpios: panel reset gpio -- te-gpios: panel TE gpio - -Required nodes: -- Video port for DSI input - -Example -------- - -lcd0: display { - compatible = "tpo,taal", "panel-dsi-cm"; - label = "lcd0"; - - reset-gpios = <&gpio4 6 GPIO_ACTIVE_HIGH>; - - port { - lcd0_in: endpoint { - remote-endpoint = <&dsi1_out_ep>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/display/panel/panel-dsi-cm.yaml b/Documentation/devicetree/bindings/display/panel/panel-dsi-cm.yaml new file mode 100644 index 000000000000..d766c949c622 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/panel-dsi-cm.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/panel-dsi-cm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: DSI command mode panels + +maintainers: + - Tomi Valkeinen <tomi.valkeinen@ti.com> + - Sebastian Reichel <sre@kernel.org> + +description: | + This binding file is a collection of the DSI panels that + are usually driven in command mode. If no backlight is + referenced via the optional backlight property, the DSI + panel is assumed to have native backlight support. + The panel may use an OF graph binding for the association + to the display, or it may be a direct child node of the + display. + +allOf: + - $ref: panel-common.yaml# + +properties: + + compatible: + items: + - enum: + - motorola,droid4-panel # Panel from Motorola Droid4 phone + - nokia,himalaya # Panel from Nokia N950 phone + - tpo,taal # Panel from OMAP4 SDP board + - const: panel-dsi-cm # Generic DSI command mode panel compatible fallback + + reg: + maxItems: 1 + description: DSI virtual channel + + vddi-supply: + description: + Display panels require power to be supplied. While several panels need + more than one power supply with panel-specific constraints governing the + order and timings of the power supplies, in many cases a single power + supply is sufficient, either because the panel has a single power rail, or + because all its power rails can be driven by the same supply. In that case + the vddi-supply property specifies the supply powering the panel as a + phandle to a regulator. + + vpnl-supply: + description: + When the display panel needs a second power supply, this property can be + used in addition to vddi-supply. Both supplies will be enabled at the + same time before the panel is being accessed. + + width-mm: true + height-mm: true + label: true + rotation: true + panel-timing: true + port: true + reset-gpios: true + te-gpios: true + backlight: true + +additionalProperties: false + +required: + - compatible + - reg + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + dsi-controller { + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "tpo,taal", "panel-dsi-cm"; + reg = <0>; + reset-gpios = <&gpio4 6 GPIO_ACTIVE_HIGH>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml index 16778ce782fc..c0dd9fa29f1d 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple-dsi.yaml @@ -33,6 +33,8 @@ properties: - auo,b080uan01 # Boe Corporation 8.0" WUXGA TFT LCD panel - boe,tv080wum-nl0 + # Innolux P079ZCA 7.85" 768x1024 TFT LCD panel + - innolux,p079zca # Kingdisplay KD097D04 9.7" 1536x2048 TFT LCD panel - kingdisplay,kd097d04 # LG ACX467AKM-7 4.95" 1080×1920 LCD Panel diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml index d6cca1479633..6deeeed59e59 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml @@ -81,6 +81,10 @@ properties: - boe,nv140fhmn49 # CDTech(H.K.) Electronics Limited 4.3" 480x272 color TFT-LCD panel - cdtech,s043wq26h-ct7 + # CDTech(H.K.) Electronics Limited 7" WSVGA (1024x600) TFT LCD Panel + - cdtech,s070pws19hp-fc21 + # CDTech(H.K.) Electronics Limited 7" WVGA (800x480) TFT LCD Panel + - cdtech,s070swv29hg-dc44 # CDTech(H.K.) Electronics Limited 7" 800x480 color TFT-LCD panel - cdtech,s070wv95-ct16 # Chunghwa Picture Tubes Ltd. 7" WXGA TFT LCD panel @@ -157,6 +161,8 @@ properties: - innolux,zj070na-01p # Kaohsiung Opto-Electronics Inc. 5.7" QVGA (320 x 240) TFT LCD panel - koe,tx14d24vm1bpa + # Kaohsiung Opto-Electronics Inc. 10.1" WUXGA (1920 x 1200) LVDS TFT LCD panel + - koe,tx26d202vm0bwa # Kaohsiung Opto-Electronics. TX31D200VM0BAA 12.3" HSXGA LVDS panel - koe,tx31d200vm0baa # Kyocera Corporation 12.1" XGA (1024x768) TFT LCD panel @@ -245,6 +251,8 @@ properties: - starry,kr122ea0sra # Tianma Micro-electronics TM070JDHG30 7.0" WXGA TFT LCD panel - tianma,tm070jdhg30 + # Tianma Micro-electronics TM070JVHG33 7.0" WXGA TFT LCD panel + - tianma,tm070jvhg33 # Tianma Micro-electronics TM070RVHG71 7.0" WXGA TFT LCD panel - tianma,tm070rvhg71 # Toshiba 8.9" WXGA (1280x768) TFT LCD panel diff --git a/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.txt b/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.txt deleted file mode 100644 index a372c5d84695..000000000000 --- a/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.txt +++ /dev/null @@ -1,23 +0,0 @@ -Rocktech jh057n00900 5.5" 720x1440 TFT LCD panel - -Required properties: -- compatible: should be "rocktech,jh057n00900" -- reg: DSI virtual channel of the peripheral -- reset-gpios: panel reset gpio -- backlight: phandle of the backlight device attached to the panel -- vcc-supply: phandle of the regulator that provides the vcc supply voltage. -- iovcc-supply: phandle of the regulator that provides the iovcc supply - voltage. - -Example: - - &mipi_dsi { - panel@0 { - compatible = "rocktech,jh057n00900"; - reg = <0>; - backlight = <&backlight>; - reset-gpios = <&gpio3 13 GPIO_ACTIVE_LOW>; - vcc-supply = <®_2v8_p>; - iovcc-supply = <®_1v8_p>; - }; - }; diff --git a/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.yaml b/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.yaml new file mode 100644 index 000000000000..d5733ef30954 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.yaml @@ -0,0 +1,71 @@ +# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/rocktech,jh057n00900.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rocktech JH057N00900 5.5" 720x1440 TFT LCD panel + +maintainers: + - Ondrej Jirman <megi@xff.cz> + +description: | + Rocktech JH057N00900 is a 720x1440 TFT LCD panel + connected using a MIPI-DSI video interface. + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + enum: + # Rocktech JH057N00900 5.5" 720x1440 TFT LCD panel + - rocktech,jh057n00900 + # Xingbangda XBD599 5.99" 720x1440 TFT LCD panel + - xingbangda,xbd599 + + port: true + reg: + maxItems: 1 + description: DSI virtual channel + + vcc-supply: + description: Panel power supply + + iovcc-supply: + description: I/O voltage supply + + reset-gpios: + description: GPIO used for the reset pin + maxItems: 1 + + backlight: + description: Backlight used by the panel + $ref: "/schemas/types.yaml#/definitions/phandle" + +required: + - compatible + - reg + - vcc-supply + - iovcc-supply + - reset-gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + dsi { + #address-cells = <1>; + #size-cells = <0>; + panel@0 { + compatible = "rocktech,jh057n00900"; + reg = <0>; + vcc-supply = <®_2v8_p>; + iovcc-supply = <®_1v8_p>; + reset-gpios = <&gpio3 13 GPIO_ACTIVE_LOW>; + backlight = <&backlight>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.txt b/Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.txt deleted file mode 100644 index 9e766c5f86da..000000000000 --- a/Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.txt +++ /dev/null @@ -1,56 +0,0 @@ -Samsung S6E8AA0 AMOLED LCD 5.3 inch panel - -Required properties: - - compatible: "samsung,s6e8aa0" - - reg: the virtual channel number of a DSI peripheral - - vdd3-supply: core voltage supply - - vci-supply: voltage supply for analog circuits - - reset-gpios: a GPIO spec for the reset pin - - display-timings: timings for the connected panel as described by [1] - -Optional properties: - - power-on-delay: delay after turning regulators on [ms] - - reset-delay: delay after reset sequence [ms] - - init-delay: delay after initialization sequence [ms] - - panel-width-mm: physical panel width [mm] - - panel-height-mm: physical panel height [mm] - - flip-horizontal: boolean to flip image horizontally - - flip-vertical: boolean to flip image vertically - -The device node can contain one 'port' child node with one child -'endpoint' node, according to the bindings defined in [2]. This -node should describe panel's video bus. - -[1]: Documentation/devicetree/bindings/display/panel/display-timing.txt -[2]: Documentation/devicetree/bindings/media/video-interfaces.txt - -Example: - - panel { - compatible = "samsung,s6e8aa0"; - reg = <0>; - vdd3-supply = <&vcclcd_reg>; - vci-supply = <&vlcd_reg>; - reset-gpios = <&gpy4 5 0>; - power-on-delay= <50>; - reset-delay = <100>; - init-delay = <100>; - panel-width-mm = <58>; - panel-height-mm = <103>; - flip-horizontal; - flip-vertical; - - display-timings { - timing0: timing-0 { - clock-frequency = <57153600>; - hactive = <720>; - vactive = <1280>; - hfront-porch = <5>; - hback-porch = <5>; - hsync-len = <5>; - vfront-porch = <13>; - vback-porch = <1>; - vsync-len = <2>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.yaml b/Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.yaml new file mode 100644 index 000000000000..ca959451557e --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.yaml @@ -0,0 +1,100 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/samsung,s6e8aa0.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung S6E8AA0 AMOLED LCD 5.3 inch panel + +maintainers: + - Andrzej Hajda <a.hajda@samsung.com> + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + const: samsung,s6e8aa0 + + reg: true + reset-gpios: true + display-timings: true + + vdd3-supply: + description: core voltage supply + + vci-supply: + description: voltage supply for analog circuits + + power-on-delay: + description: delay after turning regulators on [ms] + $ref: /schemas/types.yaml#/definitions/uint32 + + reset-delay: + description: delay after reset sequence [ms] + $ref: /schemas/types.yaml#/definitions/uint32 + + init-delay: + description: delay after initialization sequence [ms] + + panel-width-mm: + description: physical panel width [mm] + + panel-height-mm: + description: physical panel height [mm] + + flip-horizontal: + description: boolean to flip image horizontally + type: boolean + + flip-vertical: + description: boolean to flip image vertically + type: boolean + +required: + - compatible + - reg + - vdd3-supply + - vci-supply + - reset-gpios + - display-timings + +additionalProperties: false + +examples: + - | + dsi { + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "samsung,s6e8aa0"; + reg = <0>; + vdd3-supply = <&vcclcd_reg>; + vci-supply = <&vlcd_reg>; + reset-gpios = <&gpy4 5 0>; + power-on-delay= <50>; + reset-delay = <100>; + init-delay = <100>; + panel-width-mm = <58>; + panel-height-mm = <103>; + flip-horizontal; + flip-vertical; + + display-timings { + timing0: timing-0 { + clock-frequency = <57153600>; + hactive = <720>; + vactive = <1280>; + hfront-porch = <5>; + hback-porch = <5>; + hsync-len = <5>; + vfront-porch = <13>; + vback-porch = <1>; + vsync-len = <2>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/panel/sharp,lq101r1sx01.txt b/Documentation/devicetree/bindings/display/panel/sharp,lq101r1sx01.txt deleted file mode 100644 index f522bb8e47e1..000000000000 --- a/Documentation/devicetree/bindings/display/panel/sharp,lq101r1sx01.txt +++ /dev/null @@ -1,49 +0,0 @@ -Sharp Microelectronics 10.1" WQXGA TFT LCD panel - -This panel requires a dual-channel DSI host to operate. It supports two modes: -- left-right: each channel drives the left or right half of the screen -- even-odd: each channel drives the even or odd lines of the screen - -Each of the DSI channels controls a separate DSI peripheral. The peripheral -driven by the first link (DSI-LINK1), left or even, is considered the primary -peripheral and controls the device. The 'link2' property contains a phandle -to the peripheral driven by the second link (DSI-LINK2, right or odd). - -Note that in video mode the DSI-LINK1 interface always provides the left/even -pixels and DSI-LINK2 always provides the right/odd pixels. In command mode it -is possible to program either link to drive the left/even or right/odd pixels -but for the sake of consistency this binding assumes that the same assignment -is chosen as for video mode. - -Required properties: -- compatible: should be "sharp,lq101r1sx01" -- reg: DSI virtual channel of the peripheral - -Required properties (for DSI-LINK1 only): -- link2: phandle to the DSI peripheral on the secondary link. Note that the - presence of this property marks the containing node as DSI-LINK1. -- power-supply: phandle of the regulator that provides the supply voltage - -Optional properties (for DSI-LINK1 only): -- backlight: phandle of the backlight device attached to the panel - -Example: - - dsi@54300000 { - panel: panel@0 { - compatible = "sharp,lq101r1sx01"; - reg = <0>; - - link2 = <&secondary>; - - power-supply = <...>; - backlight = <...>; - }; - }; - - dsi@54400000 { - secondary: panel@0 { - compatible = "sharp,lq101r1sx01"; - reg = <0>; - }; - }; diff --git a/Documentation/devicetree/bindings/display/panel/sharp,lq101r1sx01.yaml b/Documentation/devicetree/bindings/display/panel/sharp,lq101r1sx01.yaml new file mode 100644 index 000000000000..a679d3647dbd --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/sharp,lq101r1sx01.yaml @@ -0,0 +1,87 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/sharp,lq101r1sx01.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sharp Microelectronics 10.1" WQXGA TFT LCD panel + +maintainers: + - Thierry Reding <treding@nvidia.com> + +description: | + This panel requires a dual-channel DSI host to operate. It supports two modes: + - left-right: each channel drives the left or right half of the screen + - even-odd: each channel drives the even or odd lines of the screen + + Each of the DSI channels controls a separate DSI peripheral. The peripheral + driven by the first link (DSI-LINK1), left or even, is considered the primary + peripheral and controls the device. The 'link2' property contains a phandle + to the peripheral driven by the second link (DSI-LINK2, right or odd). + + Note that in video mode the DSI-LINK1 interface always provides the left/even + pixels and DSI-LINK2 always provides the right/odd pixels. In command mode it + is possible to program either link to drive the left/even or right/odd pixels + but for the sake of consistency this binding assumes that the same assignment + is chosen as for video mode. + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + const: sharp,lq101r1sx01 + + reg: true + power-supply: true + backlight: true + + link2: + $ref: /schemas/types.yaml#/definitions/phandle + description: | + phandle to the DSI peripheral on the secondary link. Note that the + presence of this property marks the containing node as DSI-LINK1 + +required: + - compatible + - reg + +if: + required: + - link2 +then: + required: + - power-supply + +additionalProperties: false + +examples: + - | + dsi0: dsi@fd922800 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0xfd922800 0x200>; + + panel: panel@0 { + compatible = "sharp,lq101r1sx01"; + reg = <0>; + + link2 = <&secondary>; + + power-supply = <&power>; + backlight = <&backlight>; + }; + }; + + dsi1: dsi@fd922a00 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0xfd922a00 0x200>; + + secondary: panel@0 { + compatible = "sharp,lq101r1sx01"; + reg = <0>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/rockchip/rockchip-drm.yaml b/Documentation/devicetree/bindings/display/rockchip/rockchip-drm.yaml index ec8ae742d4da..7204da5eb4c5 100644 --- a/Documentation/devicetree/bindings/display/rockchip/rockchip-drm.yaml +++ b/Documentation/devicetree/bindings/display/rockchip/rockchip-drm.yaml @@ -24,7 +24,7 @@ properties: description: | Should contain a list of phandles pointing to display interface port of vop devices. vop definitions as defined in - Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt + Documentation/devicetree/bindings/display/rockchip/rockchip-vop.yaml required: - compatible diff --git a/Documentation/devicetree/bindings/display/simple-framebuffer.yaml b/Documentation/devicetree/bindings/display/simple-framebuffer.yaml index 1db608c9eef5..eaf8c54fcf50 100644 --- a/Documentation/devicetree/bindings/display/simple-framebuffer.yaml +++ b/Documentation/devicetree/bindings/display/simple-framebuffer.yaml @@ -152,28 +152,28 @@ additionalProperties: false examples: - | - aliases { - display0 = &lcdc0; + / { + compatible = "foo"; + model = "foo"; + #address-cells = <1>; + #size-cells = <1>; + + chosen { + #address-cells = <1>; + #size-cells = <1>; + framebuffer0: framebuffer@1d385000 { + compatible = "allwinner,simple-framebuffer", "simple-framebuffer"; + allwinner,pipeline = "de_be0-lcd0"; + reg = <0x1d385000 3840000>; + width = <1600>; + height = <1200>; + stride = <3200>; + format = "r5g6b5"; + clocks = <&ahb_gates 36>, <&ahb_gates 43>, <&ahb_gates 44>; + lcd-supply = <®_dc1sw>; + display = <&lcdc0>; + }; + }; }; - chosen { - #address-cells = <1>; - #size-cells = <1>; - stdout-path = "display0"; - framebuffer0: framebuffer@1d385000 { - compatible = "allwinner,simple-framebuffer", "simple-framebuffer"; - allwinner,pipeline = "de_be0-lcd0"; - reg = <0x1d385000 3840000>; - width = <1600>; - height = <1200>; - stride = <3200>; - format = "r5g6b5"; - clocks = <&ahb_gates 36>, <&ahb_gates 43>, <&ahb_gates 44>; - lcd-supply = <®_dc1sw>; - display = <&lcdc0>; - }; - }; - - lcdc0: lcdc { }; - ... diff --git a/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt b/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt index aac617acb64f..8b2a71395647 100644 --- a/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt +++ b/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt @@ -46,7 +46,7 @@ Optional nodes: crossed and LCD_DATA[0:4] is for Red[3:7] and LCD_DATA[11:15] is for Blue[3-7]. For more details see section 3.1.1 in AM335x Silicon Errata: - http://www.ti.com/general/docs/lit/getliterature.tsp?baseLiteratureNumber=sprz360 + https://www.ti.com/general/docs/lit/getliterature.tsp?baseLiteratureNumber=sprz360 Example: diff --git a/Documentation/devicetree/bindings/display/xlnx/xlnx,zynqmp-dpsub.yaml b/Documentation/devicetree/bindings/display/xlnx/xlnx,zynqmp-dpsub.yaml new file mode 100644 index 000000000000..52a939cade3b --- /dev/null +++ b/Documentation/devicetree/bindings/display/xlnx/xlnx,zynqmp-dpsub.yaml @@ -0,0 +1,174 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/xlnx/xlnx,zynqmp-dpsub.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx ZynqMP DisplayPort Subsystem + +description: | + The DisplayPort subsystem of Xilinx ZynqMP (Zynq UltraScale+ MPSoC) + implements the display and audio pipelines based on the DisplayPort v1.2 + standard. The subsystem includes multiple functional blocks as below: + + +------------------------------------------------------------+ + +--------+ | +----------------+ +-----------+ | + | DPDMA | --->| | --> | Video | Video +-------------+ | + | 4x vid | | | | | Rendering | -+--> | | | +------+ + | 2x aud | | | Audio/Video | --> | Pipeline | | | DisplayPort |---> | PHY0 | + +--------+ | | Buffer Manager | +-----------+ | | Source | | +------+ + | | and STC | +-----------+ | | Controller | | +------+ + Live Video --->| | --> | Audio | Audio | |---> | PHY1 | + | | | | Mixer | --+-> | | | +------+ + Live Audio --->| | --> | | || +-------------+ | + | +----------------+ +-----------+ || | + +---------------------------------------||-------------------+ + vv + Blended Video and + Mixed Audio to PL + + The Buffer Manager interacts with external interface such as DMA engines or + live audio/video streams from the programmable logic. The Video Rendering + Pipeline blends the video and graphics layers and performs colorspace + conversion. The Audio Mixer mixes the incoming audio streams. The DisplayPort + Source Controller handles the DisplayPort protocol and connects to external + PHYs. + + The subsystem supports 2 video and 2 audio streams, and various pixel formats + and depths up to 4K@30 resolution. + + Please refer to "Zynq UltraScale+ Device Technical Reference Manual" + (https://www.xilinx.com/support/documentation/user_guides/ug1085-zynq-ultrascale-trm.pdf) + for more details. + +maintainers: + - Laurent Pinchart <laurent.pinchart@ideasonboard.com> + +properties: + compatible: + const: xlnx,zynqmp-dpsub-1.7 + + reg: + maxItems: 4 + reg-names: + items: + - const: dp + - const: blend + - const: av_buf + - const: aud + + interrupts: + maxItems: 1 + + clocks: + description: + The APB clock and at least one video clock are mandatory, the audio clock + is optional. + minItems: 2 + maxItems: 4 + items: + - description: dp_apb_clk is the APB clock + - description: dp_aud_clk is the Audio clock + - description: + dp_vtc_pixel_clk_in is the non-live video clock (from Processing + System) + - description: + dp_live_video_in_clk is the live video clock (from Programmable + Logic) + clock-names: + oneOf: + - minItems: 2 + maxItems: 3 + items: + - const: dp_apb_clk + - enum: [ dp_vtc_pixel_clk_in, dp_live_video_in_clk ] + - enum: [ dp_vtc_pixel_clk_in, dp_live_video_in_clk ] + - minItems: 3 + maxItems: 4 + items: + - const: dp_apb_clk + - const: dp_aud_clk + - enum: [ dp_vtc_pixel_clk_in, dp_live_video_in_clk ] + - enum: [ dp_vtc_pixel_clk_in, dp_live_video_in_clk ] + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + + dmas: + maxItems: 4 + items: + - description: Video layer, plane 0 (RGB or luma) + - description: Video layer, plane 1 (U/V or U) + - description: Video layer, plane 2 (V) + - description: Graphics layer + dma-names: + items: + - const: vid0 + - const: vid1 + - const: vid2 + - const: gfx0 + + phys: + description: PHYs for the DP data lanes + minItems: 1 + maxItems: 2 + phy-names: + minItems: 1 + maxItems: 2 + items: + - const: dp-phy0 + - const: dp-phy1 + +required: + - compatible + - reg + - reg-names + - interrupts + - clocks + - clock-names + - power-domains + - resets + - dmas + - dma-names + - phys + - phy-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/phy/phy.h> + #include <dt-bindings/reset/xlnx-zynqmp-resets.h> + + display@fd4a0000 { + compatible = "xlnx,zynqmp-dpsub-1.7"; + reg = <0x0 0xfd4a0000 0x0 0x1000>, + <0x0 0xfd4aa000 0x0 0x1000>, + <0x0 0xfd4ab000 0x0 0x1000>, + <0x0 0xfd4ac000 0x0 0x1000>; + reg-names = "dp", "blend", "av_buf", "aud"; + interrupts = <0 119 4>; + interrupt-parent = <&gic>; + + clock-names = "dp_apb_clk", "dp_aud_clk", "dp_live_video_in_clk"; + clocks = <&dp_aclk>, <&clkc 17>, <&si570_1>; + + power-domains = <&pd_dp>; + resets = <&reset ZYNQMP_RESET_DP>; + + dma-names = "vid0", "vid1", "vid2", "gfx0"; + dmas = <&xlnx_dpdma 0>, + <&xlnx_dpdma 1>, + <&xlnx_dpdma 2>, + <&xlnx_dpdma 3>; + + phys = <&psgtr 1 PHY_TYPE_DP 0 3 27000000>, + <&psgtr 0 PHY_TYPE_DP 1 3 27000000>; + + phy-names = "dp-phy0", "dp-phy1"; + }; + +... diff --git a/Documentation/devicetree/bindings/dma/arm-pl330.txt b/Documentation/devicetree/bindings/dma/arm-pl330.txt index 2c7fd1941abb..315e90122afa 100644 --- a/Documentation/devicetree/bindings/dma/arm-pl330.txt +++ b/Documentation/devicetree/bindings/dma/arm-pl330.txt @@ -16,6 +16,7 @@ Optional properties: - dma-channels: contains the total number of DMA channels supported by the DMAC - dma-requests: contains the total number of DMA requests supported by the DMAC - arm,pl330-broken-no-flushp: quirk for avoiding to execute DMAFLUSHP + - arm,pl330-periph-burst: quirk for performing burst transfer only - resets: contains an entry for each entry in reset-names. See ../reset/reset.txt for details. - reset-names: must contain at least "dma", and optional is "dma-ocp". diff --git a/Documentation/devicetree/bindings/dma/owl-dma.txt b/Documentation/devicetree/bindings/dma/owl-dma.txt deleted file mode 100644 index 03e9bb12b75f..000000000000 --- a/Documentation/devicetree/bindings/dma/owl-dma.txt +++ /dev/null @@ -1,47 +0,0 @@ -* Actions Semi Owl SoCs DMA controller - -This binding follows the generic DMA bindings defined in dma.txt. - -Required properties: -- compatible: Should be "actions,s900-dma". -- reg: Should contain DMA registers location and length. -- interrupts: Should contain 4 interrupts shared by all channel. -- #dma-cells: Must be <1>. Used to represent the number of integer - cells in the dmas property of client device. -- dma-channels: Physical channels supported. -- dma-requests: Number of DMA request signals supported by the controller. - Refer to Documentation/devicetree/bindings/dma/dma.txt -- clocks: Phandle and Specifier of the clock feeding the DMA controller. - -Example: - -Controller: - dma: dma-controller@e0260000 { - compatible = "actions,s900-dma"; - reg = <0x0 0xe0260000 0x0 0x1000>; - interrupts = <GIC_SPI 57 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 58 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 59 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 60 IRQ_TYPE_LEVEL_HIGH>; - #dma-cells = <1>; - dma-channels = <12>; - dma-requests = <46>; - clocks = <&clock CLK_DMAC>; - }; - -Client: - -DMA clients connected to the Actions Semi Owl SoCs DMA controller must -use the format described in the dma.txt file, using a two-cell specifier -for each channel. - -The two cells in order are: -1. A phandle pointing to the DMA controller. -2. The channel id. - -uart5: serial@e012a000 { - ... - dma-names = "tx", "rx"; - dmas = <&dma 26>, <&dma 27>; - ... -}; diff --git a/Documentation/devicetree/bindings/dma/owl-dma.yaml b/Documentation/devicetree/bindings/dma/owl-dma.yaml new file mode 100644 index 000000000000..256d62af2c64 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/owl-dma.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/owl-dma.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Actions Semi Owl SoCs DMA controller + +description: | + The OWL DMA is a general-purpose direct memory access controller capable of + supporting 10 and 12 independent DMA channels for S700 and S900 SoCs + respectively. + +maintainers: + - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org> + +allOf: + - $ref: "dma-controller.yaml#" + +properties: + compatible: + enum: + - actions,s900-dma + - actions,s700-dma + + reg: + maxItems: 1 + + interrupts: + description: + controller supports 4 interrupts, which are freely assignable to the + DMA channels. + maxItems: 4 + + "#dma-cells": + const: 1 + + dma-channels: + maximum: 12 + + dma-requests: + maximum: 46 + + clocks: + maxItems: 1 + description: + Phandle and Specifier of the clock feeding the DMA controller. + + power-domains: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - "#dma-cells" + - dma-channels + - dma-requests + - clocks + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + dma: dma-controller@e0260000 { + compatible = "actions,s900-dma"; + reg = <0xe0260000 0x1000>; + interrupts = <GIC_SPI 57 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 58 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 59 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 60 IRQ_TYPE_LEVEL_HIGH>; + #dma-cells = <1>; + dma-channels = <12>; + dma-requests = <46>; + clocks = <&clock 22>; + }; + +... diff --git a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml index b842dfd96a89..13f1a46be40d 100644 --- a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml +++ b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml @@ -23,6 +23,7 @@ properties: - renesas,dmac-r8a774a1 # RZ/G2M - renesas,dmac-r8a774b1 # RZ/G2N - renesas,dmac-r8a774c0 # RZ/G2E + - renesas,dmac-r8a774e1 # RZ/G2H - renesas,dmac-r8a7790 # R-Car H2 - renesas,dmac-r8a7791 # R-Car M2-W - renesas,dmac-r8a7792 # R-Car V2H diff --git a/Documentation/devicetree/bindings/dma/renesas,usb-dmac.yaml b/Documentation/devicetree/bindings/dma/renesas,usb-dmac.yaml index 9ca6d8ddf232..ab287c652b2c 100644 --- a/Documentation/devicetree/bindings/dma/renesas,usb-dmac.yaml +++ b/Documentation/devicetree/bindings/dma/renesas,usb-dmac.yaml @@ -16,6 +16,7 @@ properties: compatible: items: - enum: + - renesas,r8a7742-usb-dmac # RZ/G1H - renesas,r8a7743-usb-dmac # RZ/G1M - renesas,r8a7744-usb-dmac # RZ/G1N - renesas,r8a7745-usb-dmac # RZ/G1E @@ -23,6 +24,7 @@ properties: - renesas,r8a774a1-usb-dmac # RZ/G2M - renesas,r8a774b1-usb-dmac # RZ/G2N - renesas,r8a774c0-usb-dmac # RZ/G2E + - renesas,r8a774e1-usb-dmac # RZ/G2H - renesas,r8a7790-usb-dmac # R-Car H2 - renesas,r8a7791-usb-dmac # R-Car M2-W - renesas,r8a7793-usb-dmac # R-Car M2-N diff --git a/Documentation/devicetree/bindings/dma/snps,dma-spear1340.yaml b/Documentation/devicetree/bindings/dma/snps,dma-spear1340.yaml new file mode 100644 index 000000000000..20870f5c14dd --- /dev/null +++ b/Documentation/devicetree/bindings/dma/snps,dma-spear1340.yaml @@ -0,0 +1,176 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/snps,dma-spear1340.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Synopsys Designware DMA Controller + +maintainers: + - Viresh Kumar <vireshk@kernel.org> + - Andy Shevchenko <andriy.shevchenko@linux.intel.com> + +allOf: + - $ref: "dma-controller.yaml#" + +properties: + compatible: + const: snps,dma-spear1340 + + "#dma-cells": + const: 3 + description: | + First cell is a phandle pointing to the DMA controller. Second one is + the DMA request line number. Third cell is the memory master identifier + for transfers on dynamically allocated channel. Fourth cell is the + peripheral master identifier for transfers on an allocated channel. + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + description: AHB interface reference clock. + const: hclk + + dma-channels: + description: | + Number of DMA channels supported by the controller. In case if + not specified the driver will try to auto-detect this and + the rest of the optional parameters. + minimum: 1 + maximum: 8 + + dma-requests: + minimum: 1 + maximum: 16 + + dma-masters: + $ref: /schemas/types.yaml#definitions/uint32 + description: | + Number of DMA masters supported by the controller. In case if + not specified the driver will try to auto-detect this and + the rest of the optional parameters. + minimum: 1 + maximum: 4 + + chan_allocation_order: + $ref: /schemas/types.yaml#definitions/uint32 + description: | + DMA channels allocation order specifier. Zero means ascending order + (first free allocated), while one - descending (last free allocated). + default: 0 + enum: [0, 1] + + chan_priority: + $ref: /schemas/types.yaml#definitions/uint32 + description: | + DMA channels priority order. Zero means ascending channels priority + so the very first channel has the highest priority. While 1 means + descending priority (the last channel has the highest priority). + default: 0 + enum: [0, 1] + + block_size: + $ref: /schemas/types.yaml#definitions/uint32 + description: Maximum block size supported by the DMA controller. + enum: [3, 7, 15, 31, 63, 127, 255, 511, 1023, 2047, 4095] + + data-width: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: Data bus width per each DMA master in bytes. + items: + maxItems: 4 + items: + enum: [4, 8, 16, 32] + + data_width: + $ref: /schemas/types.yaml#/definitions/uint32-array + deprecated: true + description: | + Data bus width per each DMA master in (2^n * 8) bits. This property is + deprecated. It' usage is discouraged in favor of data-width one. Moreover + the property incorrectly permits to define data-bus width of 8 and 16 + bits, which is impossible in accordance with DW DMAC IP-core data book. + items: + maxItems: 4 + items: + enum: + - 0 # 8 bits + - 1 # 16 bits + - 2 # 32 bits + - 3 # 64 bits + - 4 # 128 bits + - 5 # 256 bits + default: 0 + + multi-block: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: | + LLP-based multi-block transfer supported by hardware per + each DMA channel. + items: + maxItems: 8 + items: + enum: [0, 1] + default: 1 + + snps,max-burst-len: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: | + Maximum length of the burst transactions supported by the controller. + This property defines the upper limit of the run-time burst setting + (CTLx.SRC_MSIZE/CTLx.DST_MSIZE fields) so the allowed burst length + will be from 1 to max-burst-len words. It's an array property with one + cell per channel in the units determined by the value set in the + CTLx.SRC_TR_WIDTH/CTLx.DST_TR_WIDTH fields (data width). + items: + maxItems: 8 + items: + enum: [4, 8, 16, 32, 64, 128, 256] + default: 256 + + snps,dma-protection-control: + $ref: /schemas/types.yaml#definitions/uint32 + description: | + Bits one-to-one passed to the AHB HPROT[3:1] bus. Each bit setting + indicates the following features: bit 0 - privileged mode, + bit 1 - DMA is bufferable, bit 2 - DMA is cacheable. + default: 0 + minimum: 0 + maximum: 7 + +unevaluatedProperties: false + +required: + - compatible + - "#dma-cells" + - reg + - interrupts + +examples: + - | + dma-controller@fc000000 { + compatible = "snps,dma-spear1340"; + reg = <0xfc000000 0x1000>; + interrupt-parent = <&vic1>; + interrupts = <12>; + + dma-channels = <8>; + dma-requests = <16>; + dma-masters = <4>; + #dma-cells = <3>; + + chan_allocation_order = <1>; + chan_priority = <1>; + block_size = <0xfff>; + data-width = <8 8>; + multi-block = <0 0 0 0 0 0 0 0>; + snps,max-burst-len = <16 16 4 4 4 4 4 4>; + }; +... diff --git a/Documentation/devicetree/bindings/dma/snps-dma.txt b/Documentation/devicetree/bindings/dma/snps-dma.txt deleted file mode 100644 index 0bedceed1963..000000000000 --- a/Documentation/devicetree/bindings/dma/snps-dma.txt +++ /dev/null @@ -1,69 +0,0 @@ -* Synopsys Designware DMA Controller - -Required properties: -- compatible: "snps,dma-spear1340" -- reg: Address range of the DMAC registers -- interrupt: Should contain the DMAC interrupt number -- dma-channels: Number of channels supported by hardware -- dma-requests: Number of DMA request lines supported, up to 16 -- dma-masters: Number of AHB masters supported by the controller -- #dma-cells: must be <3> -- chan_allocation_order: order of allocation of channel, 0 (default): ascending, - 1: descending -- chan_priority: priority of channels. 0 (default): increase from chan 0->n, 1: - increase from chan n->0 -- block_size: Maximum block size supported by the controller -- data-width: Maximum data width supported by hardware per AHB master - (in bytes, power of 2) - - -Deprecated properties: -- data_width: Maximum data width supported by hardware per AHB master - (0 - 8bits, 1 - 16bits, ..., 5 - 256bits) - - -Optional properties: -- multi-block: Multi block transfers supported by hardware. Array property with - one cell per channel. 0: not supported, 1 (default): supported. -- snps,dma-protection-control: AHB HPROT[3:1] protection setting. - The default value is 0 (for non-cacheable, non-buffered, - unprivileged data access). - Refer to include/dt-bindings/dma/dw-dmac.h for possible values. - -Example: - - dmahost: dma@fc000000 { - compatible = "snps,dma-spear1340"; - reg = <0xfc000000 0x1000>; - interrupt-parent = <&vic1>; - interrupts = <12>; - - dma-channels = <8>; - dma-requests = <16>; - dma-masters = <2>; - #dma-cells = <3>; - chan_allocation_order = <1>; - chan_priority = <1>; - block_size = <0xfff>; - data-width = <8 8>; - }; - -DMA clients connected to the Designware DMA controller must use the format -described in the dma.txt file, using a four-cell specifier for each channel. -The four cells in order are: - -1. A phandle pointing to the DMA controller -2. The DMA request line number -3. Memory master for transfers on allocated channel -4. Peripheral master for transfers on allocated channel - -Example: - - serial@e0000000 { - compatible = "arm,pl011", "arm,primecell"; - reg = <0xe0000000 0x1000>; - interrupts = <0 35 0x4>; - dmas = <&dmahost 12 0 1>, - <&dmahost 13 1 0>; - dma-names = "rx", "rx"; - }; diff --git a/Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dpdma.yaml b/Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dpdma.yaml new file mode 100644 index 000000000000..5de510f8c88c --- /dev/null +++ b/Documentation/devicetree/bindings/dma/xilinx/xlnx,zynqmp-dpdma.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/xilinx/xlnx,zynqmp-dpdma.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx ZynqMP DisplayPort DMA Controller Device Tree Bindings + +description: | + These bindings describe the DMA engine included in the Xilinx ZynqMP + DisplayPort Subsystem. The DMA engine supports up to 6 DMA channels (3 + channels for a video stream, 1 channel for a graphics stream, and 2 channels + for an audio stream). + +maintainers: + - Laurent Pinchart <laurent.pinchart@ideasonboard.com> + +allOf: + - $ref: "../dma-controller.yaml#" + +properties: + "#dma-cells": + const: 1 + description: | + The cell is the DMA channel ID (see dt-bindings/dma/xlnx-zynqmp-dpdma.h + for a list of channel IDs). + + compatible: + const: xlnx,zynqmp-dpdma + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + description: The AXI clock + maxItems: 1 + + clock-names: + const: axi_clk + +required: + - "#dma-cells" + - compatible + - reg + - interrupts + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + dma: dma-controller@fd4c0000 { + compatible = "xlnx,zynqmp-dpdma"; + reg = <0x0 0xfd4c0000 0x0 0x1000>; + interrupts = <GIC_SPI 122 IRQ_TYPE_LEVEL_HIGH>; + interrupt-parent = <&gic>; + clocks = <&dpdma_clk>; + clock-names = "axi_clk"; + #dma-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/firmware/qcom,scm.txt b/Documentation/devicetree/bindings/firmware/qcom,scm.txt index 354b448fc0c3..78456437df5f 100644 --- a/Documentation/devicetree/bindings/firmware/qcom,scm.txt +++ b/Documentation/devicetree/bindings/firmware/qcom,scm.txt @@ -11,10 +11,12 @@ Required properties: * "qcom,scm-apq8084" * "qcom,scm-ipq4019" * "qcom,scm-ipq806x" + * "qcom,scm-ipq8074" * "qcom,scm-msm8660" * "qcom,scm-msm8916" * "qcom,scm-msm8960" * "qcom,scm-msm8974" + * "qcom,scm-msm8994" * "qcom,scm-msm8996" * "qcom,scm-msm8998" * "qcom,scm-sc7180" diff --git a/Documentation/devicetree/bindings/fpga/fpga-region.txt b/Documentation/devicetree/bindings/fpga/fpga-region.txt index 8ab19d1d3f9a..e811cf825019 100644 --- a/Documentation/devicetree/bindings/fpga/fpga-region.txt +++ b/Documentation/devicetree/bindings/fpga/fpga-region.txt @@ -493,4 +493,4 @@ FPGA Bridges that exist on the FPGA fabric prior to the partial reconfiguration. -- [1] www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/ug/ug_partrecon.pdf [2] tspace.library.utoronto.ca/bitstream/1807/67932/1/Byma_Stuart_A_201411_MAS_thesis.pdf -[3] http://www.xilinx.com/support/documentation/sw_manuals/xilinx14_1/ug702.pdf +[3] https://www.xilinx.com/support/documentation/sw_manuals/xilinx14_1/ug702.pdf diff --git a/Documentation/devicetree/bindings/fpga/xilinx-slave-serial.txt b/Documentation/devicetree/bindings/fpga/xilinx-slave-serial.txt index cfa4ed42b62f..5ef659c1394d 100644 --- a/Documentation/devicetree/bindings/fpga/xilinx-slave-serial.txt +++ b/Documentation/devicetree/bindings/fpga/xilinx-slave-serial.txt @@ -1,11 +1,14 @@ Xilinx Slave Serial SPI FPGA Manager -Xilinx Spartan-6 FPGAs support a method of loading the bitstream over -what is referred to as "slave serial" interface. +Xilinx Spartan-6 and 7 Series FPGAs support a method of loading the +bitstream over what is referred to as "slave serial" interface. The slave serial link is not technically SPI, and might require extra circuits in order to play nicely with other SPI slaves on the same bus. -See https://www.xilinx.com/support/documentation/user_guides/ug380.pdf +See: +- https://www.xilinx.com/support/documentation/user_guides/ug380.pdf +- https://www.xilinx.com/support/documentation/user_guides/ug470_7Series_Config.pdf +- https://www.xilinx.com/support/documentation/application_notes/xapp583-fpga-configuration.pdf Required properties: - compatible: should contain "xlnx,fpga-slave-serial" @@ -13,6 +16,10 @@ Required properties: - prog_b-gpios: config pin (referred to as PROGRAM_B in the manual) - done-gpios: config status pin (referred to as DONE in the manual) +Optional properties: +- init-b-gpios: initialization status and configuration error pin + (referred to as INIT_B in the manual) + Example for full FPGA configuration: fpga-region0 { @@ -37,7 +44,8 @@ Example for full FPGA configuration: spi-max-frequency = <60000000>; spi-cpha; reg = <0>; - done-gpios = <&gpio0 9 GPIO_ACTIVE_HIGH>; prog_b-gpios = <&gpio0 29 GPIO_ACTIVE_LOW>; + init-b-gpios = <&gpio0 28 GPIO_ACTIVE_LOW>; + done-gpios = <&gpio0 9 GPIO_ACTIVE_HIGH>; }; }; diff --git a/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt b/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt index 41372d441131..2aaf661c04ee 100644 --- a/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt +++ b/Documentation/devicetree/bindings/fuse/nvidia,tegra20-fuse.txt @@ -4,8 +4,9 @@ Required properties: - compatible : For Tegra20, must contain "nvidia,tegra20-efuse". For Tegra30, must contain "nvidia,tegra30-efuse". For Tegra114, must contain "nvidia,tegra114-efuse". For Tegra124, must contain "nvidia,tegra124-efuse". - Otherwise, must contain "nvidia,<chip>-efuse", plus one of the above, where - <chip> is tegra132. + For Tegra132 must contain "nvidia,tegra132-efuse", "nvidia,tegra124-efuse". + For Tegra210 must contain "nvidia,tegra210-efuse". For Tegra186 must contain + "nvidia,tegra186-efuse". For Tegra194 must contain "nvidia,tegra194-efuse". Details: nvidia,tegra20-efuse: Tegra20 requires using APB DMA to read the fuse data due to a hardware bug. Tegra20 also lacks certain information which is diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt index dab537c20def..3126c3817e2a 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt @@ -19,6 +19,7 @@ Required properties: nxp,pca9698 nxp,pcal6416 nxp,pcal6524 + nxp,pcal9535 nxp,pcal9555a maxim,max7310 maxim,max7312 diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca9570.yaml b/Documentation/devicetree/bindings/gpio/gpio-pca9570.yaml new file mode 100644 index 000000000000..338c5312a106 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-pca9570.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/gpio-pca9570.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: PCA9570 I2C GPO expander + +maintainers: + - Sungbo Eo <mans0n@gorani.run> + +properties: + compatible: + enum: + - nxp,pca9570 + + reg: + maxItems: 1 + + gpio-controller: true + + '#gpio-cells': + const: 2 + +required: + - compatible + - reg + - gpio-controller + - "#gpio-cells" + +additionalProperties: false + +examples: + - | + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + gpio@24 { + compatible = "nxp,pca9570"; + reg = <0x24>; + gpio-controller; + #gpio-cells = <2>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/gpio/gpio-zynq.txt b/Documentation/devicetree/bindings/gpio/gpio-zynq.txt index 4fa4eb5507cd..f693e82b4c0f 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-zynq.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-zynq.txt @@ -6,7 +6,9 @@ Required properties: - First cell is the GPIO line number - Second cell is used to specify optional parameters (unused) -- compatible : Should be "xlnx,zynq-gpio-1.0" or "xlnx,zynqmp-gpio-1.0" +- compatible : Should be "xlnx,zynq-gpio-1.0" or + "xlnx,zynqmp-gpio-1.0" or "xlnx,versal-gpio-1.0 + or "xlnx,pmc-gpio-1.0 - clocks : Clock specifier (see clock bindings for details) - gpio-controller : Marks the device node as a GPIO controller. - interrupts : Interrupt specifier (see interrupt bindings for diff --git a/Documentation/devicetree/bindings/gpio/mediatek,mt7621-gpio.txt b/Documentation/devicetree/bindings/gpio/mediatek,mt7621-gpio.txt index ba455589f869..e1c49b660d3a 100644 --- a/Documentation/devicetree/bindings/gpio/mediatek,mt7621-gpio.txt +++ b/Documentation/devicetree/bindings/gpio/mediatek,mt7621-gpio.txt @@ -12,7 +12,7 @@ Required properties for the top level node: Only the GPIO_ACTIVE_HIGH and GPIO_ACTIVE_LOW flags are supported. - #interrupt-cells : Specifies the number of cells needed to encode an interrupt. Should be 2. The first cell defines the interrupt number, - the second encodes the triger flags encoded as described in + the second encodes the trigger flags encoded as described in Documentation/devicetree/bindings/interrupt-controller/interrupts.txt - compatible: - "mediatek,mt7621-gpio" for Mediatek controllers diff --git a/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt b/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt deleted file mode 100644 index 30fd2201b3d4..000000000000 --- a/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt +++ /dev/null @@ -1,48 +0,0 @@ -* Marvell PXA GPIO controller - -Required properties: -- compatible : Should be "intel,pxa25x-gpio", "intel,pxa26x-gpio", - "intel,pxa27x-gpio", "intel,pxa3xx-gpio", - "marvell,pxa93x-gpio", "marvell,mmp-gpio", - "marvell,mmp2-gpio" or marvell,pxa1928-gpio. -- reg : Address and length of the register set for the device -- interrupts : Should be the port interrupt shared by all gpio pins. - There're three gpio interrupts in arch-pxa, and they're gpio0, - gpio1 and gpio_mux. There're only one gpio interrupt in arch-mmp, - gpio_mux. -- interrupt-names : Should be the names of irq resources. Each interrupt - uses its own interrupt name, so there should be as many interrupt names - as referenced interrupts. -- interrupt-controller : Identifies the node as an interrupt controller. -- #interrupt-cells: Specifies the number of cells needed to encode an - interrupt source. -- gpio-controller : Marks the device node as a gpio controller. -- #gpio-cells : Should be two. The first cell is the pin number and - the second cell is used to specify flags. See gpio.txt for possible - values. - -Example for a MMP platform: - - gpio: gpio@d4019000 { - compatible = "marvell,mmp-gpio"; - reg = <0xd4019000 0x1000>; - interrupts = <49>; - interrupt-names = "gpio_mux"; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <1>; - }; - -Example for a PXA3xx platform: - - gpio: gpio@40e00000 { - compatible = "intel,pxa3xx-gpio"; - reg = <0x40e00000 0x10000>; - interrupt-names = "gpio0", "gpio1", "gpio_mux"; - interrupts = <8 9 10>; - gpio-controller; - #gpio-cells = <0x2>; - interrupt-controller; - #interrupt-cells = <0x2>; - }; diff --git a/Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml b/Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml new file mode 100644 index 000000000000..4db3b8a3332c --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml @@ -0,0 +1,173 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/mrvl-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell PXA GPIO controller + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + - Bartosz Golaszewski <bgolaszewski@baylibre.com> + - Rob Herring <robh+dt@kernel.org> + +allOf: + - if: + properties: + compatible: + contains: + enum: + - intel,pxa25x-gpio + - intel,pxa26x-gpio + - intel,pxa27x-gpio + - intel,pxa3xx-gpio + then: + properties: + interrupts: + minItems: 3 + maxItems: 3 + interrupt-names: + items: + - const: gpio0 + - const: gpio1 + - const: gpio_mux + - if: + properties: + compatible: + contains: + enum: + - marvell,mmp-gpio + - marvell,mmp2-gpio + then: + properties: + interrupts: + maxItems: 1 + interrupt-names: + items: + - const: gpio_mux + +properties: + $nodename: + pattern: '^gpio@[0-9a-f]+$' + + compatible: + enum: + - intel,pxa25x-gpio + - intel,pxa26x-gpio + - intel,pxa27x-gpio + - intel,pxa3xx-gpio + - marvell,mmp-gpio + - marvell,mmp2-gpio + - marvell,pxa93x-gpio + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + + ranges: true + + '#address-cells': + const: 1 + + '#size-cells': + const: 1 + + gpio-controller: true + + '#gpio-cells': + const: 2 + + gpio-ranges: + maxItems: 1 + + interrupts: true + + interrupt-names: true + + interrupt-controller: true + + '#interrupt-cells': + const: 2 + +patternProperties: + '^gpio@[0-9a-f]*$': + type: object + properties: + reg: + maxItems: 1 + + required: + - reg + + additionalProperties: false + +required: + - compatible + - '#address-cells' + - '#size-cells' + - reg + - gpio-controller + - '#gpio-cells' + - interrupts + - interrupt-names + - interrupt-controller + - '#interrupt-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/pxa-clock.h> + gpio@40e00000 { + compatible = "intel,pxa3xx-gpio"; + #address-cells = <1>; + #size-cells = <1>; + reg = <0x40e00000 0x10000>; + gpio-controller; + #gpio-cells = <2>; + interrupts = <8>, <9>, <10>; + interrupt-names = "gpio0", "gpio1", "gpio_mux"; + clocks = <&clks CLK_GPIO>; + interrupt-controller; + #interrupt-cells = <2>; + }; + - | + #include <dt-bindings/clock/marvell,pxa910.h> + gpio@d4019000 { + compatible = "marvell,mmp-gpio"; + #address-cells = <1>; + #size-cells = <1>; + reg = <0xd4019000 0x1000>; + gpio-controller; + #gpio-cells = <2>; + interrupts = <49>; + interrupt-names = "gpio_mux"; + clocks = <&soc_clocks PXA910_CLK_GPIO>; + resets = <&soc_clocks PXA910_CLK_GPIO>; + interrupt-controller; + #interrupt-cells = <2>; + ranges; + + gpio@d4019000 { + reg = <0xd4019000 0x4>; + }; + + gpio@d4019004 { + reg = <0xd4019004 0x4>; + }; + + gpio@d4019008 { + reg = <0xd4019008 0x4>; + }; + + gpio@d4019100 { + reg = <0xd4019100 0x4>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/gpu/nvidia,gk20a.txt b/Documentation/devicetree/bindings/gpu/nvidia,gk20a.txt index f32bbba4d3bc..662a3c8a7d29 100644 --- a/Documentation/devicetree/bindings/gpu/nvidia,gk20a.txt +++ b/Documentation/devicetree/bindings/gpu/nvidia,gk20a.txt @@ -6,6 +6,7 @@ Required properties: - nvidia,gk20a - nvidia,gm20b - nvidia,gp10b + - nvidia,gv11b - reg: Physical base address and length of the controller's registers. Must contain two entries: - first entry for bar0 @@ -25,6 +26,9 @@ Required properties: If the compatible string is "nvidia,gm20b", then the following clock is also required: - ref +If the compatible string is "nvidia,gv11b", then the following clock is also +required: + - fuse - resets: Must contain an entry for each entry in reset-names. See ../reset/reset.txt for details. - reset-names: Must include the following entries: @@ -88,3 +92,24 @@ Example for GP10B: power-domains = <&bpmp TEGRA186_POWER_DOMAIN_GPU>; iommus = <&smmu TEGRA186_SID_GPU>; }; + +Example for GV11B: + + gpu@17000000 { + compatible = "nvidia,gv11b"; + reg = <0x17000000 0x10000000>, + <0x18000000 0x10000000>; + interrupts = <GIC_SPI 70 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 71 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "stall", "nonstall"; + clocks = <&bpmp TEGRA194_CLK_GPCCLK>, + <&bpmp TEGRA194_CLK_GPU_PWR>, + <&bpmp TEGRA194_CLK_FUSE>; + clock-names = "gpu", "pwr", "fuse"; + resets = <&bpmp TEGRA194_RESET_GPU>; + reset-names = "gpu"; + dma-coherent; + + power-domains = <&bpmp TEGRA194_POWER_DOMAIN_GPU>; + iommus = <&smmu TEGRA194_SID_GPU>; + }; diff --git a/Documentation/devicetree/bindings/hwmon/gpio-fan.txt b/Documentation/devicetree/bindings/hwmon/gpio-fan.txt index 2becdcfdc840..f4cfa350f6a1 100644 --- a/Documentation/devicetree/bindings/hwmon/gpio-fan.txt +++ b/Documentation/devicetree/bindings/hwmon/gpio-fan.txt @@ -12,7 +12,8 @@ Optional properties: - alarm-gpios: This pin going active indicates something is wrong with the fan, and a udev event will be fired. - #cooling-cells: If used as a cooling device, must be <2> - Also see: Documentation/devicetree/bindings/thermal/thermal.txt + Also see: + Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml min and max states are derived from the speed-map of the fan. Note: At least one the "gpios" or "alarm-gpios" properties must be set. diff --git a/Documentation/devicetree/bindings/hwmon/lm90.txt b/Documentation/devicetree/bindings/hwmon/lm90.txt index c76a7ac47c34..398dcb965751 100644 --- a/Documentation/devicetree/bindings/hwmon/lm90.txt +++ b/Documentation/devicetree/bindings/hwmon/lm90.txt @@ -34,8 +34,8 @@ Optional properties: LM90 "-ALERT" pin output. See interrupt-controller/interrupts.txt for the format. -- #thermal-sensor-cells: should be set to 1. See thermal/thermal.txt for - details. See <include/dt-bindings/thermal/lm90.h> for the +- #thermal-sensor-cells: should be set to 1. See thermal/thermal-sensor.yaml + for details. See <include/dt-bindings/thermal/lm90.h> for the definition of the local, remote and 2nd remote sensor index constants. diff --git a/Documentation/devicetree/bindings/hwmon/microchip,sparx5-temp.yaml b/Documentation/devicetree/bindings/hwmon/microchip,sparx5-temp.yaml new file mode 100644 index 000000000000..76be625d5646 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/microchip,sparx5-temp.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/hwmon/microchip,sparx5-temp.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip Sparx5 Temperature Monitor + +maintainers: + - Lars Povlsen <lars.povlsen@microchip.com> + +description: | + Microchip Sparx5 embedded temperature monitor + +properties: + compatible: + enum: + - microchip,sparx5-temp + + reg: + maxItems: 1 + + clocks: + items: + - description: AHB reference clock + + '#thermal-sensor-cells': + const: 0 + +required: + - compatible + - reg + - clocks + +additionalProperties: false + +examples: + - | + tmon0: tmon@610508110 { + compatible = "microchip,sparx5-temp"; + reg = <0x10508110 0xc>; + #thermal-sensor-cells = <0>; + clocks = <&ahb_clk>; + }; diff --git a/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml b/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml index 90b2fa3f7752..c17e5d3ee3f1 100644 --- a/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml +++ b/Documentation/devicetree/bindings/hwmon/ti,tmp513.yaml @@ -18,8 +18,8 @@ description: | consumption. Datasheets: - http://www.ti.com/lit/gpn/tmp513 - http://www.ti.com/lit/gpn/tmp512 + https://www.ti.com/lit/gpn/tmp513 + https://www.ti.com/lit/gpn/tmp512 properties: diff --git a/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml b/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml index da6129090a8e..78ffcab2428c 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml +++ b/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml @@ -52,15 +52,15 @@ properties: description: sda and scl gpio, alternative for {sda,scl}-gpios i2c-gpio,sda-open-drain: - # Generate a warning if present - not: true + type: boolean + deprecated: true description: this means that something outside of our control has put the GPIO line used for SDA into open drain mode, and that something is not the GPIO chip. It is essentially an inconsistency flag. i2c-gpio,scl-open-drain: - # Generate a warning if present - not: true + type: boolean + deprecated: true description: this means that something outside of our control has put the GPIO line used for SCL into open drain mode, and that something is not the GPIO chip. It is essentially an inconsistency flag. diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt deleted file mode 100644 index f0c072ff9eca..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt +++ /dev/null @@ -1,20 +0,0 @@ -* Freescale Low Power Inter IC (LPI2C) for i.MX - -Required properties: -- compatible : - - "fsl,imx7ulp-lpi2c" for LPI2C compatible with the one integrated on i.MX7ULP soc - - "fsl,imx8qxp-lpi2c" for LPI2C compatible with the one integrated on i.MX8QXP soc - - "fsl,imx8qm-lpi2c" for LPI2C compatible with the one integrated on i.MX8QM soc -- reg : address and length of the lpi2c master registers -- interrupts : lpi2c interrupt -- clocks : lpi2c clock specifier - -Examples: - -lpi2c7: lpi2c7@40a50000 { - compatible = "fsl,imx7ulp-lpi2c"; - reg = <0x40A50000 0x10000>; - interrupt-parent = <&intc>; - interrupts = <GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clks IMX7ULP_CLK_LPI2C7>; -}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml new file mode 100644 index 000000000000..ac0bc5dd64d6 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/i2c-imx-lpi2c.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale Low Power Inter IC (LPI2C) for i.MX + +maintainers: + - Anson Huang <Anson.Huang@nxp.com> + +properties: + compatible: + enum: + - fsl,imx7ulp-lpi2c + - fsl,imx8qxp-lpi2c + - fsl,imx8qm-lpi2c + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imx7ulp-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + lpi2c7@40a50000 { + compatible = "fsl,imx7ulp-lpi2c"; + reg = <0x40A50000 0x10000>; + interrupt-parent = <&intc>; + interrupts = <GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clks IMX7ULP_CLK_LPI2C7>; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx.txt b/Documentation/devicetree/bindings/i2c/i2c-imx.txt deleted file mode 100644 index b967544590e8..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-imx.txt +++ /dev/null @@ -1,49 +0,0 @@ -* Freescale Inter IC (I2C) and High Speed Inter IC (HS-I2C) for i.MX - -Required properties: -- compatible : - - "fsl,imx1-i2c" for I2C compatible with the one integrated on i.MX1 SoC - - "fsl,imx21-i2c" for I2C compatible with the one integrated on i.MX21 SoC - - "fsl,vf610-i2c" for I2C compatible with the one integrated on Vybrid vf610 SoC -- reg : Should contain I2C/HS-I2C registers location and length -- interrupts : Should contain I2C/HS-I2C interrupt -- clocks : Should contain the I2C/HS-I2C clock specifier - -Optional properties: -- clock-frequency : Constains desired I2C/HS-I2C bus clock frequency in Hz. - The absence of the property indicates the default frequency 100 kHz. -- dmas: A list of two dma specifiers, one for each entry in dma-names. -- dma-names: should contain "tx" and "rx". -- scl-gpios: specify the gpio related to SCL pin -- sda-gpios: specify the gpio related to SDA pin -- pinctrl: add extra pinctrl to configure i2c pins to gpio function for i2c - bus recovery, call it "gpio" state - -Examples: - -i2c@83fc4000 { /* I2C2 on i.MX51 */ - compatible = "fsl,imx51-i2c", "fsl,imx21-i2c"; - reg = <0x83fc4000 0x4000>; - interrupts = <63>; -}; - -i2c@70038000 { /* HS-I2C on i.MX51 */ - compatible = "fsl,imx51-i2c", "fsl,imx21-i2c"; - reg = <0x70038000 0x4000>; - interrupts = <64>; - clock-frequency = <400000>; -}; - -i2c0: i2c@40066000 { /* i2c0 on vf610 */ - compatible = "fsl,vf610-i2c"; - reg = <0x40066000 0x1000>; - interrupts =<0 71 0x04>; - dmas = <&edma0 0 50>, - <&edma0 0 51>; - dma-names = "rx","tx"; - pinctrl-names = "default", "gpio"; - pinctrl-0 = <&pinctrl_i2c1>; - pinctrl-1 = <&pinctrl_i2c1_gpio>; - scl-gpios = <&gpio5 26 GPIO_ACTIVE_HIGH>; - sda-gpios = <&gpio5 27 GPIO_ACTIVE_HIGH>; -}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx.yaml b/Documentation/devicetree/bindings/i2c/i2c-imx.yaml new file mode 100644 index 000000000000..869f2ae3d5b3 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-imx.yaml @@ -0,0 +1,103 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/i2c-imx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale Inter IC (I2C) and High Speed Inter IC (HS-I2C) for i.MX + +maintainers: + - Wolfram Sang <wolfram@the-dreams.de> + +properties: + compatible: + oneOf: + - const: fsl,imx1-i2c + - const: fsl,imx21-i2c + - const: fsl,vf610-i2c + - items: + - const: fsl,imx35-i2c + - const: fsl,imx1-i2c + - items: + - enum: + - fsl,imx25-i2c + - fsl,imx27-i2c + - fsl,imx31-i2c + - fsl,imx50-i2c + - fsl,imx51-i2c + - fsl,imx53-i2c + - fsl,imx6q-i2c + - fsl,imx6sl-i2c + - fsl,imx6sx-i2c + - fsl,imx6sll-i2c + - fsl,imx6ul-i2c + - fsl,imx7s-i2c + - fsl,imx8mq-i2c + - fsl,imx8mm-i2c + - fsl,imx8mn-i2c + - fsl,imx8mp-i2c + - const: fsl,imx21-i2c + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + const: ipg + + clock-frequency: + enum: [ 100000, 400000 ] + + dmas: + items: + - description: DMA controller phandle and request line for RX + - description: DMA controller phandle and request line for TX + + dma-names: + items: + - const: rx + - const: tx + + sda-gpios: + maxItems: 1 + + scl-gpios: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imx5-clock.h> + #include <dt-bindings/clock/vf610-clock.h> + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + i2c@83fc4000 { + compatible = "fsl,imx51-i2c", "fsl,imx21-i2c"; + reg = <0x83fc4000 0x4000>; + interrupts = <63>; + clocks = <&clks IMX5_CLK_I2C2_GATE>; + }; + + i2c@40066000 { + compatible = "fsl,vf610-i2c"; + reg = <0x40066000 0x1000>; + interrupts = <71 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clks VF610_CLK_I2C0>; + clock-names = "ipg"; + dmas = <&edma0 0 50>, + <&edma0 0 51>; + dma-names = "rx", "tx"; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-mxs.txt b/Documentation/devicetree/bindings/i2c/i2c-mxs.txt deleted file mode 100644 index 4e1c8ac01eba..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-mxs.txt +++ /dev/null @@ -1,25 +0,0 @@ -* Freescale MXS Inter IC (I2C) Controller - -Required properties: -- compatible: Should be "fsl,<chip>-i2c" -- reg: Should contain registers location and length -- interrupts: Should contain ERROR interrupt number -- clock-frequency: Desired I2C bus clock frequency in Hz. - Only 100000Hz and 400000Hz modes are supported. -- dmas: DMA specifier, consisting of a phandle to DMA controller node - and I2C DMA channel ID. - Refer to dma.txt and fsl-mxs-dma.txt for details. -- dma-names: Must be "rx-tx". - -Examples: - -i2c0: i2c@80058000 { - #address-cells = <1>; - #size-cells = <0>; - compatible = "fsl,imx28-i2c"; - reg = <0x80058000 2000>; - interrupts = <111>; - clock-frequency = <100000>; - dmas = <&dma_apbx 6>; - dma-names = "rx-tx"; -}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-mxs.yaml b/Documentation/devicetree/bindings/i2c/i2c-mxs.yaml new file mode 100644 index 000000000000..d3134ed775fa --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-mxs.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/i2c-mxs.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale MXS Inter IC (I2C) Controller + +maintainers: + - Shawn Guo <shawn.guo@linaro.org> + +properties: + compatible: + enum: + - fsl,imx23-i2c + - fsl,imx28-i2c + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clock-frequency: + enum: [ 100000, 400000 ] + + dmas: + maxItems: 1 + + dma-names: + const: rx-tx + +required: + - compatible + - reg + - interrupts + - dmas + - dma-names + +additionalProperties: false + +examples: + - | + i2c@80058000 { + compatible = "fsl,imx28-i2c"; + reg = <0x80058000 2000>; + interrupts = <111>; + clock-frequency = <100000>; + dmas = <&dma_apbx 6>; + dma-names = "rx-tx"; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-pxa.txt b/Documentation/devicetree/bindings/i2c/i2c-pxa.txt deleted file mode 100644 index c30783c0eca0..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-pxa.txt +++ /dev/null @@ -1,31 +0,0 @@ -* Marvell MMP I2C controller - -Required properties : - - - reg : Offset and length of the register set for the device - - compatible : should be "mrvl,mmp-twsi" where mmp is the name of a - compatible processor, e.g. pxa168, pxa910, mmp2, mmp3. - For the pxa2xx/pxa3xx, an additional node "mrvl,pxa-i2c" is required - as shown in the example below. - For the Armada 3700, the compatible should be "marvell,armada-3700-i2c". - -Recommended properties : - - - interrupts : the interrupt number - - mrvl,i2c-polling : Disable interrupt of i2c controller. Polling - status register of i2c controller instead. - - mrvl,i2c-fast-mode : Enable fast mode of i2c controller. - -Examples: - twsi1: i2c@d4011000 { - compatible = "mrvl,mmp-twsi"; - reg = <0xd4011000 0x1000>; - interrupts = <7>; - mrvl,i2c-fast-mode; - }; - - twsi2: i2c@d4025000 { - compatible = "mrvl,mmp-twsi"; - reg = <0xd4025000 0x1000>; - interrupts = <58>; - }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-pxa.yaml b/Documentation/devicetree/bindings/i2c/i2c-pxa.yaml new file mode 100644 index 000000000000..da6e8bdc4037 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-pxa.yaml @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/i2c-pxa.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell MMP I2C controller bindings + +maintainers: + - Rob Herring <robh+dt@kernel.org> + +allOf: + - $ref: /schemas/i2c/i2c-controller.yaml# + - if: + not: + required: + - mrvl,i2c-polling + then: + required: + - interrupts + +properties: + compatible: + enum: + - mrvl,mmp-twsi + - mrvl,pxa-i2c + - marvell,armada-3700-i2c + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 1 + + resets: + minItems: 1 + + mrvl,i2c-polling: + $ref: /schemas/types.yaml#/definitions/flag + description: | + Disable interrupt of i2c controller. Polling status register of i2c + controller instead. + + mrvl,i2c-fast-mode: + $ref: /schemas/types.yaml#/definitions/flag + description: Enable fast mode of i2c controller. + +unevaluatedProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - '#address-cells' + - '#size-cells' + +examples: + - | + #include <dt-bindings/clock/marvell,mmp2.h> + i2c@d4011000 { + compatible = "mrvl,mmp-twsi"; + reg = <0xd4011000 0x1000>; + interrupts = <7>; + clocks = <&soc_clocks MMP2_CLK_TWSI1>; + mrvl,i2c-fast-mode; + #address-cells = <1>; + #size-cells = <0>; + }; + +... diff --git a/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt b/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt index 18c0de362451..3f2f990c2e62 100644 --- a/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt +++ b/Documentation/devicetree/bindings/i2c/nvidia,tegra20-i2c.txt @@ -35,12 +35,12 @@ Required properties: Due to above changes, Tegra114 I2C driver makes incompatible with previous hardware driver. Hence, tegra114 I2C controller is compatible with "nvidia,tegra114-i2c". - nvidia,tegra210-i2c-vi: Tegra210 has one I2C controller that is part of the - host1x domain and typically used for camera use-cases. This VI I2C - controller is mostly compatible with the programming model of the - regular I2C controllers with a few exceptions. The I2C registers start - at an offset of 0xc00 (instead of 0), registers are 16 bytes apart - (rather than 4) and the controller does not support slave mode. + nvidia,tegra210-i2c-vi: Tegra210 has one I2C controller that is on host1x bus + and is part of VE power domain and typically used for camera use-cases. + This VI I2C controller is mostly compatible with the programming model + of the regular I2C controllers with a few exceptions. The I2C registers + start at an offset of 0xc00 (instead of 0), registers are 16 bytes + apart (rather than 4) and the controller does not support slave mode. - reg: Should contain I2C controller registers physical address and length. - interrupts: Should contain I2C controller interrupts. - address-cells: Address cells for I2C device address. @@ -53,10 +53,17 @@ Required properties: - fast-clk Tegra114: - div-clk + Tegra210: + - div-clk + - slow (only for nvidia,tegra210-i2c-vi compatible node) - resets: Must contain an entry for each entry in reset-names. See ../reset/reset.txt for details. - reset-names: Must include the following entries: - i2c +- power-domains: Only for nvidia,tegra210-i2c-vi compatible node and must + include venc powergate node as vi i2c is part of VE power domain. + tegra210-i2c-vi: + - pd_venc - dmas: Must contain an entry for each entry in clock-names. See ../dma/dma.txt for details. - dma-names: Must include the following entries: diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml index d124eba1ce54..fd4eaa3d0ab4 100644 --- a/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml +++ b/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml @@ -12,8 +12,8 @@ maintainers: description: | Analog Devices ADXL345/ADXL375 3-Axis Digital Accelerometers that supports both I2C & SPI interfaces. - http://www.analog.com/en/products/mems/accelerometers/adxl345.html - http://www.analog.com/en/products/sensors-mems/accelerometers/adxl375.html + https://www.analog.com/en/products/mems/accelerometers/adxl345.html + https://www.analog.com/en/products/sensors-mems/accelerometers/adxl375.html properties: compatible: diff --git a/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.txt b/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.txt deleted file mode 100644 index b25bf3a77e0f..000000000000 --- a/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.txt +++ /dev/null @@ -1,22 +0,0 @@ -Kionix KXSD9 Accelerometer device tree bindings - -Required properties: - - compatible: should be set to "kionix,kxsd9" - - reg: i2c slave address - -Optional properties: - - vdd-supply: The input supply for VDD - - iovdd-supply: The input supply for IOVDD - - interrupts: The movement detection interrupt - - mount-matrix: See mount-matrix.txt - -Example: - -kxsd9@18 { - compatible = "kionix,kxsd9"; - reg = <0x18>; - interrupt-parent = <&foo>; - interrupts = <57 IRQ_TYPE_EDGE_FALLING>; - iovdd-supply = <&bar>; - vdd-supply = <&baz>; -}; diff --git a/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.yaml b/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.yaml new file mode 100644 index 000000000000..d61ab4fa3d71 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/accel/kionix,kxsd9.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Kionix KXSD9 Accelerometer + +maintainers: + - Jonathan Cameron <jic23@kernel.org> + +description: | + 3 axis 12 bit accelerometer with +-8G range on all axes. Also has a + 12 bit auxiliary ADC channel. Interface is either SPI or I2C. + +properties: + compatible: + const: kionix,kxsd9 + + reg: + maxItems: 1 + + vdd-supply: true + iovdd-supply: true + + interrupts: + maxItems: 1 + + mount-matrix: + description: an optional 3x3 mounting rotation matrix. + +required: + - compatible + - reg + +examples: + - | + # include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + accel@18 { + compatible = "kionix,kxsd9"; + reg = <0x18>; + iovdd-supply = <&iovdd>; + vdd-supply = <&vdd>; + interrupts = <57 IRQ_TYPE_EDGE_FALLING>; + mount-matrix = "-0.984807753012208", "0", "-0.173648177666930", + "0", "-1", "0", + "-0.173648177666930", "0", "0.984807753012208"; + }; + }; + - | + # include <dt-bindings/interrupt-controller/irq.h> + spi { + #address-cells = <1>; + #size-cells = <0>; + accel@0 { + compatible = "kionix,kxsd9"; + reg = <0>; + spi-max-frequency = <10000000>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.txt b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.txt deleted file mode 100644 index cd9048cf9dcf..000000000000 --- a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.txt +++ /dev/null @@ -1,49 +0,0 @@ -* Ingenic JZ47xx ADC controller IIO bindings - -Required properties: - -- compatible: Should be one of: - * ingenic,jz4725b-adc - * ingenic,jz4740-adc - * ingenic,jz4770-adc -- reg: ADC controller registers location and length. -- clocks: phandle to the SoC's ADC clock. -- clock-names: Must be set to "adc". -- #io-channel-cells: Must be set to <1> to indicate channels are selected - by index. - -ADC clients must use the format described in iio-bindings.txt, giving -a phandle and IIO specifier pair ("io-channels") to the ADC controller. - -Example: - -#include <dt-bindings/iio/adc/ingenic,adc.h> - -adc: adc@10070000 { - compatible = "ingenic,jz4740-adc"; - #io-channel-cells = <1>; - - reg = <0x10070000 0x30>; - - clocks = <&cgu JZ4740_CLK_ADC>; - clock-names = "adc"; - - interrupt-parent = <&intc>; - interrupts = <18>; -}; - -adc-keys { - ... - compatible = "adc-keys"; - io-channels = <&adc INGENIC_ADC_AUX>; - io-channel-names = "buttons"; - ... -}; - -battery { - ... - compatible = "ingenic,jz4740-battery"; - io-channels = <&adc INGENIC_ADC_BATTERY>; - io-channel-names = "battery"; - ... -}; diff --git a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml new file mode 100644 index 000000000000..9f414dbdae86 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml @@ -0,0 +1,71 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2019-2020 Artur Rojek +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/iio/adc/ingenic,adc.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Ingenic JZ47xx ADC controller IIO bindings + +maintainers: + - Artur Rojek <contact@artur-rojek.eu> + +description: > + Industrial I/O subsystem bindings for ADC controller found in + Ingenic JZ47xx SoCs. + + ADC clients must use the format described in iio-bindings.txt, giving + a phandle and IIO specifier pair ("io-channels") to the ADC controller. + +properties: + compatible: + enum: + - ingenic,jz4725b-adc + - ingenic,jz4740-adc + - ingenic,jz4770-adc + + '#io-channel-cells': + const: 1 + description: + Must be set to <1> to indicate channels are selected by index. + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: adc + + interrupts: + maxItems: 1 + +required: + - compatible + - '#io-channel-cells' + - reg + - clocks + - clock-names + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/jz4740-cgu.h> + #include <dt-bindings/iio/adc/ingenic,adc.h> + + adc@10070000 { + compatible = "ingenic,jz4740-adc"; + #io-channel-cells = <1>; + + reg = <0x10070000 0x30>; + + clocks = <&cgu JZ4740_CLK_ADC>; + clock-names = "adc"; + + interrupt-parent = <&intc>; + interrupts = <18>; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.txt b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.txt deleted file mode 100644 index c8787688122a..000000000000 --- a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.txt +++ /dev/null @@ -1,173 +0,0 @@ -Qualcomm's SPMI PMIC ADC - -- SPMI PMIC voltage ADC (VADC) provides interface to clients to read - voltage. The VADC is a 15-bit sigma-delta ADC. -- SPMI PMIC5 voltage ADC (ADC) provides interface to clients to read - voltage. The VADC is a 16-bit sigma-delta ADC. - -VADC node: - -- compatible: - Usage: required - Value type: <string> - Definition: Should contain "qcom,spmi-vadc". - Should contain "qcom,spmi-adc5" for PMIC5 ADC driver. - Should contain "qcom,spmi-adc-rev2" for PMIC rev2 ADC driver. - Should contain "qcom,pms405-adc" for PMS405 PMIC - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: VADC base address in the SPMI PMIC register map. - -- #address-cells: - Usage: required - Value type: <u32> - Definition: Must be one. Child node 'reg' property should define ADC - channel number. - -- #size-cells: - Usage: required - Value type: <u32> - Definition: Must be zero. - -- #io-channel-cells: - Usage: required - Value type: <u32> - Definition: Must be one. For details about IIO bindings see: - Documentation/devicetree/bindings/iio/iio-bindings.txt - -- interrupts: - Usage: optional - Value type: <prop-encoded-array> - Definition: End of conversion interrupt. - -Channel node properties: - -- reg: - Usage: required - Value type: <u32> - Definition: ADC channel number. - See include/dt-bindings/iio/qcom,spmi-vadc.h - -- label: - Usage: required for "qcom,spmi-adc5" and "qcom,spmi-adc-rev2" - Value type: <empty> - Definition: ADC input of the platform as seen in the schematics. - For thermistor inputs connected to generic AMUX or GPIO inputs - these can vary across platform for the same pins. Hence select - the platform schematics name for this channel. - -- qcom,decimation: - Usage: optional - Value type: <u32> - Definition: This parameter is used to decrease ADC sampling rate. - Quicker measurements can be made by reducing decimation ratio. - - For compatible property "qcom,spmi-vadc", valid values are - 512, 1024, 2048, 4096. If property is not found, default value - of 512 will be used. - - For compatible property "qcom,spmi-adc5", valid values are 250, 420 - and 840. If property is not found, default value of 840 is used. - - For compatible property "qcom,spmi-adc-rev2", valid values are 256, - 512 and 1024. If property is not present, default value is 1024. - -- qcom,pre-scaling: - Usage: optional - Value type: <u32 array> - Definition: Used for scaling the channel input signal before the signal is - fed to VADC. The configuration for this node is to know the - pre-determined ratio and use it for post scaling. Select one from - the following options. - <1 1>, <1 3>, <1 4>, <1 6>, <1 20>, <1 8>, <10 81>, <1 10> - If property is not found default value depending on chip will be used. - -- qcom,ratiometric: - Usage: optional - Value type: <empty> - Definition: Channel calibration type. - - For compatible property "qcom,spmi-vadc", if this property is - specified VADC will use the VDD reference (1.8V) and GND for - channel calibration. If property is not found, channel will be - calibrated with 0.625V and 1.25V reference channels, also - known as absolute calibration. - - For compatible property "qcom,spmi-adc5" and "qcom,spmi-adc-rev2", - if this property is specified VADC will use the VDD reference - (1.875V) and GND for channel calibration. If property is not found, - channel will be calibrated with 0V and 1.25V reference channels, - also known as absolute calibration. - -- qcom,hw-settle-time: - Usage: optional - Value type: <u32> - Definition: Time between AMUX getting configured and the ADC starting - conversion. The 'hw_settle_time' is an index used from valid values - and programmed in hardware to achieve the hardware settling delay. - - For compatible property "qcom,spmi-vadc" and "qcom,spmi-adc-rev2", - Delay = 100us * (hw_settle_time) for hw_settle_time < 11, - and 2ms * (hw_settle_time - 10) otherwise. - Valid values are: 0, 100, 200, 300, 400, 500, 600, 700, 800, - 900 us and 1, 2, 4, 6, 8, 10 ms. - If property is not found, channel will use 0us. - - For compatible property "qcom,spmi-adc5", delay = 15us for - value 0, 100us * (value) for values < 11, - and 2ms * (value - 10) otherwise. - Valid values are: 15, 100, 200, 300, 400, 500, 600, 700, 800, - 900 us and 1, 2, 4, 6, 8, 10 ms - Certain controller digital versions have valid values of - 15, 100, 200, 300, 400, 500, 600, 700, 1, 2, 4, 8, 16, 32, 64, 128 ms - If property is not found, channel will use 15us. - -- qcom,avg-samples: - Usage: optional - Value type: <u32> - Definition: Number of samples to be used for measurement. - Averaging provides the option to obtain a single measurement - from the ADC that is an average of multiple samples. The value - selected is 2^(value). - - For compatible property "qcom,spmi-vadc", valid values - are: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512 - If property is not found, 1 sample will be used. - - For compatible property "qcom,spmi-adc5" and "qcom,spmi-adc-rev2", - valid values are: 1, 2, 4, 8, 16 - If property is not found, 1 sample will be used. - -NOTE: - -For compatible property "qcom,spmi-vadc" following channels, also known as -reference point channels, are used for result calibration and their channel -configuration nodes should be defined: -VADC_REF_625MV and/or VADC_SPARE1(based on PMIC version) VADC_REF_1250MV, -VADC_GND_REF and VADC_VDD_VADC. - -Example: - -#include <dt-bindings/iio/qcom,spmi-vadc.h> -#include <linux/irq.h> -/* ... */ - - /* VADC node */ - pmic_vadc: vadc@3100 { - compatible = "qcom,spmi-vadc"; - reg = <0x3100>; - interrupts = <0x0 0x31 0x0 IRQ_TYPE_EDGE_RISING>; - #address-cells = <1>; - #size-cells = <0>; - #io-channel-cells = <1>; - io-channel-ranges; - - /* Channel node */ - adc-chan@VADC_LR_MUX10_USB_ID { - reg = <VADC_LR_MUX10_USB_ID>; - qcom,decimation = <512>; - qcom,ratiometric; - qcom,hw-settle-time = <200>; - qcom,avg-samples = <1>; - qcom,pre-scaling = <1 3>; - }; - }; - - /* IIO client node */ - usb { - io-channels = <&pmic_vadc VADC_LR_MUX10_USB_ID>; - io-channel-names = "vadc"; - }; diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml new file mode 100644 index 000000000000..e6263b617941 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml @@ -0,0 +1,278 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/qcom,spmi-vadc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm's SPMI PMIC ADC + +maintainers: + - Andy Gross <agross@kernel.org> + - Bjorn Andersson <bjorn.andersson@linaro.org> + +description: | + SPMI PMIC voltage ADC (VADC) provides interface to clients to read + voltage. The VADC is a 15-bit sigma-delta ADC. + SPMI PMIC5/PMIC7 voltage ADC (ADC) provides interface to clients to read + voltage. The VADC is a 16-bit sigma-delta ADC. + +properties: + compatible: + oneOf: + - items: + - const: qcom,pms405-adc + - const: qcom,spmi-adc-rev2 + + - items: + - enum: + - qcom,spmi-vadc + - qcom,spmi-adc5 + - qcom,spmi-adc-rev2 + - qcom,spmi-adc7 + + reg: + description: VADC base address in the SPMI PMIC register map + maxItems: 1 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + '#io-channel-cells': + const: 1 + + interrupts: + maxItems: 1 + description: + End of conversion interrupt. + +required: + - compatible + - reg + - '#address-cells' + - '#size-cells' + - '#io-channel-cells' + +patternProperties: + "^.*@[0-9a-f]+$": + type: object + description: | + Represents the external channels which are connected to the ADC. + For compatible property "qcom,spmi-vadc" following channels, also known as + reference point channels, are used for result calibration and their channel + configuration nodes should be defined: + VADC_REF_625MV and/or VADC_SPARE1(based on PMIC version) VADC_REF_1250MV, + VADC_GND_REF and VADC_VDD_VADC. + + properties: + reg: + description: | + ADC channel number. + See include/dt-bindings/iio/qcom,spmi-vadc.h + For PMIC7 ADC, the channel numbers are specified separately per PMIC + in the PMIC-specific files in include/dt-bindings/iio/. + + label: + $ref: /schemas/types.yaml#/definitions/string + description: | + ADC input of the platform as seen in the schematics. + For thermistor inputs connected to generic AMUX or GPIO inputs + these can vary across platform for the same pins. Hence select + the platform schematics name for this channel. + + qcom,decimation: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + This parameter is used to decrease ADC sampling rate. + Quicker measurements can be made by reducing decimation ratio. + + qcom,pre-scaling: + description: | + Used for scaling the channel input signal before the signal is + fed to VADC. The configuration for this node is to know the + pre-determined ratio and use it for post scaling. It is a pair of + integers, denoting the numerator and denominator of the fraction by which + input signal is multiplied. For example, <1 3> indicates the signal is scaled + down to 1/3 of its value before ADC measurement. + If property is not found default value depending on chip will be used. + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32-array + oneOf: + - items: + - const: 1 + - enum: [ 1, 3, 4, 6, 20, 8, 10 ] + + - items: + - const: 10 + - const: 81 + + qcom,ratiometric: + description: | + Channel calibration type. + - For compatible property "qcom,spmi-vadc", if this property is + specified VADC will use the VDD reference (1.8V) and GND for + channel calibration. If property is not found, channel will be + calibrated with 0.625V and 1.25V reference channels, also + known as absolute calibration. + - For compatible property "qcom,spmi-adc5", "qcom,spmi-adc7" and + "qcom,spmi-adc-rev2", if this property is specified VADC will use + the VDD reference (1.875V) and GND for channel calibration. If + property is not found, channel will be calibrated with 0V and 1.25V + reference channels, also known as absolute calibration. + type: boolean + + qcom,hw-settle-time: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Time between AMUX getting configured and the ADC starting + conversion. The 'hw_settle_time' is an index used from valid values + and programmed in hardware to achieve the hardware settling delay. + + qcom,avg-samples: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Number of samples to be used for measurement. + Averaging provides the option to obtain a single measurement + from the ADC that is an average of multiple samples. The value + selected is 2^(value). + + required: + - reg + +allOf: + - if: + properties: + compatible: + contains: + const: qcom,spmi-vadc + + then: + patternProperties: + "^.*@[0-9a-f]+$": + properties: + qcom,decimation: + enum: [ 512, 1024, 2048, 4096 ] + default: 512 + + qcom,hw-settle-time: + enum: [ 0, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1, 2, + 4, 6, 8, 10 ] + default: 0 + + qcom,avg-samples: + enum: [ 1, 2, 4, 8, 16, 32, 64, 128, 256, 512 ] + default: 1 + + - if: + properties: + compatible: + contains: + const: qcom,spmi-adc-rev2 + + then: + patternProperties: + "^.*@[0-9a-f]+$": + properties: + qcom,decimation: + enum: [ 256, 512, 1024 ] + default: 1024 + + qcom,hw-settle-time: + enum: [ 0, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1, 2, + 4, 6, 8, 10 ] + default: 0 + + qcom,avg-samples: + enum: [ 1, 2, 4, 8, 16 ] + default: 1 + + - if: + properties: + compatible: + contains: + const: qcom,spmi-adc5 + + then: + patternProperties: + "^.*@[0-9a-f]+$": + properties: + qcom,decimation: + enum: [ 250, 420, 840 ] + default: 840 + + qcom,hw-settle-time: + enum: [ 15, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1, 2, + 4, 6, 8, 10, 16, 32, 64, 128 ] + default: 15 + + qcom,avg-samples: + enum: [ 1, 2, 4, 8, 16 ] + default: 1 + + - if: + properties: + compatible: + contains: + const: qcom,spmi-adc7 + + then: + patternProperties: + "^.*@[0-9a-f]+$": + properties: + qcom,decimation: + enum: [ 85, 340, 1360 ] + default: 1360 + + qcom,hw-settle-time: + enum: [ 15, 100, 200, 300, 400, 500, 600, 700, 1000, 2000, 4000, + 8000, 16000, 32000, 64000, 128000 ] + default: 15 + + qcom,avg-samples: + enum: [ 1, 2, 4, 8, 16 ] + default: 1 + +examples: + - | + spmi_bus { + #address-cells = <1>; + #size-cells = <0>; + /* VADC node */ + pmic_vadc: adc@3100 { + compatible = "qcom,spmi-vadc"; + reg = <0x3100>; + interrupts = <0x0 0x31 0x0 0x1>; + #address-cells = <1>; + #size-cells = <0>; + #io-channel-cells = <1>; + io-channel-ranges; + + /* Channel node */ + adc-chan@39 { + reg = <0x39>; + qcom,decimation = <512>; + qcom,ratiometric; + qcom,hw-settle-time = <200>; + qcom,avg-samples = <1>; + qcom,pre-scaling = <1 3>; + }; + + adc-chan@9 { + reg = <0x9>; + }; + + adc-chan@a { + reg = <0xa>; + }; + + adc-chan@e { + reg = <0xe>; + }; + + adc-chan@f { + reg = <0xf>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads8688.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads8688.yaml new file mode 100644 index 000000000000..97fe6cbb2efa --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ti,ads8688.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/ti,ads8688.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments' ADS8684 and ADS8688 ADC chip + +maintainers: + - Sean Nyekjaer <sean@geanix.com> + +description: | + SPI 16bit ADCs with 4/8 channels. + +properties: + compatible: + enum: + - ti,ads8684 + - ti,ads8688 + + reg: + maxItems: 1 + + vref-supply: + description: Optional external reference. If not supplied, assume + REFSEL input tied low to enable the internal reference. + +required: + - compatible + - reg + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + + adc@0 { + compatible = "ti,ads8688"; + reg = <0>; + vref-supply = <&vdd_supply>; + spi-max-frequency = <1000000>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/adc/ti-ads8688.txt b/Documentation/devicetree/bindings/iio/adc/ti-ads8688.txt deleted file mode 100644 index a02337d7efa4..000000000000 --- a/Documentation/devicetree/bindings/iio/adc/ti-ads8688.txt +++ /dev/null @@ -1,20 +0,0 @@ -* Texas Instruments' ADS8684 and ADS8688 ADC chip - -Required properties: - - compatible: Should be "ti,ads8684" or "ti,ads8688" - - reg: spi chip select number for the device - -Recommended properties: - - spi-max-frequency: Definition as per - Documentation/devicetree/bindings/spi/spi-bus.txt - -Optional properties: - - vref-supply: The regulator supply for ADC reference voltage - -Example: -adc@0 { - compatible = "ti,ads8688"; - reg = <0>; - vref-supply = <&vdd_supply>; - spi-max-frequency = <1000000>; -}; diff --git a/Documentation/devicetree/bindings/iio/chemical/sensirion,scd30.yaml b/Documentation/devicetree/bindings/iio/chemical/sensirion,scd30.yaml new file mode 100644 index 000000000000..40d87346ff4c --- /dev/null +++ b/Documentation/devicetree/bindings/iio/chemical/sensirion,scd30.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/chemical/sensirion,scd30.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sensirion SCD30 carbon dioxide sensor + +maintainers: + - Tomasz Duszynski <tomasz.duszynski@octakon.com> + +description: | + Air quality sensor capable of measuring co2 concentration, temperature + and relative humidity. + +properties: + compatible: + enum: + - sensirion,scd30 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + vdd-supply: true + + sensirion,sel-gpios: + description: GPIO connected to the SEL line + maxItems: 1 + + sensirion,pwm-gpios: + description: GPIO connected to the PWM line + maxItems: 1 + +required: + - compatible + +additionalProperties: false + +examples: + - | + # include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + co2-sensor@61 { + compatible = "sensirion,scd30"; + reg = <0x61>; + vdd-supply = <&vdd>; + interrupt-parent = <&gpio0>; + interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + }; + }; + - | + # include <dt-bindings/interrupt-controller/irq.h> + serial { + co2-sensor { + compatible = "sensirion,scd30"; + vdd-supply = <&vdd>; + interrupt-parent = <&gpio0>; + interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt b/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt index 639c94ed83e9..17af395b99d9 100644 --- a/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt +++ b/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt @@ -6,7 +6,7 @@ Is is programmable through an SPI interface. The internal DACs are loaded when the LOADDACS pin is pulled down. -http://www.ti.com/lit/ds/sbas106/sbas106.pdf +https://www.ti.com/lit/ds/sbas106/sbas106.pdf Required Properties: - compatible: Should be one of: diff --git a/Documentation/devicetree/bindings/iio/iio-bindings.txt b/Documentation/devicetree/bindings/iio/iio-bindings.txt index af33267727f4..aa63cac7323e 100644 --- a/Documentation/devicetree/bindings/iio/iio-bindings.txt +++ b/Documentation/devicetree/bindings/iio/iio-bindings.txt @@ -9,7 +9,7 @@ specifier is an array of one or more cells identifying the IIO output on a device. The length of an IIO specifier is defined by the value of a #io-channel-cells property in the IIO provider node. -[1] http://marc.info/?l=linux-iio&m=135902119507483&w=2 +[1] https://marc.info/?l=linux-iio&m=135902119507483&w=2 ==IIO providers== diff --git a/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml b/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml index 0d0ef84e22b9..33d8e9fd14b7 100644 --- a/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml +++ b/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml @@ -37,6 +37,15 @@ properties: set if the specified interrupt pin should be configured as open drain. If not set, defaults to push-pull. + vdd-supply: + description: provide VDD power to the sensor. + + vddio-supply: + description: provide VDD IO power to the sensor. + + mount-matrix: + description: an optional 3x3 mounting rotation matrix + required: - compatible - reg @@ -52,9 +61,14 @@ examples: bmi160@68 { compatible = "bosch,bmi160"; reg = <0x68>; + vdd-supply = <&pm8916_l17>; + vddio-supply = <&pm8916_l6>; interrupt-parent = <&gpio4>; interrupts = <12 IRQ_TYPE_EDGE_RISING>; interrupt-names = "INT1"; + mount-matrix = "0", "1", "0", + "-1", "0", "0", + "0", "0", "1"; }; }; - | diff --git a/Documentation/devicetree/bindings/iio/imu/invensense,icm42600.yaml b/Documentation/devicetree/bindings/iio/imu/invensense,icm42600.yaml new file mode 100644 index 000000000000..abd8d25e1136 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/imu/invensense,icm42600.yaml @@ -0,0 +1,90 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/imu/invensense,icm42600.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: InvenSense ICM-426xx Inertial Measurement Unit + +maintainers: + - Jean-Baptiste Maneyrol <jmaneyrol@invensense.com> + +description: | + 6-axis MotionTracking device that combines a 3-axis gyroscope and a 3-axis + accelerometer. + + It has a configurable host interface that supports I3C, I2C and SPI serial + communication, features a 2kB FIFO and 2 programmable interrupts with + ultra-low-power wake-on-motion support to minimize system power consumption. + + Other industry-leading features include InvenSense on-chip APEX Motion + Processing engine for gesture recognition, activity classification, and + pedometer, along with programmable digital filters, and an embedded + temperature sensor. + + https://invensense.tdk.com/wp-content/uploads/2020/03/DS-000292-ICM-42605-v1.4.pdf + +properties: + compatible: + enum: + - invensense,icm42600 + - invensense,icm42602 + - invensense,icm42605 + - invensense,icm42622 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + drive-open-drain: + type: boolean + + vdd-supply: + description: Regulator that provides power to the sensor + + vddio-supply: + description: Regulator that provides power to the bus + +required: + - compatible + - reg + - interrupts + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + icm42605@68 { + compatible = "invensense,icm42605"; + reg = <0x68>; + interrupt-parent = <&gpio2>; + interrupts = <7 IRQ_TYPE_EDGE_FALLING>; + vdd-supply = <&vdd>; + vddio-supply = <&vddio>; + }; + }; + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + spi0 { + #address-cells = <1>; + #size-cells = <0>; + + icm42602@0 { + compatible = "invensense,icm42602"; + reg = <0>; + spi-max-frequency = <24000000>; + spi-cpha; + spi-cpol; + interrupt-parent = <&gpio1>; + interrupts = <2 IRQ_TYPE_EDGE_FALLING>; + vdd-supply = <&vdd>; + vddio-supply = <&vddio>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/light/apds9300.txt b/Documentation/devicetree/bindings/iio/light/apds9300.txt index aa199e09a493..3aa6db3ee99d 100644 --- a/Documentation/devicetree/bindings/iio/light/apds9300.txt +++ b/Documentation/devicetree/bindings/iio/light/apds9300.txt @@ -1,6 +1,6 @@ * Avago APDS9300 ambient light sensor -http://www.avagotech.com/docs/AV02-1077EN +https://www.avagotech.com/docs/AV02-1077EN Required properties: diff --git a/Documentation/devicetree/bindings/iio/light/apds9960.txt b/Documentation/devicetree/bindings/iio/light/apds9960.txt index 3af325ad194b..c53ddb81c4aa 100644 --- a/Documentation/devicetree/bindings/iio/light/apds9960.txt +++ b/Documentation/devicetree/bindings/iio/light/apds9960.txt @@ -1,6 +1,6 @@ * Avago APDS9960 gesture/RGB/ALS/proximity sensor -http://www.avagotech.com/docs/AV02-4191EN +https://www.avagotech.com/docs/AV02-4191EN Required properties: diff --git a/Documentation/devicetree/bindings/iio/light/opt3001.txt b/Documentation/devicetree/bindings/iio/light/opt3001.txt index 47b13eb8f4ec..9e6f2998e751 100644 --- a/Documentation/devicetree/bindings/iio/light/opt3001.txt +++ b/Documentation/devicetree/bindings/iio/light/opt3001.txt @@ -6,7 +6,7 @@ the optional generation of IIO events on rising/falling light threshold changes requires the use of interrupts. Without interrupts, only the simple reading of the current light value is supported through the IIO API. -http://www.ti.com/product/opt3001 +https://www.ti.com/product/opt3001 Required properties: - compatible: should be "ti,opt3001" diff --git a/Documentation/devicetree/bindings/iio/light/vl6180.txt b/Documentation/devicetree/bindings/iio/light/vl6180.txt index 2c52952715a0..fb9137d85df9 100644 --- a/Documentation/devicetree/bindings/iio/light/vl6180.txt +++ b/Documentation/devicetree/bindings/iio/light/vl6180.txt @@ -1,6 +1,6 @@ STMicro VL6180 - ALS, range and proximity sensor -Link to datasheet: http://www.st.com/resource/en/datasheet/vl6180x.pdf +Link to datasheet: https://www.st.com/resource/en/datasheet/vl6180x.pdf Required properties: diff --git a/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt b/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt deleted file mode 100644 index aa67ceb0d4e0..000000000000 --- a/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt +++ /dev/null @@ -1,30 +0,0 @@ -* AsahiKASEI AK8975 magnetometer sensor - -Required properties: - - - compatible : should be "asahi-kasei,ak8975" - - reg : the I2C address of the magnetometer - -Optional properties: - - - gpios : should be device tree identifier of the magnetometer DRDY pin - - vdd-supply: an optional regulator that needs to be on to provide VDD - - mount-matrix: an optional 3x3 mounting rotation matrix - -Example: - -ak8975@c { - compatible = "asahi-kasei,ak8975"; - reg = <0x0c>; - gpios = <&gpj0 7 0>; - vdd-supply = <&ldo_3v3_gnss>; - mount-matrix = "-0.984807753012208", /* x0 */ - "0", /* y0 */ - "-0.173648177666930", /* z0 */ - "0", /* x1 */ - "-1", /* y1 */ - "0", /* z1 */ - "-0.173648177666930", /* x2 */ - "0", /* y2 */ - "0.984807753012208"; /* z2 */ -}; diff --git a/Documentation/devicetree/bindings/iio/magnetometer/asahi-kasei,ak8975.yaml b/Documentation/devicetree/bindings/iio/magnetometer/asahi-kasei,ak8975.yaml new file mode 100644 index 000000000000..f4393bfbf355 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/magnetometer/asahi-kasei,ak8975.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/magnetometer/asahi-kasei,ak8975.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: AsahiKASEI AK8975 magnetometer sensor + +maintainers: + - Jonathan Albrieux <jonathan.albrieux@gmail.com> + +properties: + compatible: + oneOf: + - enum: + - asahi-kasei,ak8975 + - asahi-kasei,ak8963 + - asahi-kasei,ak09911 + - asahi-kasei,ak09912 + - enum: + - ak8975 + - ak8963 + - ak09911 + - ak09912 + deprecated: true + + reg: + maxItems: 1 + + gpios: + maxItems: 1 + description: | + AK8975 has a "Data ready" pin (DRDY) which informs that data + is ready to be read and is possible to listen on it. If used, + this should be active high. Prefer interrupt over this. + + interrupts: + maxItems: 1 + description: interrupt for DRDY pin. Triggered on rising edge. + + vdd-supply: + description: | + an optional regulator that needs to be on to provide VDD power to + the sensor. + + mount-matrix: + description: an optional 3x3 mounting rotation matrix. + + reset-gpios: + description: | + an optional pin needed for AK09911 to set the reset state. This should + be usually active low + +required: + - compatible + - reg + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/gpio/gpio.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + magnetometer@c { + compatible = "asahi-kasei,ak8975"; + reg = <0x0c>; + interrupt-parent = <&gpio6>; + interrupts = <15 IRQ_TYPE_EDGE_RISING>; + vdd-supply = <&ldo_3v3_gnss>; + reset-gpios = <&msmgpio 111 GPIO_ACTIVE_LOW>; + mount-matrix = "-0.984807753012208", /* x0 */ + "0", /* y0 */ + "-0.173648177666930", /* z0 */ + "0", /* x1 */ + "-1", /* y1 */ + "0", /* z1 */ + "-0.173648177666930", /* x2 */ + "0", /* y2 */ + "0.984807753012208"; /* z2 */ + }; + }; diff --git a/Documentation/devicetree/bindings/iio/magnetometer/bmc150_magn.txt b/Documentation/devicetree/bindings/iio/magnetometer/bmc150_magn.txt index fd5fca90fb39..22912e43b60c 100644 --- a/Documentation/devicetree/bindings/iio/magnetometer/bmc150_magn.txt +++ b/Documentation/devicetree/bindings/iio/magnetometer/bmc150_magn.txt @@ -4,7 +4,11 @@ http://ae-bst.resource.bosch.com/media/products/dokumente/bmc150/BST-BMC150-DS00 Required properties: - - compatible : should be "bosch,bmc150_magn" + - compatible : should be one of: + "bosch,bmc150_magn" + "bosch,bmc156_magn" + "bosch,bmm150" + "bosch,bmm150_magn" (DEPRECATED, use bosch,bmm150) - reg : the I2C address of the magnetometer Optional properties: diff --git a/Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.txt b/Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.txt index c82794002595..89647d714387 100644 --- a/Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.txt +++ b/Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.txt @@ -21,7 +21,7 @@ controller state. The mux controller state is described in Example: mux: mux-controller { - compatible = "mux-gpio"; + compatible = "gpio-mux"; #mux-control-cells = <0>; mux-gpios = <&pioA 0 GPIO_ACTIVE_HIGH>, diff --git a/Documentation/devicetree/bindings/iio/potentiometer/mcp41010.txt b/Documentation/devicetree/bindings/iio/potentiometer/mcp41010.txt index 566711b9950c..4f245e8469fd 100644 --- a/Documentation/devicetree/bindings/iio/potentiometer/mcp41010.txt +++ b/Documentation/devicetree/bindings/iio/potentiometer/mcp41010.txt @@ -1,7 +1,7 @@ * Microchip MCP41010/41050/41100/42010/42050/42100 Digital Potentiometer Datasheet publicly available at: -http://ww1.microchip.com/downloads/en/devicedoc/11195c.pdf +https://ww1.microchip.com/downloads/en/devicedoc/11195c.pdf The node for this driver must be a child node of a SPI controller, hence all mandatory properties described in diff --git a/Documentation/devicetree/bindings/iio/potentiostat/lmp91000.txt b/Documentation/devicetree/bindings/iio/potentiostat/lmp91000.txt index e6d0c2eb345c..f3ab02b0dd41 100644 --- a/Documentation/devicetree/bindings/iio/potentiostat/lmp91000.txt +++ b/Documentation/devicetree/bindings/iio/potentiostat/lmp91000.txt @@ -1,7 +1,7 @@ * Texas Instruments LMP91000 series of potentiostats -LMP91000: http://www.ti.com/lit/ds/symlink/lmp91000.pdf -LMP91002: http://www.ti.com/lit/ds/symlink/lmp91002.pdf +LMP91000: https://www.ti.com/lit/ds/symlink/lmp91000.pdf +LMP91002: https://www.ti.com/lit/ds/symlink/lmp91002.pdf Required properties: diff --git a/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml b/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml index 64c18f1693f0..be2be4b556db 100644 --- a/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml +++ b/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml @@ -13,7 +13,7 @@ description: | Bindings for the All Sensors DLH series pressure sensors. Specifications about the sensors can be found at: - http://www.allsensors.com/cad/DS-0355_Rev_B.PDF + https://www.allsensors.com/cad/DS-0355_Rev_B.PDF properties: compatible: diff --git a/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.yaml b/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.yaml index f86f8b23ef18..ce795279839e 100644 --- a/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.yaml +++ b/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.yaml @@ -17,9 +17,9 @@ description: | until it is received once again Specifications about the devices can be found at: - http://www.robot-electronics.co.uk/htm/srf04tech.htm + https://www.robot-electronics.co.uk/htm/srf04tech.htm - http://www.maxbotix.com/documents/LV-MaxSonar-EZ_Datasheet.pdf + https://www.maxbotix.com/documents/LV-MaxSonar-EZ_Datasheet.pdf properties: compatible: diff --git a/Documentation/devicetree/bindings/input/imx-keypad.txt b/Documentation/devicetree/bindings/input/imx-keypad.txt deleted file mode 100644 index 2ebaf7d26843..000000000000 --- a/Documentation/devicetree/bindings/input/imx-keypad.txt +++ /dev/null @@ -1,53 +0,0 @@ -* Freescale i.MX Keypad Port(KPP) device tree bindings - -The KPP is designed to interface with a keypad matrix with 2-point contact -or 3-point contact keys. The KPP is designed to simplify the software task -of scanning a keypad matrix. The KPP is capable of detecting, debouncing, -and decoding one or multiple keys pressed simultaneously on a keypad. - -Required SoC Specific Properties: -- compatible: Should be "fsl,<soc>-kpp". - -- reg: Physical base address of the KPP and length of memory mapped - region. - -- interrupts: The KPP interrupt number to the CPU(s). - -- clocks: The clock provided by the SoC to the KPP. Some SoCs use dummy -clock(The clock for the KPP is provided by the SoCs automatically). - -Required Board Specific Properties: -- pinctrl-names: The definition can be found at -pinctrl/pinctrl-bindings.txt. - -- pinctrl-0: The definition can be found at -pinctrl/pinctrl-bindings.txt. - -- linux,keymap: The definition can be found at -bindings/input/matrix-keymap.txt. - -Example: -kpp: kpp@73f94000 { - compatible = "fsl,imx51-kpp", "fsl,imx21-kpp"; - reg = <0x73f94000 0x4000>; - interrupts = <60>; - clocks = <&clks 0>; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_kpp_1>; - linux,keymap = <0x00000067 /* KEY_UP */ - 0x0001006c /* KEY_DOWN */ - 0x00020072 /* KEY_VOLUMEDOWN */ - 0x00030066 /* KEY_HOME */ - 0x0100006a /* KEY_RIGHT */ - 0x01010069 /* KEY_LEFT */ - 0x0102001c /* KEY_ENTER */ - 0x01030073 /* KEY_VOLUMEUP */ - 0x02000040 /* KEY_F6 */ - 0x02010042 /* KEY_F8 */ - 0x02020043 /* KEY_F9 */ - 0x02030044 /* KEY_F10 */ - 0x0300003b /* KEY_F1 */ - 0x0301003c /* KEY_F2 */ - 0x0302003d /* KEY_F3 */ - 0x03030074>; /* KEY_POWER */ -}; diff --git a/Documentation/devicetree/bindings/input/imx-keypad.yaml b/Documentation/devicetree/bindings/input/imx-keypad.yaml new file mode 100644 index 000000000000..7432c6e8cf3a --- /dev/null +++ b/Documentation/devicetree/bindings/input/imx-keypad.yaml @@ -0,0 +1,85 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/imx-keypad.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale i.MX Keypad Port(KPP) device tree bindings + +maintainers: + - Liu Ying <gnuiyl@gmail.com> + +allOf: + - $ref: "/schemas/input/matrix-keymap.yaml#" + +description: | + The KPP is designed to interface with a keypad matrix with 2-point contact + or 3-point contact keys. The KPP is designed to simplify the software task + of scanning a keypad matrix. The KPP is capable of detecting, debouncing, + and decoding one or multiple keys pressed simultaneously on a keypad. + +properties: + compatible: + oneOf: + - const: fsl,imx21-kpp + - items: + - enum: + - fsl,imx25-kpp + - fsl,imx27-kpp + - fsl,imx31-kpp + - fsl,imx35-kpp + - fsl,imx51-kpp + - fsl,imx53-kpp + - fsl,imx50-kpp + - fsl,imx6q-kpp + - fsl,imx6sx-kpp + - fsl,imx6sl-kpp + - fsl,imx6sll-kpp + - fsl,imx6ul-kpp + - fsl,imx7d-kpp + - const: fsl,imx21-kpp + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + - linux,keymap + +unevaluatedProperties: false + +examples: + - | + keypad@73f94000 { + compatible = "fsl,imx51-kpp", "fsl,imx21-kpp"; + reg = <0x73f94000 0x4000>; + interrupts = <60>; + clocks = <&clks 0>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_kpp_1>; + linux,keymap = <0x00000067 /* KEY_UP */ + 0x0001006c /* KEY_DOWN */ + 0x00020072 /* KEY_VOLUMEDOWN */ + 0x00030066 /* KEY_HOME */ + 0x0100006a /* KEY_RIGHT */ + 0x01010069 /* KEY_LEFT */ + 0x0102001c /* KEY_ENTER */ + 0x01030073 /* KEY_VOLUMEUP */ + 0x02000040 /* KEY_F6 */ + 0x02010042 /* KEY_F8 */ + 0x02020043 /* KEY_F9 */ + 0x02030044 /* KEY_F10 */ + 0x0300003b /* KEY_F1 */ + 0x0301003c /* KEY_F2 */ + 0x0302003d /* KEY_F3 */ + 0x03030074>; /* KEY_POWER */ + }; diff --git a/Documentation/devicetree/bindings/input/matrix-keymap.txt b/Documentation/devicetree/bindings/input/matrix-keymap.txt index c54919fad17e..79f6d01aecaa 100644 --- a/Documentation/devicetree/bindings/input/matrix-keymap.txt +++ b/Documentation/devicetree/bindings/input/matrix-keymap.txt @@ -1,27 +1 @@ -A simple common binding for matrix-connected key boards. Currently targeted at -defining the keys in the scope of linux key codes since that is a stable and -standardized interface at this time. - -Required properties: -- linux,keymap: an array of packed 1-cell entries containing the equivalent - of row, column and linux key-code. The 32-bit big endian cell is packed - as: - row << 24 | column << 16 | key-code - -Optional properties: -Properties for the number of rows and columns are optional because some -drivers will use fixed values for these. -- keypad,num-rows: Number of row lines connected to the keypad controller. -- keypad,num-columns: Number of column lines connected to the keypad - controller. - -Some users of this binding might choose to specify secondary keymaps for -cases where there is a modifier key such as a Fn key. Proposed names -for said properties are "linux,fn-keymap" or with another descriptive -word for the modifier other from "Fn". - -Example: - linux,keymap = < 0x00030012 - 0x0102003a >; - keypad,num-rows = <2>; - keypad,num-columns = <8>; +This file has been moved to matrix-keymap.yaml diff --git a/Documentation/devicetree/bindings/input/matrix-keymap.yaml b/Documentation/devicetree/bindings/input/matrix-keymap.yaml new file mode 100644 index 000000000000..c3bf09156783 --- /dev/null +++ b/Documentation/devicetree/bindings/input/matrix-keymap.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/matrix-keymap.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Common key matrices binding for matrix-connected key boards + +maintainers: + - Olof Johansson <olof@lixom.net> + +description: | + A simple common binding for matrix-connected key boards. Currently targeted at + defining the keys in the scope of linux key codes since that is a stable and + standardized interface at this time. + + Some users of this binding might choose to specify secondary keymaps for + cases where there is a modifier key such as a Fn key. Proposed names + for said properties are "linux,fn-keymap" or with another descriptive + word for the modifier other from "Fn". + +properties: + linux,keymap: + $ref: '/schemas/types.yaml#/definitions/uint32-array' + description: | + An array of packed 1-cell entries containing the equivalent of row, + column and linux key-code. The 32-bit big endian cell is packed as: + row << 24 | column << 16 | key-code + + keypad,num-rows: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Number of row lines connected to the keypad controller. + + keypad,num-columns: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Number of column lines connected to the keypad controller. + +examples: + - | + keypad { + /* ... */ + linux,keymap = < 0x00030012 + 0x0102003a >; + keypad,num-rows = <2>; + keypad,num-columns = <8>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.txt index d514ec060a4a..021cf822395c 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,l2-intc.txt @@ -2,7 +2,10 @@ Broadcom Generic Level 2 Interrupt Controller Required properties: -- compatible: should be "brcm,l2-intc" for latched interrupt controllers +- compatible: should be one of: + "brcm,hif-spi-l2-intc" or + "brcm,upg-aux-aon-l2-intc" or + "brcm,l2-intc" for latched interrupt controllers should be "brcm,bcm7271-l2-intc" for level interrupt controllers - reg: specifies the base physical address and size of the registers - interrupt-controller: identifies the node as an interrupt controller diff --git a/Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.txt b/Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.txt index e13405355166..e6bbcae4d07f 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.txt @@ -10,7 +10,7 @@ Interrupt number definition: 16-31 : private irq, and we use 16 as the co-processor timer. 31-1024: common irq for soc ip. -Interrupt triger mode: (Defined in dt-bindings/interrupt-controller/irq.h) +Interrupt trigger mode: (Defined in dt-bindings/interrupt-controller/irq.h) IRQ_TYPE_LEVEL_HIGH (default) IRQ_TYPE_LEVEL_LOW IRQ_TYPE_EDGE_RISING diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,htvec.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,htvec.yaml index e865cd8f96a9..87a74558204f 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/loongson,htvec.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,htvec.yaml @@ -22,8 +22,8 @@ properties: interrupts: minItems: 1 - maxItems: 4 - description: Four parent interrupts that receive chained interrupts. + maxItems: 8 + description: Eight parent interrupts that receive chained interrupts. interrupt-controller: true diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml b/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml index b1db21ed44e9..03fc4f5b4b39 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,liointc.yaml @@ -51,8 +51,8 @@ properties: description: | This property points how the children interrupts will be mapped into CPU interrupt lines. Each cell refers to a parent interrupt line from 0 to 3 - and each bit in the cell refers to a children interrupt fron 0 to 31. - If a CPU interrupt line didn't connected with liointc, then keep it's + and each bit in the cell refers to a child interrupt from 0 to 31. + If a CPU interrupt line didn't connect with liointc, then keep its cell with zero. $ref: /schemas/types.yaml#/definitions/uint32-array minItems: 4 diff --git a/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt b/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt deleted file mode 100644 index 173595305e26..000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt +++ /dev/null @@ -1,67 +0,0 @@ -MIPS Global Interrupt Controller (GIC) - -The MIPS GIC routes external interrupts to individual VPEs and IRQ pins. -It also supports local (per-processor) interrupts and software-generated -interrupts which can be used as IPIs. The GIC also includes a free-running -global timer, per-CPU count/compare timers, and a watchdog. - -Required properties: -- compatible : Should be "mti,gic". -- interrupt-controller : Identifies the node as an interrupt controller -- #interrupt-cells : Specifies the number of cells needed to encode an - interrupt specifier. Should be 3. - - The first cell is the type of interrupt, local or shared. - See <include/dt-bindings/interrupt-controller/mips-gic.h>. - - The second cell is the GIC interrupt number. - - The third cell encodes the interrupt flags. - See <include/dt-bindings/interrupt-controller/irq.h> for a list of valid - flags. - -Optional properties: -- reg : Base address and length of the GIC registers. If not present, - the base address reported by the hardware GCR_GIC_BASE will be used. -- mti,reserved-cpu-vectors : Specifies the list of CPU interrupt vectors - to which the GIC may not route interrupts. Valid values are 2 - 7. - This property is ignored if the CPU is started in EIC mode. -- mti,reserved-ipi-vectors : Specifies the range of GIC interrupts that are - reserved for IPIs. - It accepts 2 values, the 1st is the starting interrupt and the 2nd is the size - of the reserved range. - If not specified, the driver will allocate the last 2 * number of VPEs in the - system. - -Required properties for timer sub-node: -- compatible : Should be "mti,gic-timer". -- interrupts : Interrupt for the GIC local timer. - -Optional properties for timer sub-node: -- clocks : GIC timer operating clock. -- clock-frequency : Clock frequency at which the GIC timers operate. - -Note that one of clocks or clock-frequency must be specified. - -Example: - - gic: interrupt-controller@1bdc0000 { - compatible = "mti,gic"; - reg = <0x1bdc0000 0x20000>; - - interrupt-controller; - #interrupt-cells = <3>; - - mti,reserved-cpu-vectors = <7>; - mti,reserved-ipi-vectors = <40 8>; - - timer { - compatible = "mti,gic-timer"; - interrupts = <GIC_LOCAL 1 IRQ_TYPE_NONE>; - clock-frequency = <50000000>; - }; - }; - - uart@18101400 { - ... - interrupt-parent = <&gic>; - interrupts = <GIC_SHARED 24 IRQ_TYPE_LEVEL_HIGH>; - ... - }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.txt b/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.txt deleted file mode 100644 index a0ed02725a9d..000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.txt +++ /dev/null @@ -1,64 +0,0 @@ -* Marvell MMP Interrupt controller - -Required properties: -- compatible : Should be - "mrvl,mmp-intc" on Marvel MMP, - "mrvl,mmp2-intc" along with "mrvl,mmp2-mux-intc" on MMP2 or - "marvell,mmp3-intc" with "mrvl,mmp2-mux-intc" on MMP3 -- reg : Address and length of the register set of the interrupt controller. - If the interrupt controller is intc, address and length means the range - of the whole interrupt controller. The "marvell,mmp3-intc" controller - also has a secondary range for the second CPU core. If the interrupt - controller is mux-intc, address and length means one register. Since - address of mux-intc is in the range of intc. mux-intc is secondary - interrupt controller. -- reg-names : Name of the register set of the interrupt controller. It's - only required in mux-intc interrupt controller. -- interrupts : Should be the port interrupt shared by mux interrupts. It's - only required in mux-intc interrupt controller. -- interrupt-controller : Identifies the node as an interrupt controller. -- #interrupt-cells : Specifies the number of cells needed to encode an - interrupt source. -- mrvl,intc-nr-irqs : Specifies the number of interrupts in the interrupt - controller. -- mrvl,clr-mfp-irq : Specifies the interrupt that needs to clear MFP edge - detection first. - -Example: - intc: interrupt-controller@d4282000 { - compatible = "mrvl,mmp2-intc"; - interrupt-controller; - #interrupt-cells = <1>; - reg = <0xd4282000 0x1000>; - mrvl,intc-nr-irqs = <64>; - }; - - intcmux4@d4282150 { - compatible = "mrvl,mmp2-mux-intc"; - interrupts = <4>; - interrupt-controller; - #interrupt-cells = <1>; - reg = <0x150 0x4>, <0x168 0x4>; - reg-names = "mux status", "mux mask"; - mrvl,intc-nr-irqs = <2>; - }; - -* Marvell Orion Interrupt controller - -Required properties -- compatible : Should be "marvell,orion-intc". -- #interrupt-cells: Specifies the number of cells needed to encode an - interrupt source. Supported value is <1>. -- interrupt-controller : Declare this node to be an interrupt controller. -- reg : Interrupt mask address. A list of 4 byte ranges, one per controller. - One entry in the list represents 32 interrupts. - -Example: - - intc: interrupt-controller { - compatible = "marvell,orion-intc", "marvell,intc"; - interrupt-controller; - #interrupt-cells = <1>; - reg = <0xfed20204 0x04>, - <0xfed20214 0x04>; - }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.yaml new file mode 100644 index 000000000000..372ccbfae771 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.yaml @@ -0,0 +1,134 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/mrvl,intc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell MMP/Orion Interrupt controller bindings + +maintainers: + - Thomas Gleixner <tglx@linutronix.de> + - Jason Cooper <jason@lakedaemon.net> + - Marc Zyngier <maz@kernel.org> + - Rob Herring <robh+dt@kernel.org> + +allOf: + - if: + properties: + compatible: + not: + contains: + const: marvell,orion-intc + then: + required: + - mrvl,intc-nr-irqs + - if: + properties: + compatible: + contains: + enum: + - mrvl,mmp-intc + - mrvl,mmp2-intc + then: + properties: + reg: + maxItems: 1 + - if: + properties: + compatible: + contains: + enum: + - marvell,mmp3-intc + - mrvl,mmp2-mux-intc + then: + properties: + reg: + minItems: 2 + - if: + properties: + compatible: + contains: + const: mrvl,mmp2-mux-intc + then: + properties: + interrupts: + maxItems: 1 + reg-names: + items: + - const: 'mux status' + - const: 'mux mask' + required: + - interrupts + else: + properties: + interrupts: false + +properties: + '#interrupt-cells': + const: 1 + + compatible: + enum: + - mrvl,mmp-intc + - mrvl,mmp2-intc + - marvell,mmp3-intc + - marvell,orion-intc + - mrvl,mmp2-mux-intc + + reg: + minItems: 1 + maxItems: 2 + + reg-names: true + + interrupts: true + + interrupt-controller: true + + mrvl,intc-nr-irqs: + description: | + Specifies the number of interrupts in the interrupt controller. + $ref: /schemas/types.yaml#/definitions/uint32 + + mrvl,clr-mfp-irq: + description: | + Specifies the interrupt that needs to clear MFP edge detection first. + $ref: /schemas/types.yaml#/definitions/uint32 + +required: + - '#interrupt-cells' + - compatible + - reg + - interrupt-controller + +additionalProperties: false + +examples: + - | + interrupt-controller@d4282000 { + compatible = "mrvl,mmp2-intc"; + interrupt-controller; + #interrupt-cells = <1>; + reg = <0xd4282000 0x1000>; + mrvl,intc-nr-irqs = <64>; + }; + + interrupt-controller@d4282150 { + compatible = "mrvl,mmp2-mux-intc"; + interrupts = <4>; + interrupt-controller; + #interrupt-cells = <1>; + reg = <0x150 0x4>, <0x168 0x4>; + reg-names = "mux status", "mux mask"; + mrvl,intc-nr-irqs = <2>; + }; + - | + interrupt-controller@fed20204 { + compatible = "marvell,orion-intc"; + interrupt-controller; + #interrupt-cells = <1>; + reg = <0xfed20204 0x04>, + <0xfed20214 0x04>; + }; + +... diff --git a/Documentation/devicetree/bindings/interrupt-controller/mti,gic.yaml b/Documentation/devicetree/bindings/interrupt-controller/mti,gic.yaml new file mode 100644 index 000000000000..9f0eb3addac4 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/mti,gic.yaml @@ -0,0 +1,148 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/mti,gic.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MIPS Global Interrupt Controller + +maintainers: + - Paul Burton <paulburton@kernel.org> + - Thomas Bogendoerfer <tsbogend@alpha.franken.de> + +description: | + The MIPS GIC routes external interrupts to individual VPEs and IRQ pins. + It also supports local (per-processor) interrupts and software-generated + interrupts which can be used as IPIs. The GIC also includes a free-running + global timer, per-CPU count/compare timers, and a watchdog. + +properties: + compatible: + const: mti,gic + + "#interrupt-cells": + const: 3 + description: | + The 1st cell is the type of interrupt: local or shared defined in the + file 'dt-bindings/interrupt-controller/mips-gic.h'. The 2nd cell is the + GIC interrupt number. The 3d cell encodes the interrupt flags setting up + the IRQ trigger modes, which are defined in the file + 'dt-bindings/interrupt-controller/irq.h'. + + reg: + description: | + Base address and length of the GIC registers space. If not present, + the base address reported by the hardware GCR_GIC_BASE will be used. + maxItems: 1 + + interrupt-controller: true + + mti,reserved-cpu-vectors: + description: | + Specifies the list of CPU interrupt vectors to which the GIC may not + route interrupts. This property is ignored if the CPU is started in EIC + mode. + allOf: + - $ref: /schemas/types.yaml#definitions/uint32-array + - minItems: 1 + maxItems: 6 + uniqueItems: true + items: + minimum: 2 + maximum: 7 + + mti,reserved-ipi-vectors: + description: | + Specifies the range of GIC interrupts that are reserved for IPIs. + It accepts two values: the 1st is the starting interrupt and the 2nd is + the size of the reserved range. If not specified, the driver will + allocate the last (2 * number of VPEs in the system). + allOf: + - $ref: /schemas/types.yaml#definitions/uint32-array + - items: + - minimum: 0 + maximum: 254 + - minimum: 2 + maximum: 254 + + timer: + type: object + description: | + MIPS GIC includes a free-running global timer, per-CPU count/compare + timers, and a watchdog. Currently only the GIC Timer is supported. + properties: + compatible: + const: mti,gic-timer + + interrupts: + description: | + Interrupt for the GIC local timer, so normally it's suppose to be of + <GIC_LOCAL X IRQ_TYPE_NONE> format. + maxItems: 1 + + clocks: + maxItems: 1 + + clock-frequency: true + + required: + - compatible + - interrupts + + oneOf: + - required: + - clocks + - required: + - clock-frequency + + additionalProperties: false + +unevaluatedProperties: false + +required: + - compatible + - "#interrupt-cells" + - interrupt-controller + +examples: + - | + #include <dt-bindings/interrupt-controller/mips-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + interrupt-controller@1bdc0000 { + compatible = "mti,gic"; + reg = <0x1bdc0000 0x20000>; + interrupt-controller; + #interrupt-cells = <3>; + mti,reserved-cpu-vectors = <7>; + mti,reserved-ipi-vectors = <40 8>; + + timer { + compatible = "mti,gic-timer"; + interrupts = <GIC_LOCAL 1 IRQ_TYPE_NONE>; + clock-frequency = <50000000>; + }; + }; + - | + #include <dt-bindings/interrupt-controller/mips-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + interrupt-controller@1bdc0000 { + compatible = "mti,gic"; + reg = <0x1bdc0000 0x20000>; + interrupt-controller; + #interrupt-cells = <3>; + + timer { + compatible = "mti,gic-timer"; + interrupts = <GIC_LOCAL 1 IRQ_TYPE_NONE>; + clocks = <&cpu_pll>; + }; + }; + - | + interrupt-controller { + compatible = "mti,gic"; + interrupt-controller; + #interrupt-cells = <3>; + }; +... diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,rza1-irqc.txt b/Documentation/devicetree/bindings/interrupt-controller/renesas,rza1-irqc.txt deleted file mode 100644 index 727b7e4cd6e0..000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/renesas,rza1-irqc.txt +++ /dev/null @@ -1,43 +0,0 @@ -DT bindings for the Renesas RZ/A1 Interrupt Controller - -The RZ/A1 Interrupt Controller is a front-end for the GIC found on Renesas -RZ/A1 and RZ/A2 SoCs: - - IRQ sense select for 8 external interrupts, 1:1-mapped to 8 GIC SPI - interrupts, - - NMI edge select. - -Required properties: - - compatible: Must be "renesas,<soctype>-irqc", and "renesas,rza1-irqc" as - fallback. - Examples with soctypes are: - - "renesas,r7s72100-irqc" (RZ/A1H) - - "renesas,r7s9210-irqc" (RZ/A2M) - - #interrupt-cells: Must be 2 (an interrupt index and flags, as defined - in interrupts.txt in this directory) - - #address-cells: Must be zero - - interrupt-controller: Marks the device as an interrupt controller - - reg: Base address and length of the memory resource used by the interrupt - controller - - interrupt-map: Specifies the mapping from external interrupts to GIC - interrupts - - interrupt-map-mask: Must be <7 0> - -Example: - - irqc: interrupt-controller@fcfef800 { - compatible = "renesas,r7s72100-irqc", "renesas,rza1-irqc"; - #interrupt-cells = <2>; - #address-cells = <0>; - interrupt-controller; - reg = <0xfcfef800 0x6>; - interrupt-map = - <0 0 &gic GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>, - <1 0 &gic GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>, - <2 0 &gic GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>, - <3 0 &gic GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>, - <4 0 &gic GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>, - <5 0 &gic GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>, - <6 0 &gic GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>, - <7 0 &gic GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>; - interrupt-map-mask = <7 0>; - }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,rza1-irqc.yaml b/Documentation/devicetree/bindings/interrupt-controller/renesas,rza1-irqc.yaml new file mode 100644 index 000000000000..755cdfabfcd0 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/renesas,rza1-irqc.yaml @@ -0,0 +1,80 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/renesas,rza1-irqc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/A1 Interrupt Controller + +maintainers: + - Chris Brandt <chris.brandt@renesas.com> + - Geert Uytterhoeven <geert+renesas@glider.be> + +description: | + The RZ/A1 Interrupt Controller is a front-end for the GIC found on Renesas RZ/A1 and + RZ/A2 SoCs: + - IRQ sense select for 8 external interrupts, 1:1-mapped to 8 GIC SPI interrupts, + - NMI edge select. + +allOf: + - $ref: /schemas/interrupt-controller.yaml# + +properties: + compatible: + items: + - enum: + - renesas,r7s72100-irqc # RZ/A1H + - renesas,r7s9210-irqc # RZ/A2M + - const: renesas,rza1-irqc + + '#interrupt-cells': + const: 2 + + '#address-cells': + const: 0 + + interrupt-controller: true + + reg: + maxItems: 1 + + interrupt-map: + maxItems: 8 + description: Specifies the mapping from external interrupts to GIC interrupts. + + interrupt-map-mask: + items: + - const: 7 + - const: 0 + +required: + - compatible + - '#interrupt-cells' + - '#address-cells' + - interrupt-controller + - reg + - interrupt-map + - interrupt-map-mask + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + irqc: interrupt-controller@fcfef800 { + compatible = "renesas,r7s72100-irqc", "renesas,rza1-irqc"; + #interrupt-cells = <2>; + #address-cells = <0>; + interrupt-controller; + reg = <0xfcfef800 0x6>; + interrupt-map = + <0 0 &gic GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>, + <1 0 &gic GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>, + <2 0 &gic GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>, + <3 0 &gic GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>, + <4 0 &gic GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>, + <5 0 &gic GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>, + <6 0 &gic GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>, + <7 0 &gic GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>; + interrupt-map-mask = <7 0>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.txt b/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.txt index 1a8718f8855d..178fca08278f 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.txt @@ -55,7 +55,7 @@ Required Properties: corresponds to a range of host irqs. For more details on TISCI IRQ resource management refer: -http://downloads.ti.com/tisci/esd/latest/2_tisci_msgs/rm/rm_irq.html +https://downloads.ti.com/tisci/esd/latest/2_tisci_msgs/rm/rm_irq.html Example: -------- diff --git a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml index 39675cf4ed71..5e4fe54f51cd 100644 --- a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml +++ b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.yaml @@ -32,6 +32,7 @@ properties: - enum: - renesas,ipmmu-r8a774a1 # RZ/G2M - renesas,ipmmu-r8a774b1 # RZ/G2N + - renesas,ipmmu-r8a774e1 # RZ/G2H - renesas,ipmmu-r8a774c0 # RZ/G2E - renesas,ipmmu-r8a7795 # R-Car H3 - renesas,ipmmu-r8a7796 # R-Car M3-W diff --git a/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.txt b/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.txt deleted file mode 100644 index 321be6640533..000000000000 --- a/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.txt +++ /dev/null @@ -1,16 +0,0 @@ -gpio-backlight bindings - -Required properties: - - compatible: "gpio-backlight" - - gpios: describes the gpio that is used for enabling/disabling the backlight. - refer to bindings/gpio/gpio.txt for more details. - -Optional properties: - - default-on: enable the backlight at boot. - -Example: - backlight { - compatible = "gpio-backlight"; - gpios = <&gpio3 4 GPIO_ACTIVE_HIGH>; - default-on; - }; diff --git a/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.yaml new file mode 100644 index 000000000000..75cc569b9c55 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.yaml @@ -0,0 +1,41 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/backlight/gpio-backlight.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: gpio-backlight bindings + +maintainers: + - Lee Jones <lee.jones@linaro.org> + - Daniel Thompson <daniel.thompson@linaro.org> + - Jingoo Han <jingoohan1@gmail.com> + +properties: + compatible: + const: gpio-backlight + + gpios: + description: The gpio that is used for enabling/disabling the backlight. + maxItems: 1 + + default-on: + description: enable the backlight at boot. + type: boolean + +required: + - compatible + - gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + backlight { + compatible = "gpio-backlight"; + gpios = <&gpio3 4 GPIO_ACTIVE_HIGH>; + default-on; + }; + +... diff --git a/Documentation/devicetree/bindings/leds/backlight/led-backlight.txt b/Documentation/devicetree/bindings/leds/backlight/led-backlight.txt deleted file mode 100644 index 4c7dfbe7f67a..000000000000 --- a/Documentation/devicetree/bindings/leds/backlight/led-backlight.txt +++ /dev/null @@ -1,28 +0,0 @@ -led-backlight bindings - -This binding is used to describe a basic backlight device made of LEDs. -It can also be used to describe a backlight device controlled by the output of -a LED driver. - -Required properties: - - compatible: "led-backlight" - - leds: a list of LEDs - -Optional properties: - - brightness-levels: Array of distinct brightness levels. The levels must be - in the range accepted by the underlying LED devices. - This is used to translate a backlight brightness level - into a LED brightness level. If it is not provided, the - identity mapping is used. - - - default-brightness-level: The default brightness level. - -Example: - - backlight { - compatible = "led-backlight"; - - leds = <&led1>, <&led2>; - brightness-levels = <0 4 8 16 32 64 128 255>; - default-brightness-level = <6>; - }; diff --git a/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml new file mode 100644 index 000000000000..625082bf3892 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/backlight/led-backlight.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: led-backlight bindings + +maintainers: + - Lee Jones <lee.jones@linaro.org> + - Daniel Thompson <daniel.thompson@linaro.org> + - Jingoo Han <jingoohan1@gmail.com> + +description: + This binding is used to describe a basic backlight device made of LEDs. It + can also be used to describe a backlight device controlled by the output of + a LED driver. + +properties: + compatible: + const: led-backlight + + leds: + description: A list of LED nodes + $ref: /schemas/types.yaml#/definitions/phandle-array + + brightness-levels: + description: + Array of distinct brightness levels. The levels must be in the range + accepted by the underlying LED devices. This is used to translate a + backlight brightness level into a LED brightness level. If it is not + provided, the identity mapping is used. + $ref: /schemas/types.yaml#/definitions/uint32-array + + default-brightness-level: + description: + The default brightness level (index into the array defined by the + "brightness-levels" property). + $ref: /schemas/types.yaml#/definitions/uint32 + +required: + - compatible + - leds + +additionalProperties: false + +examples: + - | + backlight { + compatible = "led-backlight"; + + leds = <&led1>, <&led2>; + brightness-levels = <0 4 8 16 32 64 128 255>; + default-brightness-level = <6>; + }; + +... diff --git a/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.txt b/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.txt deleted file mode 100644 index 64fa2fbd98c9..000000000000 --- a/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.txt +++ /dev/null @@ -1,61 +0,0 @@ -pwm-backlight bindings - -Required properties: - - compatible: "pwm-backlight" - - pwms: OF device-tree PWM specification (see PWM binding[0]) - - power-supply: regulator for supply voltage - -Optional properties: - - pwm-names: a list of names for the PWM devices specified in the - "pwms" property (see PWM binding[0]) - - enable-gpios: contains a single GPIO specifier for the GPIO which enables - and disables the backlight (see GPIO binding[1]) - - post-pwm-on-delay-ms: Delay in ms between setting an initial (non-zero) PWM - and enabling the backlight using GPIO. - - pwm-off-delay-ms: Delay in ms between disabling the backlight using GPIO - and setting PWM value to 0. - - brightness-levels: Array of distinct brightness levels. Typically these - are in the range from 0 to 255, but any range starting at - 0 will do. The actual brightness level (PWM duty cycle) - will be interpolated from these values. 0 means a 0% duty - cycle (darkest/off), while the last value in the array - represents a 100% duty cycle (brightest). - - default-brightness-level: The default brightness level (index into the - array defined by the "brightness-levels" property). - - num-interpolated-steps: Number of interpolated steps between each value - of brightness-levels table. This way a high - resolution pwm duty cycle can be used without - having to list out every possible value in the - brightness-level array. - -[0]: Documentation/devicetree/bindings/pwm/pwm.txt -[1]: Documentation/devicetree/bindings/gpio/gpio.txt - -Example: - - backlight { - compatible = "pwm-backlight"; - pwms = <&pwm 0 5000000>; - - brightness-levels = <0 4 8 16 32 64 128 255>; - default-brightness-level = <6>; - - power-supply = <&vdd_bl_reg>; - enable-gpios = <&gpio 58 0>; - post-pwm-on-delay-ms = <10>; - pwm-off-delay-ms = <10>; - }; - -Example using num-interpolation-steps: - - backlight { - compatible = "pwm-backlight"; - pwms = <&pwm 0 5000000>; - - brightness-levels = <0 2048 4096 8192 16384 65535>; - num-interpolated-steps = <2048>; - default-brightness-level = <4096>; - - power-supply = <&vdd_bl_reg>; - enable-gpios = <&gpio 58 0>; - }; diff --git a/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml new file mode 100644 index 000000000000..fcb8429f3088 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml @@ -0,0 +1,104 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/backlight/pwm-backlight.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: pwm-backlight bindings + +maintainers: + - Lee Jones <lee.jones@linaro.org> + - Daniel Thompson <daniel.thompson@linaro.org> + - Jingoo Han <jingoohan1@gmail.com> + +properties: + compatible: + const: pwm-backlight + + pwms: + maxItems: 1 + + pwm-names: true + + power-supply: + description: regulator for supply voltage + + enable-gpios: + description: + Contains a single GPIO specifier for the GPIO which enables and disables + the backlight. + maxItems: 1 + + post-pwm-on-delay-ms: + description: + Delay in ms between setting an initial (non-zero) PWM and enabling the + backlight using GPIO. + + pwm-off-delay-ms: + description: + Delay in ms between disabling the backlight using GPIO and setting PWM + value to 0. + + brightness-levels: + description: + Array of distinct brightness levels. Typically these are in the range + from 0 to 255, but any range starting at 0 will do. The actual brightness + level (PWM duty cycle) will be interpolated from these values. 0 means a + 0% duty cycle (darkest/off), while the last value in the array represents + a 100% duty cycle (brightest). + $ref: /schemas/types.yaml#/definitions/uint32-array + + default-brightness-level: + description: + The default brightness level (index into the array defined by the + "brightness-levels" property). + $ref: /schemas/types.yaml#/definitions/uint32 + + num-interpolated-steps: + description: + Number of interpolated steps between each value of brightness-levels + table. This way a high resolution pwm duty cycle can be used without + having to list out every possible value in the brightness-level array. + $ref: /schemas/types.yaml#/definitions/uint32 + +dependencies: + default-brightness-level: [brightness-levels] + num-interpolated-steps: [brightness-levels] + +required: + - compatible + - pwms + - power-supply + +additionalProperties: false + +examples: + - | + backlight { + compatible = "pwm-backlight"; + pwms = <&pwm 0 5000000>; + + brightness-levels = <0 4 8 16 32 64 128 255>; + default-brightness-level = <6>; + + power-supply = <&vdd_bl_reg>; + enable-gpios = <&gpio 58 0>; + post-pwm-on-delay-ms = <10>; + pwm-off-delay-ms = <10>; + }; + + - | + // Example using num-interpolation-steps: + backlight { + compatible = "pwm-backlight"; + pwms = <&pwm 0 5000000>; + + brightness-levels = <0 2048 4096 8192 16384 65535>; + num-interpolated-steps = <2048>; + default-brightness-level = <4096>; + + power-supply = <&vdd_bl_reg>; + enable-gpios = <&gpio 58 0>; + }; + +... diff --git a/Documentation/devicetree/bindings/leds/cznic,turris-omnia-leds.yaml b/Documentation/devicetree/bindings/leds/cznic,turris-omnia-leds.yaml new file mode 100644 index 000000000000..24ad1446445e --- /dev/null +++ b/Documentation/devicetree/bindings/leds/cznic,turris-omnia-leds.yaml @@ -0,0 +1,90 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/cznic,turris-omnia-leds.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: CZ.NIC's Turris Omnia LEDs driver + +maintainers: + - Marek Behún <marek.behun@nic.cz> + +description: + This module adds support for the RGB LEDs found on the front panel of the + Turris Omnia router. There are 12 RGB LEDs that are controlled by a + microcontroller that communicates via the I2C bus. Each LED is described + as a subnode of this I2C device. + +properties: + compatible: + const: cznic,turris-omnia-leds + + reg: + description: I2C slave address of the microcontroller. + maxItems: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + +patternProperties: + "^multi-led[0-9a-f]$": + type: object + allOf: + - $ref: leds-class-multicolor.yaml# + description: + This node represents one of the RGB LED devices on Turris Omnia. + No subnodes need to be added for subchannels since this controller only + supports RGB LEDs. + + properties: + reg: + minimum: 0 + maximum: 11 + description: + This property identifies one of the LEDs on the front panel of the + Turris Omnia router. + + required: + - reg + +additionalProperties: false + +examples: + - | + + #include <dt-bindings/leds/common.h> + + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + led-controller@2b { + compatible = "cznic,turris-omnia-leds"; + reg = <0x2b>; + #address-cells = <1>; + #size-cells = <0>; + + multi-led@0 { + /* + * No subnodes are needed, this controller only supports RGB + * LEDs. + */ + reg = <0>; + color = <LED_COLOR_ID_MULTI>; + function = LED_FUNCTION_POWER; + linux,default-trigger = "heartbeat"; + }; + + multi-led@a { + reg = <0xa>; + color = <LED_COLOR_ID_MULTI>; + function = LED_FUNCTION_INDICATOR; + function-enumerator = <1>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/leds/leds-class-multicolor.yaml b/Documentation/devicetree/bindings/leds/leds-class-multicolor.yaml new file mode 100644 index 000000000000..b55e1f1308a4 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-class-multicolor.yaml @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/leds-class-multicolor.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Common properties for the multicolor LED class. + +maintainers: + - Dan Murphy <dmurphy@ti.com> + +description: | + Bindings for multi color LEDs show how to describe current outputs of + either integrated multi-color LED elements (like RGB, RGBW, RGBWA-UV + etc.) or standalone LEDs, to achieve logically grouped multi-color LED + modules. This is achieved by adding multi-led nodes layer to the + monochrome LED bindings. + The nodes and properties defined in this document are unique to the multicolor + LED class. Common LED nodes and properties are inherited from the common.txt + within this documentation directory. + +patternProperties: + "^multi-led@([0-9a-f])$": + type: object + description: Represents the LEDs that are to be grouped. + properties: + color: + const: 8 # LED_COLOR_ID_MULTI + description: | + For multicolor LED support this property should be defined as + LED_COLOR_ID_MULTI which can be found in include/linux/leds/common.h. + + $ref: "common.yaml#" + + required: + - color +... diff --git a/Documentation/devicetree/bindings/leds/leds-lm3532.txt b/Documentation/devicetree/bindings/leds/leds-lm3532.txt index 53793213dd52..097490a5ff91 100644 --- a/Documentation/devicetree/bindings/leds/leds-lm3532.txt +++ b/Documentation/devicetree/bindings/leds/leds-lm3532.txt @@ -102,4 +102,4 @@ led-controller@38 { }; For more product information please see the links below: -http://www.ti.com/product/LM3532 +https://www.ti.com/product/LM3532 diff --git a/Documentation/devicetree/bindings/leds/leds-lm3601x.txt b/Documentation/devicetree/bindings/leds/leds-lm3601x.txt index 095dafb6ec7f..17e940025dc2 100644 --- a/Documentation/devicetree/bindings/leds/leds-lm3601x.txt +++ b/Documentation/devicetree/bindings/leds/leds-lm3601x.txt @@ -47,5 +47,5 @@ led-controller@64 { } For more product information please see the links below: -http://www.ti.com/product/LM36010 -http://www.ti.com/product/LM36011 +https://www.ti.com/product/LM36010 +https://www.ti.com/product/LM36011 diff --git a/Documentation/devicetree/bindings/leds/leds-lm36274.txt b/Documentation/devicetree/bindings/leds/leds-lm36274.txt index 39c230d59a4d..de6f4931fb31 100644 --- a/Documentation/devicetree/bindings/leds/leds-lm36274.txt +++ b/Documentation/devicetree/bindings/leds/leds-lm36274.txt @@ -82,4 +82,4 @@ lm36274@11 { }; For more product information please see the link below: -http://www.ti.com/lit/ds/symlink/lm36274.pdf +https://www.ti.com/lit/ds/symlink/lm36274.pdf diff --git a/Documentation/devicetree/bindings/leds/leds-lm3692x.txt b/Documentation/devicetree/bindings/leds/leds-lm3692x.txt index 501468aa4d38..b1103d961d6c 100644 --- a/Documentation/devicetree/bindings/leds/leds-lm3692x.txt +++ b/Documentation/devicetree/bindings/leds/leds-lm3692x.txt @@ -62,4 +62,4 @@ led-controller@36 { } For more product information please see the link below: -http://www.ti.com/lit/ds/snvsa29/snvsa29.pdf +https://www.ti.com/lit/ds/snvsa29/snvsa29.pdf diff --git a/Documentation/devicetree/bindings/leds/leds-lm3697.txt b/Documentation/devicetree/bindings/leds/leds-lm3697.txt index 63992d732959..221b37b6049b 100644 --- a/Documentation/devicetree/bindings/leds/leds-lm3697.txt +++ b/Documentation/devicetree/bindings/leds/leds-lm3697.txt @@ -70,4 +70,4 @@ led-controller@36 { } For more product information please see the link below: -http://www.ti.com/lit/ds/symlink/lm3697.pdf +https://www.ti.com/lit/ds/symlink/lm3697.pdf diff --git a/Documentation/devicetree/bindings/leds/leds-lp55xx.txt b/Documentation/devicetree/bindings/leds/leds-lp55xx.txt deleted file mode 100644 index 1b66a413fb9d..000000000000 --- a/Documentation/devicetree/bindings/leds/leds-lp55xx.txt +++ /dev/null @@ -1,228 +0,0 @@ -Binding for TI/National Semiconductor LP55xx Led Drivers - -Required properties: -- compatible: one of - national,lp5521 - national,lp5523 - ti,lp55231 - ti,lp5562 - ti,lp8501 - -- reg: I2C slave address -- clock-mode: Input clock mode, (0: automode, 1: internal, 2: external) - -Each child has own specific current settings -- led-cur: Current setting at each led channel (mA x10, 0 if led is not connected) -- max-cur: Maximun current at each led channel. - -Optional properties: -- enable-gpio: GPIO attached to the chip's enable pin -- label: Used for naming LEDs -- pwr-sel: LP8501 specific property. Power selection for output channels. - 0: D1~9 are connected to VDD - 1: D1~6 with VDD, D7~9 with VOUT - 2: D1~6 with VOUT, D7~9 with VDD - 3: D1~9 are connected to VOUT - -Alternatively, each child can have a specific channel name and trigger: -- chan-name (optional): name of channel -- linux,default-trigger (optional): see - Documentation/devicetree/bindings/leds/common.txt - -example 1) LP5521 -3 LED channels, external clock used. Channel names are 'lp5521_pri:channel0', -'lp5521_pri:channel1' and 'lp5521_pri:channel2', with a heartbeat trigger -on channel 0. - -lp5521@32 { - compatible = "national,lp5521"; - reg = <0x32>; - label = "lp5521_pri"; - clock-mode = /bits/ 8 <2>; - - chan0 { - led-cur = /bits/ 8 <0x2f>; - max-cur = /bits/ 8 <0x5f>; - linux,default-trigger = "heartbeat"; - }; - - chan1 { - led-cur = /bits/ 8 <0x2f>; - max-cur = /bits/ 8 <0x5f>; - }; - - chan2 { - led-cur = /bits/ 8 <0x2f>; - max-cur = /bits/ 8 <0x5f>; - }; -}; - -example 2) LP5523 -9 LED channels with specific name. Internal clock used. -The I2C slave address is configurable with ASEL1 and ASEL0 pins. -Available addresses are 32/33/34/35h. - -ASEL1 ASEL0 Address -------------------------- - GND GND 32h - GND VEN 33h - VEN GND 34h - VEN VEN 35h - -lp5523@32 { - compatible = "national,lp5523"; - reg = <0x32>; - clock-mode = /bits/ 8 <1>; - - chan0 { - chan-name = "d1"; - led-cur = /bits/ 8 <0x14>; - max-cur = /bits/ 8 <0x20>; - }; - - chan1 { - chan-name = "d2"; - led-cur = /bits/ 8 <0x14>; - max-cur = /bits/ 8 <0x20>; - }; - - chan2 { - chan-name = "d3"; - led-cur = /bits/ 8 <0x14>; - max-cur = /bits/ 8 <0x20>; - }; - - chan3 { - chan-name = "d4"; - led-cur = /bits/ 8 <0x14>; - max-cur = /bits/ 8 <0x20>; - }; - - chan4 { - chan-name = "d5"; - led-cur = /bits/ 8 <0x14>; - max-cur = /bits/ 8 <0x20>; - }; - - chan5 { - chan-name = "d6"; - led-cur = /bits/ 8 <0x14>; - max-cur = /bits/ 8 <0x20>; - }; - - chan6 { - chan-name = "d7"; - led-cur = /bits/ 8 <0x14>; - max-cur = /bits/ 8 <0x20>; - }; - - chan7 { - chan-name = "d8"; - led-cur = /bits/ 8 <0x14>; - max-cur = /bits/ 8 <0x20>; - }; - - chan8 { - chan-name = "d9"; - led-cur = /bits/ 8 <0x14>; - max-cur = /bits/ 8 <0x20>; - }; -}; - -example 3) LP5562 -4 channels are defined. - -lp5562@30 { - compatible = "ti,lp5562"; - reg = <0x30>; - clock-mode = /bits/8 <2>; - - chan0 { - chan-name = "R"; - led-cur = /bits/ 8 <0x20>; - max-cur = /bits/ 8 <0x60>; - }; - - chan1 { - chan-name = "G"; - led-cur = /bits/ 8 <0x20>; - max-cur = /bits/ 8 <0x60>; - }; - - chan2 { - chan-name = "B"; - led-cur = /bits/ 8 <0x20>; - max-cur = /bits/ 8 <0x60>; - }; - - chan3 { - chan-name = "W"; - led-cur = /bits/ 8 <0x20>; - max-cur = /bits/ 8 <0x60>; - }; -}; - -example 4) LP8501 -9 channels are defined. The 'pwr-sel' is LP8501 specific property. -Others are same as LP5523. - -lp8501@32 { - compatible = "ti,lp8501"; - reg = <0x32>; - clock-mode = /bits/ 8 <2>; - pwr-sel = /bits/ 8 <3>; /* D1~9 connected to VOUT */ - - chan0 { - chan-name = "d1"; - led-cur = /bits/ 8 <0x14>; - max-cur = /bits/ 8 <0x20>; - }; - - chan1 { - chan-name = "d2"; - led-cur = /bits/ 8 <0x14>; - max-cur = /bits/ 8 <0x20>; - }; - - chan2 { - chan-name = "d3"; - led-cur = /bits/ 8 <0x14>; - max-cur = /bits/ 8 <0x20>; - }; - - chan3 { - chan-name = "d4"; - led-cur = /bits/ 8 <0x14>; - max-cur = /bits/ 8 <0x20>; - }; - - chan4 { - chan-name = "d5"; - led-cur = /bits/ 8 <0x14>; - max-cur = /bits/ 8 <0x20>; - }; - - chan5 { - chan-name = "d6"; - led-cur = /bits/ 8 <0x14>; - max-cur = /bits/ 8 <0x20>; - }; - - chan6 { - chan-name = "d7"; - led-cur = /bits/ 8 <0x14>; - max-cur = /bits/ 8 <0x20>; - }; - - chan7 { - chan-name = "d8"; - led-cur = /bits/ 8 <0x14>; - max-cur = /bits/ 8 <0x20>; - }; - - chan8 { - chan-name = "d9"; - led-cur = /bits/ 8 <0x14>; - max-cur = /bits/ 8 <0x20>; - }; -}; diff --git a/Documentation/devicetree/bindings/leds/leds-lp55xx.yaml b/Documentation/devicetree/bindings/leds/leds-lp55xx.yaml new file mode 100644 index 000000000000..b1bb3feb0f4d --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-lp55xx.yaml @@ -0,0 +1,220 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/leds-lp55xx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TI/National Semiconductor LP55xx and LP8501 LED Drivers + +maintainers: + - Jacek Anaszewski <jacek.anaszewski@gmail.com> + - Pavel Machek <pavel@ucw.cz> + +description: | + Bindings for the TI/National Semiconductor LP55xx and LP8501 multi channel + LED Drivers. + + For more product information please see the link below: + https://www.ti.com/lit/gpn/lp5521 + https://www.ti.com/lit/gpn/lp5523 + https://www.ti.com/lit/gpn/lp55231 + https://www.ti.com/lit/gpn/lp5562 + https://www.ti.com/lit/gpn/lp8501 + +properties: + compatible: + enum: + - national,lp5521 + - national,lp5523 + - ti,lp55231 + - ti,lp5562 + - ti,lp8501 + + reg: + maxItems: 1 + description: I2C slave address + + clock-mode: + $ref: /schemas/types.yaml#definitions/uint8 + description: | + Input clock mode + enum: + - 0 # automode + - 1 # internal + - 2 # external + + enable-gpio: + maxItems: 1 + description: | + GPIO attached to the chip's enable pin + + pwr-sel: + $ref: /schemas/types.yaml#definitions/uint8 + description: | + LP8501 specific property. Power selection for output channels. + enum: + - 0 # D1~9 are connected to VDD + - 1 # D1~6 with VDD, D7~9 with VOUT + - 2 # D1~6 with VOUT, D7~9 with VDD + - 3 # D1~9 are connected to VOUT + +patternProperties: + "(^led@[0-9a-f]$|led)": + type: object + $ref: common.yaml# + properties: + led-cur: + $ref: /schemas/types.yaml#definitions/uint8 + description: | + Current setting at each LED channel (mA x10, 0 if LED is not connected) + minimum: 0 + maximum: 255 + + max-cur: + $ref: /schemas/types.yaml#definitions/uint8 + description: Maximun current at each LED channel. + + reg: + description: | + Output channel for the LED. This is zero based channel identifier and + the data sheet is a one based channel identifier. + reg value to output to LED output number + enum: + - 0 # LED output D1 + - 1 # LED output D2 + - 2 # LED output D3 + - 3 # LED output D4 + - 4 # LED output D5 + - 5 # LED output D6 + - 6 # LED output D7 + - 7 # LED output D8 + - 8 # LED output D9 + + chan-name: + $ref: /schemas/types.yaml#definitions/string + description: name of channel + +required: + - compatible + - reg + +examples: + - | + #include <dt-bindings/leds/common.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + led-controller@32 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "ti,lp8501"; + reg = <0x32>; + clock-mode = /bits/ 8 <2>; + pwr-sel = /bits/ 8 <3>; /* D1~9 connected to VOUT */ + + led@0 { + reg = <0>; + chan-name = "d1"; + led-cur = /bits/ 8 <0x14>; + max-cur = /bits/ 8 <0x20>; + }; + + led@1 { + reg = <1>; + chan-name = "d2"; + led-cur = /bits/ 8 <0x14>; + max-cur = /bits/ 8 <0x20>; + }; + + led@2 { + reg = <2>; + chan-name = "d3"; + led-cur = /bits/ 8 <0x14>; + max-cur = /bits/ 8 <0x20>; + }; + + led@3 { + reg = <3>; + chan-name = "d4"; + led-cur = /bits/ 8 <0x14>; + max-cur = /bits/ 8 <0x20>; + }; + + led@4 { + reg = <4>; + chan-name = "d5"; + led-cur = /bits/ 8 <0x14>; + max-cur = /bits/ 8 <0x20>; + }; + + led@5 { + reg = <5>; + chan-name = "d6"; + led-cur = /bits/ 8 <0x14>; + max-cur = /bits/ 8 <0x20>; + }; + + led@6 { + reg = <6>; + chan-name = "d7"; + led-cur = /bits/ 8 <0x14>; + max-cur = /bits/ 8 <0x20>; + }; + + led@7 { + reg = <7>; + chan-name = "d8"; + led-cur = /bits/ 8 <0x14>; + max-cur = /bits/ 8 <0x20>; + }; + + led@8 { + reg = <8>; + chan-name = "d9"; + led-cur = /bits/ 8 <0x14>; + max-cur = /bits/ 8 <0x20>; + }; + }; + + led-controller@33 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "national,lp5523"; + reg = <0x33>; + clock-mode = /bits/ 8 <0>; + + multi-led@2 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0x2>; + color = <LED_COLOR_ID_MULTI>; + function = LED_FUNCTION_STANDBY; + linux,default-trigger = "heartbeat"; + + led@0 { + led-cur = /bits/ 8 <50>; + max-cur = /bits/ 8 <100>; + reg = <0x0>; + color = <LED_COLOR_ID_GREEN>; + }; + + led@1 { + led-cur = /bits/ 8 <50>; + max-cur = /bits/ 8 <100>; + reg = <0x1>; + color = <LED_COLOR_ID_BLUE>; + }; + + led@6 { + led-cur = /bits/ 8 <50>; + max-cur = /bits/ 8 <100>; + reg = <0x6>; + color = <LED_COLOR_ID_RED>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/leds/leds-lp8860.txt b/Documentation/devicetree/bindings/leds/leds-lp8860.txt index 9863220db4ba..8bb25749a3da 100644 --- a/Documentation/devicetree/bindings/leds/leds-lp8860.txt +++ b/Documentation/devicetree/bindings/leds/leds-lp8860.txt @@ -47,4 +47,4 @@ led-controller@2d { } For more product information please see the link below: -http://www.ti.com/product/lp8860-q1 +https://www.ti.com/product/lp8860-q1 diff --git a/Documentation/devicetree/bindings/leds/leds-pca955x.txt b/Documentation/devicetree/bindings/leds/leds-pca955x.txt index 7984efb767b4..7a5830f8d5ab 100644 --- a/Documentation/devicetree/bindings/leds/leds-pca955x.txt +++ b/Documentation/devicetree/bindings/leds/leds-pca955x.txt @@ -26,9 +26,9 @@ LED sub-node properties: from 0 to 15 for the pca9552 from 0 to 3 for the pca9553 - type: (optional) either - PCA9532_TYPE_NONE - PCA9532_TYPE_LED - PCA9532_TYPE_GPIO + PCA955X_TYPE_NONE + PCA955X_TYPE_LED + PCA955X_TYPE_GPIO see dt-bindings/leds/leds-pca955x.h (default to LED) - label : (optional) see Documentation/devicetree/bindings/leds/common.txt diff --git a/Documentation/devicetree/bindings/mailbox/mtk-gce.txt b/Documentation/devicetree/bindings/mailbox/mtk-gce.txt index 0b5b2a6bcc48..cf48cd806e00 100644 --- a/Documentation/devicetree/bindings/mailbox/mtk-gce.txt +++ b/Documentation/devicetree/bindings/mailbox/mtk-gce.txt @@ -9,7 +9,8 @@ CMDQ driver uses mailbox framework for communication. Please refer to mailbox.txt for generic information about mailbox device-tree bindings. Required properties: -- compatible: can be "mediatek,mt8173-gce" or "mediatek,mt8183-gce" +- compatible: can be "mediatek,mt8173-gce", "mediatek,mt8183-gce" or + "mediatek,mt6779-gce". - reg: Address range of the GCE unit - interrupts: The interrupt signal from the GCE block - clock: Clocks according to the common clock binding @@ -34,8 +35,9 @@ Optional properties for a client device: start_offset: the start offset of register address that GCE can access. size: the total size of register address that GCE can access. -Some vaules of properties are defined in 'dt-bindings/gce/mt8173-gce.h' -or 'dt-binding/gce/mt8183-gce.h'. Such as sub-system ids, thread priority, event ids. +Some vaules of properties are defined in 'dt-bindings/gce/mt8173-gce.h', +'dt-binding/gce/mt8183-gce.h' or 'dt-bindings/gce/mt6779-gce.h'. Such as +sub-system ids, thread priority, event ids. Example: diff --git a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml index 12eff942708d..8f810fc5c183 100644 --- a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml +++ b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml @@ -18,10 +18,12 @@ properties: enum: - qcom,ipq8074-apcs-apps-global - qcom,msm8916-apcs-kpss-global + - qcom,msm8994-apcs-kpss-global - qcom,msm8996-apcs-hmss-global - qcom,msm8998-apcs-hmss-global - qcom,qcs404-apcs-apps-global - qcom,sc7180-apss-shared + - qcom,sdm660-apcs-hmss-global - qcom,sdm845-apss-shared - qcom,sm8150-apss-shared diff --git a/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.txt b/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.txt index 4438432bfe9b..ad76edccf881 100644 --- a/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.txt +++ b/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.txt @@ -87,7 +87,7 @@ Example: ranges; /* APU<->RPU0 IPI mailbox controller */ - ipi_mailbox_rpu0: mailbox@ff90400 { + ipi_mailbox_rpu0: mailbox@ff990400 { reg = <0xff990400 0x20>, <0xff990420 0x20>, <0xff990080 0x20>, diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml index 526593c8c614..4cc1a670c986 100644 --- a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml +++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-video-engine.yaml @@ -47,6 +47,9 @@ properties: $ref: /schemas/types.yaml#/definitions/phandle-array description: Phandle to the device SRAM + iommus: + maxItems: 1 + memory-region: description: CMA pool to use for buffers allocation instead of the default diff --git a/Documentation/devicetree/bindings/media/i2c/adv7180.txt b/Documentation/devicetree/bindings/media/i2c/adv7180.txt deleted file mode 100644 index 552b6a82cb1f..000000000000 --- a/Documentation/devicetree/bindings/media/i2c/adv7180.txt +++ /dev/null @@ -1,49 +0,0 @@ -* Analog Devices ADV7180 analog video decoder family - -The adv7180 family devices are used to capture analog video to different -digital interfaces like MIPI CSI-2 or parallel video. - -Required Properties : -- compatible : value must be one of - "adi,adv7180" - "adi,adv7180cp" - "adi,adv7180st" - "adi,adv7182" - "adi,adv7280" - "adi,adv7280-m" - "adi,adv7281" - "adi,adv7281-m" - "adi,adv7281-ma" - "adi,adv7282" - "adi,adv7282-m" - -Device nodes of "adi,adv7180cp" and "adi,adv7180st" must contain one -'port' child node per device input and output port, in accordance with the -video interface bindings defined in -Documentation/devicetree/bindings/media/video-interfaces.txt. The port -nodes are numbered as follows. - - Port adv7180cp adv7180st -------------------------------------------------------------------- - Input 0-2 0-5 - Output 3 6 - -The digital output port node must contain at least one endpoint. - -Optional Properties : -- powerdown-gpios: reference to the GPIO connected to the powerdown pin, - if any. - - -Example: - - i2c0@1c22000 { - ... - ... - adv7180@21 { - compatible = "adi,adv7180"; - reg = <0x21>; - }; - ... - }; - diff --git a/Documentation/devicetree/bindings/media/i2c/adv7180.yaml b/Documentation/devicetree/bindings/media/i2c/adv7180.yaml new file mode 100644 index 000000000000..e0084b272b25 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/adv7180.yaml @@ -0,0 +1,184 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/adv7180.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices ADV7180 analog video decoder family + +maintainers: + - Lars-Peter Clausen <lars@metafoo.de> + +description: + The adv7180 family devices are used to capture analog video to different + digital interfaces like MIPI CSI-2 or parallel video. + +properties: + compatible: + items: + - enum: + - adi,adv7180 + - adi,adv7180cp + - adi,adv7180st + - adi,adv7182 + - adi,adv7280 + - adi,adv7280-m + - adi,adv7281 + - adi,adv7281-m + - adi,adv7281-ma + - adi,adv7282 + - adi,adv7282-m + + reg: + maxItems: 1 + + powerdown-gpios: + maxItems: 1 + + port: + type: object + description: + A node containing a single endpoint as doucmented in + Documentation/devicetree/bindings/media/video-interfaces.txt + + ports: + type: object + description: + A node containing input and output port nodes with endpoint definitions + as documented in + Documentation/devicetree/bindings/media/video-interfaces.txt + +additionalProperties: false + +required: + - compatible + - reg + +allOf: + - if: + properties: + compatible: + items: + - enum: + - adi,adv7180 + - adi,adv7182 + - adi,adv7280 + - adi,adv7280-m + - adi,adv7281 + - adi,adv7281-m + - adi,adv7281-ma + - adi,adv7282 + - adi,adv7282-m + then: + required: + - port + + - if: + properties: + compatible: + contains: + const: adi,adv7180cp + then: + properties: + ports: + properties: + '#address-cells': + const: 1 + '#size-cells': + const: 0 + port@3: + type: object + description: Output port + + patternProperties: + "^port@[0-2]$": + type: object + description: Input port + + required: + - port@3 + + additionalProperties: false + + required: + - ports + + - if: + properties: + compatible: + contains: + const: adi,adv7180st + then: + properties: + ports: + properties: + '#address-cells': + const: 1 + '#size-cells': + const: 0 + port@6: + type: object + description: Output port + + patternProperties: + "^port@[0-5]$": + type: object + description: Input port + + required: + - port@6 + + additionalProperties: false + + required: + - ports + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + composite-in@20 { + compatible = "adi,adv7180"; + reg = <0x20>; + + port { + adv7180: endpoint { + bus-width = <8>; + remote-endpoint = <&vin1ep>; + }; + }; + }; + + }; + + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + composite-in@20 { + compatible = "adi,adv7180cp"; + reg = <0x20>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + adv7180_in: endpoint { + remote-endpoint = <&composite_con_in>; + }; + }; + + port@3 { + reg = <3>; + adv7180_out: endpoint { + remote-endpoint = <&vin4_in>; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/i2c/chrontel,ch7322.yaml b/Documentation/devicetree/bindings/media/i2c/chrontel,ch7322.yaml new file mode 100644 index 000000000000..daa2869377c5 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/chrontel,ch7322.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/media/i2c/chrontel,ch7322.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Chrontel HDMI-CEC Controller + +maintainers: + - Jeff Chase <jnchase@google.com> + +description: + The Chrontel CH7322 is a discrete HDMI-CEC controller. It is + programmable through I2C and drives a single CEC line. + +properties: + compatible: + const: chrontel,ch7322 + + reg: + description: I2C device address + maxItems: 1 + + clocks: + maxItems: 1 + + interrupts: + maxItems: 1 + + reset-gpios: + description: + Reference to the GPIO connected to the RESET pin, if any. This + pin is active-low. + maxItems: 1 + + standby-gpios: + description: + Reference to the GPIO connected to the OE pin, if any. When low + the device will respond to power status requests with "standby" + if in auto mode. + maxItems: 1 + + # see ../cec.txt + hdmi-phandle: + description: phandle to the HDMI controller + +required: + - compatible + - reg + - interrupts + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + ch7322@75 { + compatible = "chrontel,ch7322"; + reg = <0x75>; + interrupts = <47 IRQ_TYPE_EDGE_RISING>; + standby-gpios = <&gpio 16 GPIO_ACTIVE_LOW>; + reset-gpios = <&gpio 15 GPIO_ACTIVE_LOW>; + hdmi-phandle = <&hdmi>; + }; + }; diff --git a/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9768.yaml b/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9768.yaml new file mode 100644 index 000000000000..cb96e95d7e81 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9768.yaml @@ -0,0 +1,100 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright (c) 2020 MediaTek Inc. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/dongwoon,dw9768.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Dongwoon Anatech DW9768 Voice Coil Motor (VCM) Lens Device Tree Bindings + +maintainers: + - Dongchun Zhu <dongchun.zhu@mediatek.com> + +description: |- + The Dongwoon DW9768 is a single 10-bit digital-to-analog (DAC) converter + with 100 mA output current sink capability. VCM current is controlled with + a linear mode driver. The DAC is controlled via a 2-wire (I2C-compatible) + serial interface that operates at clock rates up to 1MHz. This chip + integrates Advanced Actuator Control (AAC) technology and is intended for + driving voice coil lenses in camera modules. + +properties: + compatible: + enum: + - dongwoon,dw9768 # for DW9768 VCM + - giantec,gt9769 # for GT9769 VCM + + reg: + maxItems: 1 + + vin-supply: + description: + Definition of the regulator used as Digital I/O voltage supply. + + vdd-supply: + description: + Definition of the regulator used as Digital core voltage supply. + + dongwoon,aac-mode: + description: + Indication of AAC mode select. + allOf: + - $ref: "/schemas/types.yaml#/definitions/uint32" + - enum: + - 1 # AAC2 mode(operation time# 0.48 x Tvib) + - 2 # AAC3 mode(operation time# 0.70 x Tvib) + - 3 # AAC4 mode(operation time# 0.75 x Tvib) + - 5 # AAC8 mode(operation time# 1.13 x Tvib) + default: 2 + + dongwoon,aac-timing: + description: + Number of AAC Timing count that controlled by one 6-bit period of + vibration register AACT[5:0], the unit of which is 100 us. + allOf: + - $ref: "/schemas/types.yaml#/definitions/uint32" + - default: 0x20 + minimum: 0x00 + maximum: 0x3f + + dongwoon,clock-presc: + description: + Indication of VCM internal clock dividing rate select, as one multiple + factor to calculate VCM ring periodic time Tvib. + allOf: + - $ref: "/schemas/types.yaml#/definitions/uint32" + - enum: + - 0 # Dividing Rate - 2 + - 1 # Dividing Rate - 1 + - 2 # Dividing Rate - 1/2 + - 3 # Dividing Rate - 1/4 + - 4 # Dividing Rate - 8 + - 5 # Dividing Rate - 4 + default: 1 + +required: + - compatible + - reg + - vin-supply + - vdd-supply + +additionalProperties: false + +examples: + - | + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + dw9768: camera-lens@c { + compatible = "dongwoon,dw9768"; + reg = <0x0c>; + + vin-supply = <&mt6358_vcamio_reg>; + vdd-supply = <&mt6358_vcama2_reg>; + dongwoon,aac-timing = <0x39>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/media/i2c/imi,rdacm2x-gmsl.yaml b/Documentation/devicetree/bindings/media/i2c/imi,rdacm2x-gmsl.yaml new file mode 100644 index 000000000000..5ad4b8c356cf --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/imi,rdacm2x-gmsl.yaml @@ -0,0 +1,159 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +# Copyright (C) 2019 Renesas Electronics Corp. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/imi,rdacm2x-gmsl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: IMI D&D RDACM20 and RDACM21 Automotive Camera Platforms + +maintainers: + - Jacopo Mondi <jacopo+renesas@jmondi.org> + - Kieran Bingham <kieran.bingham+renesas@ideasonboard.com> + - Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> + - Niklas Söderlund <niklas.soderlund+renesas@ragnatech.se> + +description: -| + The IMI D&D RDACM20 and RDACM21 are GMSL-compatible camera designed for + automotive applications. + + The RDACM20 camera module encloses a Maxim Integrated MAX9271 GMSL serializer, + coupled with an OV10635 image sensor and an embedded MCU. Both the MCU and + the image sensor are connected to the serializer local I2C bus and are + accessible by the host SoC by direct addressing. + + The RDACM21 camera module encloses the same serializer, coupled with an + OV10640 image sensor and an OV490 ISP. Only the OV490 ISP is interfaced to + the serializer local I2C bus while the image sensor is not accessible from + the host SoC. + + They both connect to a remote GMSL endpoint through a coaxial cable. + + IMI RDACM20 + +---------------+ +--------------------------------+ + | GMSL | <- Video Stream | <- Video--------\ | + | |< === GMSL Link ====== >|MAX9271<- I2C bus-> <-->OV10635 | + | de-serializer | <- I2C messages -> | \<-->MCU | + +---------------+ +--------------------------------+ + + IMI RDACM21 + +---------------+ +--------------------------------+ + | GMSL | <- Video Stream | <- Video--------\ | + | |< === GMSL Link ====== >|MAX9271<- I2C bus-> <-->OV490 | + | | <- I2C messages -> | | | + | de-serializer | | OV10640 <-------| | + +---------------+ +--------------------------------+ + + Both camera modules serialize video data generated by the embedded camera + sensor on the GMSL serial channel to a remote GMSL de-serializer. They also + receive and transmit I2C messages encapsulated and transmitted on the GMSL + bidirectional control channel. + + All I2C traffic received on the GMSL link not directed to the serializer is + propagated on the local I2C bus to the remote device there connected. All the + I2C traffic generated on the local I2C bus not directed to the serializer is + propagated to the remote de-serializer encapsulated in the GMSL control + channel. + + The RDACM20 and RDACM21 DT node should be a direct child of the GMSL + deserializer's I2C bus corresponding to the GMSL link that the camera is + attached to. + +properties: + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + compatible: + enum: + - imi,rdacm20 + - imi,rdacm21 + + reg: + description: -| + I2C device addresses, the first to be assigned to the serializer, the + following ones to be assigned to the remote devices. + + For RDACM20 the second entry of the property is assigned to the + OV10635 image sensor and the optional third one to the embedded MCU. + + For RDACM21 the second entry is assigned to the OV490 ISP and the optional + third one ignored. + + minItems: 2 + maxItems: 3 + + port: + type: object + additionalProperties: false + description: -| + Connection to the remote GMSL endpoint are modelled using the OF graph + bindings in accordance with the video interface bindings defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. + + The device node contains a single "port" child node with a single + "endpoint" sub-device. + + properties: + endpoint: + type: object + additionalProperties: false + + properties: + remote-endpoint: + description: -| + phandle to the remote GMSL endpoint sub-node in the remote node + port. + maxItems: 1 + + required: + - remote-endpoint + + required: + - endpoint + +required: + - compatible + - reg + - port + +examples: + - | + i2c@e66d8000 { + #address-cells = <1>; + #size-cells = <0>; + + reg = <0 0xe66d8000>; + + camera@31 { + compatible = "imi,rdacm20"; + reg = <0x31>, <0x41>, <0x51>; + + port { + rdacm20_out0: endpoint { + remote-endpoint = <&max9286_in0>; + }; + }; + }; + }; + + - | + i2c@e66d8000 { + #address-cells = <1>; + #size-cells = <0>; + + reg = <0 0xe66d8000>; + + camera@31 { + compatible = "imi,rdacm21"; + reg = <0x31>, <0x41>; + + port { + rdacm21_out0: endpoint { + remote-endpoint = <&max9286_in0>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/i2c/imx274.txt b/Documentation/devicetree/bindings/media/i2c/imx274.txt index 80f2e89568e1..0727079d2410 100644 --- a/Documentation/devicetree/bindings/media/i2c/imx274.txt +++ b/Documentation/devicetree/bindings/media/i2c/imx274.txt @@ -13,6 +13,11 @@ Required Properties: Optional Properties: - reset-gpios: Sensor reset GPIO +- clocks: Reference to the input clock. +- clock-names: Should be "inck". +- VANA-supply: Sensor 2.8v analog supply. +- VDIG-supply: Sensor 1.8v digital core supply. +- VDDL-supply: Sensor digital IO 1.2v supply. The imx274 device node should contain one 'port' child node with an 'endpoint' subnode. For further reading on port node refer to diff --git a/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml b/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml new file mode 100644 index 000000000000..e7b543159d15 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml @@ -0,0 +1,366 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2019 Renesas Electronics Corp. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/maxim,max9286.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim Integrated Quad GMSL Deserializer + +maintainers: + - Jacopo Mondi <jacopo+renesas@jmondi.org> + - Kieran Bingham <kieran.bingham+renesas@ideasonboard.com> + - Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> + - Niklas Söderlund <niklas.soderlund+renesas@ragnatech.se> + +description: | + The MAX9286 deserializer receives video data on up to 4 Gigabit Multimedia + Serial Links (GMSL) and outputs them on a CSI-2 D-PHY port using up to 4 data + lanes. + + In addition to video data, the GMSL links carry a bidirectional control + channel that encapsulates I2C messages. The MAX9286 forwards all I2C traffic + not addressed to itself to the other side of the links, where a GMSL + serializer will output it on a local I2C bus. In the other direction all I2C + traffic received over GMSL by the MAX9286 is output on the local I2C bus. + +properties: + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + compatible: + const: maxim,max9286 + + reg: + description: I2C device address + maxItems: 1 + + poc-supply: + description: Regulator providing Power over Coax to the cameras + maxItems: 1 + + enable-gpios: + description: GPIO connected to the \#PWDN pin with inverted polarity + maxItems: 1 + + gpio-controller: true + + '#gpio-cells': + const: 2 + + ports: + type: object + description: | + The connections to the MAX9286 GMSL and its endpoint nodes are modelled + using the OF graph bindings in accordance with the video interface + bindings defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. + + The following table lists the port number corresponding to each device + port. + + Port Description + ---------------------------------------- + Port 0 GMSL Input 0 + Port 1 GMSL Input 1 + Port 2 GMSL Input 2 + Port 3 GMSL Input 3 + Port 4 CSI-2 Output + + properties: + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + port@[0-3]: + type: object + properties: + reg: + enum: [ 0, 1, 2, 3 ] + + endpoint: + type: object + + properties: + remote-endpoint: + description: | + phandle to the remote GMSL source endpoint subnode in the + remote node port. + + required: + - remote-endpoint + + required: + - reg + - endpoint + + additionalProperties: false + + port@4: + type: object + properties: + reg: + const: 4 + + endpoint: + type: object + + properties: + remote-endpoint: + description: phandle to the remote CSI-2 sink endpoint. + + data-lanes: + description: array of physical CSI-2 data lane indexes. + + required: + - remote-endpoint + - data-lanes + + required: + - reg + - endpoint + + additionalProperties: false + + required: + - port@4 + + i2c-mux: + type: object + description: | + Each GMSL link is modelled as a child bus of an i2c bus + multiplexer/switch, in accordance with bindings described in + Documentation/devicetree/bindings/i2c/i2c-mux.txt. + + properties: + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + patternProperties: + "^i2c@[0-3]$": + type: object + description: | + Child node of the i2c bus multiplexer which represents a GMSL link. + Each serializer device on the GMSL link remote end is represented with + an i2c-mux child node. The MAX9286 chip supports up to 4 GMSL + channels. + + properties: + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + reg: + description: The index of the GMSL channel. + maxItems: 1 + + patternProperties: + "^camera@[a-f0-9]+$": + type: object + description: | + The remote camera device, composed by a GMSL serializer and a + connected video source. + + properties: + compatible: + description: The remote device compatible string. + + reg: + minItems: 2 + maxItems: 3 + description: | + The I2C addresses to be assigned to the remote devices through + address reprogramming. The number of entries depends on the + requirements of the currently connected remote device. + + port: + type: object + + properties: + endpoint: + type: object + + properties: + remote-endpoint: + description: phandle to the MAX9286 sink endpoint. + + required: + - remote-endpoint + + additionalProperties: false + + required: + - endpoint + + additionalProperties: false + + required: + - compatible + - reg + - port + + additionalProperties: false + + additionalProperties: false + + additionalProperties: false + +required: + - compatible + - reg + - ports + - i2c-mux + - gpio-controller + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c@e66d8000 { + #address-cells = <1>; + #size-cells = <0>; + + reg = <0 0xe66d8000>; + + gmsl-deserializer@2c { + compatible = "maxim,max9286"; + reg = <0x2c>; + poc-supply = <&camera_poc_12v>; + enable-gpios = <&gpio 13 GPIO_ACTIVE_HIGH>; + + gpio-controller; + #gpio-cells = <2>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + max9286_in0: endpoint { + remote-endpoint = <&rdacm20_out0>; + }; + }; + + port@1 { + reg = <1>; + + max9286_in1: endpoint { + remote-endpoint = <&rdacm20_out1>; + }; + }; + + port@2 { + reg = <2>; + + max9286_in2: endpoint { + remote-endpoint = <&rdacm20_out2>; + }; + }; + + port@3 { + reg = <3>; + + max9286_in3: endpoint { + remote-endpoint = <&rdacm20_out3>; + }; + }; + + port@4 { + reg = <4>; + + max9286_out: endpoint { + data-lanes = <1 2 3 4>; + remote-endpoint = <&csi40_in>; + }; + }; + }; + + i2c-mux { + #address-cells = <1>; + #size-cells = <0>; + + i2c@0 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0>; + + camera@51 { + compatible = "imi,rdacm20"; + reg = <0x51>, <0x61>; + + port { + rdacm20_out0: endpoint { + remote-endpoint = <&max9286_in0>; + }; + }; + + }; + }; + + i2c@1 { + #address-cells = <1>; + #size-cells = <0>; + reg = <1>; + + camera@52 { + compatible = "imi,rdacm20"; + reg = <0x52>, <0x62>; + + port { + rdacm20_out1: endpoint { + remote-endpoint = <&max9286_in1>; + }; + }; + }; + }; + + i2c@2 { + #address-cells = <1>; + #size-cells = <0>; + reg = <2>; + + camera@53 { + compatible = "imi,rdacm20"; + reg = <0x53>, <0x63>; + + port { + rdacm20_out2: endpoint { + remote-endpoint = <&max9286_in2>; + }; + }; + }; + }; + + i2c@3 { + #address-cells = <1>; + #size-cells = <0>; + reg = <3>; + + camera@54 { + compatible = "imi,rdacm20"; + reg = <0x54>, <0x64>; + + port { + rdacm20_out3: endpoint { + remote-endpoint = <&max9286_in3>; + }; + }; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/renesas,fcp.txt b/Documentation/devicetree/bindings/media/renesas,fcp.txt deleted file mode 100644 index 79c37395b396..000000000000 --- a/Documentation/devicetree/bindings/media/renesas,fcp.txt +++ /dev/null @@ -1,34 +0,0 @@ -Renesas R-Car Frame Compression Processor (FCP) ------------------------------------------------ - -The FCP is a companion module of video processing modules in the Renesas R-Car -Gen3 and RZ/G2 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 and FCPF. - - - compatible: Must be one or more of the following - - - "renesas,fcpv" for generic compatible 'FCP for VSP' - - "renesas,fcpf" for generic compatible 'FCP for FDP' - - - reg: the register base and size for the device registers - - clocks: Reference to the functional clock - -Optional properties: - - power-domains : power-domain property defined with a power domain specifier - to respective power domain. - - -Device node example -------------------- - - fcpvd1: fcp@fea2f000 { - compatible = "renesas,fcpv"; - reg = <0 0xfea2f000 0 0x200>; - clocks = <&cpg CPG_MOD 602>; - power-domains = <&sysc R8A7795_PD_A3VP>; - }; diff --git a/Documentation/devicetree/bindings/media/renesas,fcp.yaml b/Documentation/devicetree/bindings/media/renesas,fcp.yaml new file mode 100644 index 000000000000..43f2fed8cd33 --- /dev/null +++ b/Documentation/devicetree/bindings/media/renesas,fcp.yaml @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/renesas,fcp.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car Frame Compression Processor (FCP) + +maintainers: + - Laurent Pinchart <laurent.pinchart@ideasonboard.com> + +description: | + The FCP is a companion module of video processing modules in the Renesas + R-Car Gen3 and RZ/G2 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 and FCPF. + +properties: + compatible: + enum: + - renesas,fcpv # FCP for VSP + - renesas,fcpf # FCP for FDP + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + iommus: + maxItems: 1 + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - power-domains + - resets + +additionalProperties: false + +examples: + # R8A7795 (R-Car H3) FCP for VSP-D1 + - | + #include <dt-bindings/clock/renesas-cpg-mssr.h> + #include <dt-bindings/power/r8a7795-sysc.h> + + fcp@fea2f000 { + compatible = "renesas,fcpv"; + reg = <0xfea2f000 0x200>; + clocks = <&cpg CPG_MOD 602>; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + resets = <&cpg 602>; + iommus = <&ipmmu_vi0 9>; + }; +... diff --git a/Documentation/devicetree/bindings/media/renesas,fdp1.txt b/Documentation/devicetree/bindings/media/renesas,fdp1.txt deleted file mode 100644 index 8dd1007bb573..000000000000 --- a/Documentation/devicetree/bindings/media/renesas,fdp1.txt +++ /dev/null @@ -1,37 +0,0 @@ -Renesas R-Car Fine Display Processor (FDP1) -------------------------------------------- - -The FDP1 is a de-interlacing module which converts interlaced video to -progressive video. It is capable of performing pixel format conversion between -YCbCr/YUV formats and RGB formats. Only YCbCr/YUV formats are supported as -an input to the module. - -Required properties: - - - compatible: must be "renesas,fdp1" - - reg: the register base and size for the device registers - - interrupts : interrupt specifier for the FDP1 instance - - clocks: reference to the functional clock - -Optional properties: - - - power-domains: reference to the power domain that the FDP1 belongs to, if - any. - - renesas,fcp: a phandle referencing the FCP that handles memory accesses - for the FDP1. Not needed on Gen2, mandatory on Gen3. - -Please refer to the binding documentation for the clock and/or power domain -providers for more details. - - -Device node example -------------------- - - fdp1@fe940000 { - compatible = "renesas,fdp1"; - reg = <0 0xfe940000 0 0x2400>; - interrupts = <GIC_SPI 262 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 119>; - power-domains = <&sysc R8A7795_PD_A3VP>; - renesas,fcp = <&fcpf0>; - }; diff --git a/Documentation/devicetree/bindings/media/renesas,fdp1.yaml b/Documentation/devicetree/bindings/media/renesas,fdp1.yaml new file mode 100644 index 000000000000..2a27a7296fea --- /dev/null +++ b/Documentation/devicetree/bindings/media/renesas,fdp1.yaml @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/renesas,fdp1.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car Fine Display Processor (FDP1) + +maintainers: + - Laurent Pinchart <laurent.pinchart@ideasonboard.com> + +description: + The FDP1 is a de-interlacing module which converts interlaced video to + progressive video. It is capable of performing pixel format conversion + between YCbCr/YUV formats and RGB formats. Only YCbCr/YUV formats are + supported as an input to the module. + +properties: + compatible: + enum: + - renesas,fdp1 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + + renesas,fcp: + $ref: /schemas/types.yaml#/definitions/phandle + description: + A phandle referencing the FCP that handles memory accesses for the FDP1. + Not allowed on R-Car Gen2, mandatory on R-Car Gen3. + +required: + - compatible + - reg + - interrupts + - clocks + - power-domains + - resets + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/renesas-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a7795-sysc.h> + + fdp1@fe940000 { + compatible = "renesas,fdp1"; + reg = <0xfe940000 0x2400>; + interrupts = <GIC_SPI 262 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 119>; + power-domains = <&sysc R8A7795_PD_A3VP>; + resets = <&cpg 119>; + renesas,fcp = <&fcpf0>; + }; +... diff --git a/Documentation/devicetree/bindings/media/renesas,vsp1.txt b/Documentation/devicetree/bindings/media/renesas,vsp1.txt deleted file mode 100644 index cd5a955b2ea0..000000000000 --- a/Documentation/devicetree/bindings/media/renesas,vsp1.txt +++ /dev/null @@ -1,30 +0,0 @@ -* Renesas VSP Video Processing Engine - -The VSP is a video processing engine that supports up-/down-scaling, alpha -blending, color space conversion and various other image processing features. -It can be found in the Renesas R-Car Gen2, R-Car Gen3, RZ/G1, and RZ/G2 SoCs. - -Required properties: - - - compatible: Must contain one of the following values - - "renesas,vsp1" for the R-Car Gen2 and RZ/G1 VSP1 - - "renesas,vsp2" for the R-Car Gen3 and RZ/G2 VSP2 - - - reg: Base address and length of the registers block for the VSP. - - 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 - - vsp@fe928000 { - compatible = "renesas,vsp1"; - reg = <0 0xfe928000 0 0x8000>; - interrupts = <0 267 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&mstp1_clks R8A7790_CLK_VSP1_S>; - }; diff --git a/Documentation/devicetree/bindings/media/renesas,vsp1.yaml b/Documentation/devicetree/bindings/media/renesas,vsp1.yaml new file mode 100644 index 000000000000..990e9c1dbc43 --- /dev/null +++ b/Documentation/devicetree/bindings/media/renesas,vsp1.yaml @@ -0,0 +1,97 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/renesas,vsp1.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas VSP Video Processing Engine + +maintainers: + - Laurent Pinchart <laurent.pinchart@ideasonboard.com> + +description: + The VSP is a video processing engine that supports up-/down-scaling, alpha + blending, color space conversion and various other image processing features. + It can be found in the Renesas R-Car Gen2, R-Car Gen3, RZ/G1, and RZ/G2 SoCs. + +properties: + compatible: + enum: + - renesas,vsp1 # R-Car Gen2 and RZ/G1 + - renesas,vsp2 # R-Car Gen3 and RZ/G2 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + + renesas,fcp: + $ref: /schemas/types.yaml#/definitions/phandle + description: + A phandle referencing the FCP that handles memory accesses for the VSP. + +required: + - compatible + - reg + - interrupts + - clocks + - power-domains + - resets + +additionalProperties: false + +if: + properties: + compatible: + items: + - const: renesas,vsp1 +then: + properties: + renesas,fcp: false +else: + required: + - renesas,fcp + +examples: + # R8A7790 (R-Car H2) VSP1-S + - | + #include <dt-bindings/clock/renesas-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a7790-sysc.h> + + vsp@fe928000 { + compatible = "renesas,vsp1"; + reg = <0xfe928000 0x8000>; + interrupts = <GIC_SPI 267 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 131>; + power-domains = <&sysc R8A7790_PD_ALWAYS_ON>; + resets = <&cpg 131>; + }; + + # R8A77951 (R-Car H3) VSP2-BC + - | + #include <dt-bindings/clock/renesas-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a7795-sysc.h> + + vsp@fe920000 { + compatible = "renesas,vsp2"; + reg = <0xfe920000 0x8000>; + interrupts = <GIC_SPI 465 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 624>; + power-domains = <&sysc R8A7795_PD_A3VP>; + resets = <&cpg 624>; + + renesas,fcp = <&fcpvb1>; + }; +... diff --git a/Documentation/devicetree/bindings/media/xilinx/video.txt b/Documentation/devicetree/bindings/media/xilinx/video.txt index 68ac210e688e..d0335ca0cd57 100644 --- a/Documentation/devicetree/bindings/media/xilinx/video.txt +++ b/Documentation/devicetree/bindings/media/xilinx/video.txt @@ -32,4 +32,4 @@ The following properties are common to all Xilinx video IP cores. defaults to "mono". -[UG934] http://www.xilinx.com/support/documentation/ip_documentation/axi_videoip/v1_0/ug934_axi_videoIP.pdf +[UG934] https://www.xilinx.com/support/documentation/ip_documentation/axi_videoip/v1_0/ug934_axi_videoIP.pdf diff --git a/Documentation/devicetree/bindings/media/xilinx/xlnx,csi2rxss.yaml b/Documentation/devicetree/bindings/media/xilinx/xlnx,csi2rxss.yaml new file mode 100644 index 000000000000..7b9407c0520e --- /dev/null +++ b/Documentation/devicetree/bindings/media/xilinx/xlnx,csi2rxss.yaml @@ -0,0 +1,237 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/xilinx/xlnx,csi2rxss.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx MIPI CSI-2 Receiver Subsystem + +maintainers: + - Vishal Sagar <vishal.sagar@xilinx.com> + +description: | + The Xilinx MIPI CSI-2 Receiver Subsystem is used to capture MIPI CSI-2 + traffic from compliant camera sensors and send the output as AXI4 Stream + video data for image processing. + The subsystem consists of a MIPI D-PHY in slave mode which captures the + data packets. This is passed along the MIPI CSI-2 Rx IP which extracts the + packet data. The optional Video Format Bridge (VFB) converts this data to + AXI4 Stream video data. + For more details, please refer to PG232 Xilinx MIPI CSI-2 Receiver Subsystem. + Please note that this bindings includes only the MIPI CSI-2 Rx controller + and Video Format Bridge and not D-PHY. + +properties: + compatible: + items: + - enum: + - xlnx,mipi-csi2-rx-subsystem-5.0 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + description: List of clock specifiers + items: + - description: AXI Lite clock + - description: Video clock + + clock-names: + items: + - const: lite_aclk + - const: video_aclk + + xlnx,csi-pxl-format: + description: | + This denotes the CSI Data type selected in hw design. + Packets other than this data type (except for RAW8 and + User defined data types) will be filtered out. + Possible values are as below - + 0x1e - YUV4228B + 0x1f - YUV42210B + 0x20 - RGB444 + 0x21 - RGB555 + 0x22 - RGB565 + 0x23 - RGB666 + 0x24 - RGB888 + 0x28 - RAW6 + 0x29 - RAW7 + 0x2a - RAW8 + 0x2b - RAW10 + 0x2c - RAW12 + 0x2d - RAW14 + 0x2e - RAW16 + 0x2f - RAW20 + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + - anyOf: + - minimum: 0x1e + - maximum: 0x24 + - minimum: 0x28 + - maximum: 0x2f + + xlnx,vfb: + type: boolean + description: Present when Video Format Bridge is enabled in IP configuration + + xlnx,en-csi-v2-0: + type: boolean + description: Present if CSI v2 is enabled in IP configuration. + + xlnx,en-vcx: + type: boolean + description: | + When present, there are maximum 16 virtual channels, else only 4. + + xlnx,en-active-lanes: + type: boolean + description: | + Present if the number of active lanes can be re-configured at + runtime in the Protocol Configuration Register. Otherwise all lanes, + as set in IP configuration, are always active. + + video-reset-gpios: + description: Optional specifier for a GPIO that asserts video_aresetn. + maxItems: 1 + + ports: + type: object + + properties: + port@0: + type: object + description: | + Input / sink port node, single endpoint describing the + CSI-2 transmitter. + + properties: + reg: + const: 0 + + endpoint: + type: object + + properties: + + data-lanes: + description: | + This is required only in the sink port 0 endpoint which + connects to MIPI CSI-2 source like sensor. + The possible values are - + 1 - For 1 lane enabled in IP. + 1 2 - For 2 lanes enabled in IP. + 1 2 3 - For 3 lanes enabled in IP. + 1 2 3 4 - For 4 lanes enabled in IP. + items: + - const: 1 + - const: 2 + - const: 3 + - const: 4 + + remote-endpoint: true + + required: + - data-lanes + - remote-endpoint + + additionalProperties: false + + additionalProperties: false + + port@1: + type: object + description: | + Output / source port node, endpoint describing modules + connected the CSI-2 receiver. + + properties: + + reg: + const: 1 + + endpoint: + type: object + + properties: + + remote-endpoint: true + + required: + - remote-endpoint + + additionalProperties: false + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - ports + +allOf: + - if: + required: + - xlnx,vfb + then: + required: + - xlnx,csi-pxl-format + else: + properties: + xlnx,csi-pxl-format: false + + - if: + not: + required: + - xlnx,en-csi-v2-0 + then: + properties: + xlnx,en-vcx: false + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + xcsi2rxss_1: csi2rx@a0020000 { + compatible = "xlnx,mipi-csi2-rx-subsystem-5.0"; + reg = <0xa0020000 0x10000>; + interrupt-parent = <&gic>; + interrupts = <0 95 4>; + xlnx,csi-pxl-format = <0x2a>; + xlnx,vfb; + xlnx,en-active-lanes; + xlnx,en-csi-v2-0; + xlnx,en-vcx; + clock-names = "lite_aclk", "video_aclk"; + clocks = <&misc_clk_0>, <&misc_clk_1>; + video-reset-gpios = <&gpio 86 GPIO_ACTIVE_LOW>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + /* Sink port */ + reg = <0>; + csiss_in: endpoint { + data-lanes = <1 2 3 4>; + /* MIPI CSI-2 Camera handle */ + remote-endpoint = <&camera_out>; + }; + }; + port@1 { + /* Source port */ + reg = <1>; + csiss_out: endpoint { + remote-endpoint = <&vproc_in>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/memory-controllers/fsl/mmdc.txt b/Documentation/devicetree/bindings/memory-controllers/fsl/mmdc.txt deleted file mode 100644 index bcc36c5b543c..000000000000 --- a/Documentation/devicetree/bindings/memory-controllers/fsl/mmdc.txt +++ /dev/null @@ -1,35 +0,0 @@ -Freescale Multi Mode DDR controller (MMDC) - -Required properties : -- compatible : should be one of following: - for i.MX6Q/i.MX6DL: - - "fsl,imx6q-mmdc"; - for i.MX6QP: - - "fsl,imx6qp-mmdc", "fsl,imx6q-mmdc"; - for i.MX6SL: - - "fsl,imx6sl-mmdc", "fsl,imx6q-mmdc"; - for i.MX6SLL: - - "fsl,imx6sll-mmdc", "fsl,imx6q-mmdc"; - for i.MX6SX: - - "fsl,imx6sx-mmdc", "fsl,imx6q-mmdc"; - for i.MX6UL/i.MX6ULL/i.MX6ULZ: - - "fsl,imx6ul-mmdc", "fsl,imx6q-mmdc"; - for i.MX7ULP: - - "fsl,imx7ulp-mmdc", "fsl,imx6q-mmdc"; -- reg : address and size of MMDC DDR controller registers - -Optional properties : -- clocks : the clock provided by the SoC to access the MMDC registers - -Example : - mmdc0: memory-controller@21b0000 { /* MMDC0 */ - compatible = "fsl,imx6q-mmdc"; - reg = <0x021b0000 0x4000>; - clocks = <&clks IMX6QDL_CLK_MMDC_P0_IPG>; - }; - - mmdc1: memory-controller@21b4000 { /* MMDC1 */ - compatible = "fsl,imx6q-mmdc"; - reg = <0x021b4000 0x4000>; - status = "disabled"; - }; diff --git a/Documentation/devicetree/bindings/memory-controllers/fsl/mmdc.yaml b/Documentation/devicetree/bindings/memory-controllers/fsl/mmdc.yaml new file mode 100644 index 000000000000..dee5131c0361 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/fsl/mmdc.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/fsl/mmdc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale Multi Mode DDR controller (MMDC) + +maintainers: + - Anson Huang <Anson.Huang@nxp.com> + +properties: + compatible: + oneOf: + - const: fsl,imx6q-mmdc + - items: + - enum: + - fsl,imx6qp-mmdc + - fsl,imx6sl-mmdc + - fsl,imx6sll-mmdc + - fsl,imx6sx-mmdc + - fsl,imx6ul-mmdc + - fsl,imx7ulp-mmdc + - const: fsl,imx6q-mmdc + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + +examples: + - | + #include <dt-bindings/clock/imx6qdl-clock.h> + + memory-controller@21b0000 { + compatible = "fsl,imx6q-mmdc"; + reg = <0x021b0000 0x4000>; + clocks = <&clks IMX6QDL_CLK_MMDC_P0_IPG>; + }; + + memory-controller@21b4000 { + compatible = "fsl,imx6q-mmdc"; + reg = <0x021b4000 0x4000>; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml b/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml new file mode 100644 index 000000000000..660005601a7f --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml @@ -0,0 +1,88 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/renesas,rpc-if.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas Reduced Pin Count Interface (RPC-IF) + +maintainers: + - Sergei Shtylyov <sergei.shtylyov@gmail.com> + +description: | + Renesas RPC-IF allows a SPI flash or HyperFlash connected to the SoC to + be accessed via the external address space read mode or the manual mode. + + The flash chip itself should be represented by a subnode of the RPC-IF node. + The flash interface is selected based on the "compatible" property of this + subnode: + - if it contains "jedec,spi-nor", then SPI is used; + - if it contains "cfi-flash", then HyperFlash is used. + +allOf: + - $ref: "/schemas/spi/spi-controller.yaml#" + +properties: + compatible: + items: + - enum: + - renesas,r8a77970-rpc-if # R-Car V3M + - renesas,r8a77980-rpc-if # R-Car V3H + - renesas,r8a77995-rpc-if # R-Car D3 + - const: renesas,rcar-gen3-rpc-if # a generic R-Car gen3 device + + reg: + items: + - description: RPC-IF registers + - description: direct mapping read mode area + - description: write buffer area + + reg-names: + items: + - const: regs + - const: dirmap + - const: wbuf + + clocks: + maxItems: 1 + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + +patternProperties: + "flash@[0-9a-f]+$": + type: object + properties: + compatible: + enum: + - cfi-flash + - jedec,spi-nor + +examples: + - | + #include <dt-bindings/clock/renesas-cpg-mssr.h> + #include <dt-bindings/power/r8a77995-sysc.h> + + spi@ee200000 { + compatible = "renesas,r8a77995-rpc-if", "renesas,rcar-gen3-rpc-if"; + reg = <0xee200000 0x200>, + <0x08000000 0x4000000>, + <0xee208000 0x100>; + reg-names = "regs", "dirmap", "wbuf"; + clocks = <&cpg CPG_MOD 917>; + power-domains = <&sysc R8A77995_PD_ALWAYS_ON>; + resets = <&cpg 917>; + #address-cells = <1>; + #size-cells = <0>; + + flash@0 { + compatible = "jedec,spi-nor"; + reg = <0>; + spi-max-frequency = <40000000>; + spi-tx-bus-width = <1>; + spi-rx-bus-width = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt b/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt index 86446074e206..a92acf1dd491 100644 --- a/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt +++ b/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt @@ -37,7 +37,7 @@ syscon as a means to arbitrate access. [0] http://www.intel.com/design/chipsets/industry/25128901.pdf [1] https://www.renesas.com/en-sg/doc/products/mpumcu/001/rej09b0078_h8s2168.pdf?key=7c88837454702128622bee53acbda8f4 -[2] http://www.intel.com/content/dam/www/public/us/en/documents/product-briefs/ipmi-second-gen-interface-spec-v2-rev1-1.pdf +[2] https://www.intel.com/content/dam/www/public/us/en/documents/product-briefs/ipmi-second-gen-interface-spec-v2-rev1-1.pdf [3] https://en.wikipedia.org/wiki/Super_I/O Required properties diff --git a/Documentation/devicetree/bindings/mfd/atmel-tcb.txt b/Documentation/devicetree/bindings/mfd/atmel-tcb.txt deleted file mode 100644 index c4a83e364cb6..000000000000 --- a/Documentation/devicetree/bindings/mfd/atmel-tcb.txt +++ /dev/null @@ -1,56 +0,0 @@ -* Device tree bindings for Atmel Timer Counter Blocks -- compatible: Should be "atmel,<chip>-tcb", "simple-mfd", "syscon". - <chip> can be "at91rm9200" or "at91sam9x5" -- reg: Should contain registers location and length -- #address-cells: has to be 1 -- #size-cells: has to be 0 -- interrupts: Should contain all interrupts for the TC block - Note that you can specify several interrupt cells if the TC - block has one interrupt per channel. -- clock-names: tuple listing input clock names. - Required elements: "t0_clk", "slow_clk" - Optional elements: "t1_clk", "t2_clk" -- clocks: phandles to input clocks. - -The TCB can expose multiple subdevices: - * a timer - - compatible: Should be "atmel,tcb-timer" - - reg: Should contain the TCB channels to be used. If the - counter width is 16 bits (at91rm9200-tcb), two consecutive - channels are needed. Else, only one channel will be used. - -Examples: - -One interrupt per TC block: - tcb0: timer@fff7c000 { - compatible = "atmel,at91rm9200-tcb", "simple-mfd", "syscon"; - #address-cells = <1>; - #size-cells = <0>; - reg = <0xfff7c000 0x100>; - interrupts = <18 4>; - clocks = <&tcb0_clk>, <&clk32k>; - clock-names = "t0_clk", "slow_clk"; - - timer@0 { - compatible = "atmel,tcb-timer"; - reg = <0>, <1>; - }; - - timer@2 { - compatible = "atmel,tcb-timer"; - reg = <2>; - }; - }; - -One interrupt per TC channel in a TC block: - tcb1: timer@fffdc000 { - compatible = "atmel,at91rm9200-tcb", "simple-mfd", "syscon"; - #address-cells = <1>; - #size-cells = <0>; - reg = <0xfffdc000 0x100>; - interrupts = <26 4>, <27 4>, <28 4>; - clocks = <&tcb1_clk>, <&clk32k>; - clock-names = "t0_clk", "slow_clk"; - }; - - diff --git a/Documentation/devicetree/bindings/mfd/da9062.txt b/Documentation/devicetree/bindings/mfd/da9062.txt index 857af982c88f..bab0d0e66cb3 100644 --- a/Documentation/devicetree/bindings/mfd/da9062.txt +++ b/Documentation/devicetree/bindings/mfd/da9062.txt @@ -1,8 +1,8 @@ * Dialog DA9062 Power Management Integrated Circuit (PMIC) Product information for the DA9062 and DA9061 devices can be found here: -- http://www.dialog-semiconductor.com/products/da9062 -- http://www.dialog-semiconductor.com/products/da9061 +- https://www.dialog-semiconductor.com/products/da9062 +- https://www.dialog-semiconductor.com/products/da9061 The DA9062 PMIC consists of: diff --git a/Documentation/devicetree/bindings/mfd/syscon.yaml b/Documentation/devicetree/bindings/mfd/syscon.yaml index 19bdaf781853..049ec2ffc7f9 100644 --- a/Documentation/devicetree/bindings/mfd/syscon.yaml +++ b/Documentation/devicetree/bindings/mfd/syscon.yaml @@ -38,12 +38,15 @@ properties: - allwinner,sun8i-h3-system-controller - allwinner,sun8i-v3s-system-controller - allwinner,sun50i-a64-system-controller + - microchip,sparx5-cpu-syscon + - mstar,msc313-pmsleep - const: syscon - contains: const: syscon - additionalItems: true + minItems: 2 + maxItems: 4 # Should be enough reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/mfd/ti,j721e-system-controller.yaml b/Documentation/devicetree/bindings/mfd/ti,j721e-system-controller.yaml new file mode 100644 index 000000000000..03d0a232c75e --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/ti,j721e-system-controller.yaml @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2020 Texas Instruments Incorporated - http://www.ti.com/ +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/ti,j721e-system-controller.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TI J721e System Controller Registers R/W Device Tree Bindings + +description: | + This represents the Control Module registers (CTRL_MMR0) on the SoC. + System controller node represents a register region containing a set + of miscellaneous registers. The registers are not cohesive enough to + represent as any specific type of device. The typical use-case is + for some other node's driver, or platform-specific code, to acquire + a reference to the syscon node (e.g. by phandle, node path, or + search using a specific compatible value), interrogate the node (or + associated OS driver) to determine the location of the registers, + and access the registers directly. + +maintainers: + - Kishon Vijay Abraham I <kishon@ti.com> + - Roger Quadros <rogerq@ti.com + +properties: + compatible: + anyOf: + - items: + - enum: + - ti,j721e-system-controller + - const: syscon + - const: simple-mfd + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + ranges: true + +# Optional children + + "^serdes-ln-ctrl@[0-9a-f]+$": + type: object + description: | + This is the SERDES lane control mux. It should follow the bindings + specified in + Documentation/devicetree/bindings/mux/reg-mux.txt + +required: + - compatible + - reg + - "#address-cells" + - "#size-cells" + - ranges + +unevaluatedProperties: false + +examples: + - | + scm_conf: scm-conf@100000 { + compatible = "ti,j721e-system-controller", "syscon", "simple-mfd"; + reg = <0x00100000 0x1c000>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + serdes_ln_ctrl: serdes-ln-ctrl@4080 { + compatible = "mmio-mux"; + reg = <0x00004080 0x50>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/mips/ingenic/devices.yaml b/Documentation/devicetree/bindings/mips/ingenic/devices.yaml index d1175030781a..83c86cbe4716 100644 --- a/Documentation/devicetree/bindings/mips/ingenic/devices.yaml +++ b/Documentation/devicetree/bindings/mips/ingenic/devices.yaml @@ -8,7 +8,8 @@ title: Ingenic XBurst based Platforms Device Tree Bindings maintainers: - 周ç°æ° (Zhou Yanjie) <zhouyanjie@wanyeetech.com> -description: | + +description: Devices with a Ingenic XBurst CPU shall have the following properties. properties: @@ -22,6 +23,11 @@ properties: - const: qi,lb60 - const: ingenic,jz4740 + - description: YLM RetroMini RS-90 + items: + - const: ylm,rs90 + - const: ingenic,jz4725b + - description: Game Consoles Worldwide GCW Zero items: - const: gcw,zero @@ -32,8 +38,13 @@ properties: - const: img,ci20 - const: ingenic,jz4780 - - description: YSH & ATIL General Board CU Neo + - description: YSH & ATIL General Board, CU1000 Module with Neo Backplane items: - const: yna,cu1000-neo - - const: ingenic,x1000 + - const: ingenic,x1000e + + - description: YSH & ATIL General Board, CU1830 Module with Neo Backplane + items: + - const: yna,cu1830-neo + - const: ingenic,x1830 ... diff --git a/Documentation/devicetree/bindings/mips/ingenic/ingenic,cpu.yaml b/Documentation/devicetree/bindings/mips/ingenic/ingenic,cpu.yaml new file mode 100644 index 000000000000..16fa03d65ad5 --- /dev/null +++ b/Documentation/devicetree/bindings/mips/ingenic/ingenic,cpu.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mips/ingenic/ingenic,cpu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Bindings for Ingenic XBurst family CPUs + +maintainers: + - 周ç°æ° (Zhou Yanjie) <zhouyanjie@wanyeetech.com> + +description: + Ingenic XBurst family CPUs shall have the following properties. + +properties: + compatible: + oneOf: + + - description: Ingenic XBurst®1 CPU Cores + enum: + - ingenic,xburst-mxu1.0 + - ingenic,xburst-fpu1.0-mxu1.1 + - ingenic,xburst-fpu2.0-mxu2.0 + + - description: Ingenic XBurst®2 CPU Cores + enum: + - ingenic,xburst2-fpu2.1-mxu2.1-smt + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - device_type + - compatible + - reg + - clocks + +examples: + - | + #include <dt-bindings/clock/jz4780-cgu.h> + + cpus { + #address-cells = <1>; + #size-cells = <0>; + + cpu0: cpu@0 { + device_type = "cpu"; + compatible = "ingenic,xburst-fpu1.0-mxu1.1"; + reg = <0>; + + clocks = <&cgu JZ4780_CLK_CPU>; + clock-names = "cpu"; + }; + + cpu1: cpu@1 { + device_type = "cpu"; + compatible = "ingenic,xburst-fpu1.0-mxu1.1"; + reg = <1>; + + clocks = <&cgu JZ4780_CLK_CORE1>; + clock-names = "cpu"; + }; + }; +... diff --git a/Documentation/devicetree/bindings/mips/loongson/devices.yaml b/Documentation/devicetree/bindings/mips/loongson/devices.yaml index 74ed4e397a78..d25e80aa8b2a 100644 --- a/Documentation/devicetree/bindings/mips/loongson/devices.yaml +++ b/Documentation/devicetree/bindings/mips/loongson/devices.yaml @@ -17,11 +17,23 @@ properties: compatible: oneOf: - - description: Generic Loongson3 Quad Core + RS780E + - description: Classic Loongson64 Quad Core + LS7A items: - - const: loongson,loongson3-4core-rs780e + - const: loongson,loongson64c-4core-ls7a - - description: Generic Loongson3 Octa Core + RS780E + - description: Classic Loongson64 Quad Core + RS780E items: - - const: loongson,loongson3-8core-rs780e + - const: loongson,loongson64c-4core-rs780e + + - description: Classic Loongson64 Octa Core + RS780E + items: + - const: loongson,loongson64c-8core-rs780e + + - description: Generic Loongson64 Quad Core + LS7A + items: + - const: loongson,loongson64g-4core-ls7a + + - description: Virtual Loongson64 Quad Core + VirtIO + items: + - const: loongson,loongson64v-4core-virtio ... diff --git a/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt b/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt index 9134e9bcca56..7b486d4985dc 100644 --- a/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt +++ b/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt @@ -10,7 +10,7 @@ such as network interfaces, crypto accelerator instances, L2 switches, etc. For an overview of the DPAA2 architecture and fsl-mc bus see: -Documentation/networking/device_drivers/freescale/dpaa2/overview.rst +Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst As described in the above overview, all DPAA2 objects in a DPRC share the same hardware "isolation context" and a 10-bit value called an ICID @@ -28,6 +28,16 @@ Documentation/devicetree/bindings/iommu/iommu.txt. For arm-smmu binding, see: Documentation/devicetree/bindings/iommu/arm,smmu.yaml. +The MSI writes are accompanied by sideband data which is derived from the ICID. +The msi-map property is used to associate the devices with both the ITS +controller and the sideband data which accompanies the writes. + +For generic MSI bindings, see +Documentation/devicetree/bindings/interrupt-controller/msi.txt. + +For GICv3 and GIC ITS bindings, see: +Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml. + Required properties: - compatible @@ -49,11 +59,6 @@ Required properties: region may not be present in some scenarios, such as in the device tree presented to a virtual machine. - - msi-parent - Value type: <phandle> - Definition: Must be present and point to the MSI controller node - handling message interrupts for the MC. - - ranges Value type: <prop-encoded-array> Definition: A standard property. Defines the mapping between the child @@ -119,6 +124,28 @@ Optional properties: associated with the listed IOMMU, with the iommu-specifier (i - icid-base + iommu-base). +- msi-map: Maps an ICID to a GIC ITS and associated msi-specifier + data. + + The property is an arbitrary number of tuples of + (icid-base,gic-its,msi-base,length). + + Any ICID in the interval [icid-base, icid-base + length) is + associated with the listed GIC ITS, with the msi-specifier + (i - icid-base + msi-base). + +Deprecated properties: + + - msi-parent + Value type: <phandle> + Definition: Describes the MSI controller node handling message + interrupts for the MC. When there is no translation + between the ICID and deviceID this property can be used + to describe the MSI controller used by the devices on the + mc-bus. + The use of this property for mc-bus is deprecated. Please + use msi-map. + Example: smmu: iommu@5000000 { @@ -128,13 +155,24 @@ Example: ... }; + gic: interrupt-controller@6000000 { + compatible = "arm,gic-v3"; + ... + } + its: gic-its@6020000 { + compatible = "arm,gic-v3-its"; + msi-controller; + ... + }; + fsl_mc: fsl-mc@80c000000 { compatible = "fsl,qoriq-mc"; reg = <0x00000008 0x0c000000 0 0x40>, /* MC portal base */ <0x00000000 0x08340000 0 0x40000>; /* MC control reg */ - msi-parent = <&its>; /* define map for ICIDs 23-64 */ iommu-map = <23 &smmu 23 41>; + /* define msi map for ICIDs 23-64 */ + msi-map = <23 &its 23 41>; #address-cells = <3>; #size-cells = <1>; diff --git a/Documentation/devicetree/bindings/misc/olpc,xo1.75-ec.txt b/Documentation/devicetree/bindings/misc/olpc,xo1.75-ec.txt deleted file mode 100644 index 8c4d649cdd8f..000000000000 --- a/Documentation/devicetree/bindings/misc/olpc,xo1.75-ec.txt +++ /dev/null @@ -1,23 +0,0 @@ -OLPC XO-1.75 Embedded Controller - -Required properties: -- compatible: Should be "olpc,xo1.75-ec". -- cmd-gpios: gpio specifier of the CMD pin - -The embedded controller requires the SPI controller driver to signal readiness -to receive a transfer (that is, when TX FIFO contains the response data) by -strobing the ACK pin with the ready signal. See the "ready-gpios" property of the -SSP binding as documented in: -<Documentation/devicetree/bindings/spi/spi-pxa2xx.txt>. - -Example: - &ssp3 { - spi-slave; - ready-gpios = <&gpio 125 GPIO_ACTIVE_HIGH>; - - slave { - compatible = "olpc,xo1.75-ec"; - spi-cpha; - cmd-gpios = <&gpio 155 GPIO_ACTIVE_HIGH>; - }; - }; diff --git a/Documentation/devicetree/bindings/misc/olpc,xo1.75-ec.yaml b/Documentation/devicetree/bindings/misc/olpc,xo1.75-ec.yaml new file mode 100644 index 000000000000..e75d77beec6a --- /dev/null +++ b/Documentation/devicetree/bindings/misc/olpc,xo1.75-ec.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +# Copyright (C) 2019,2020 Lubomir Rintel <lkundrak@v3.sk> +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/misc/olpc,xo1.75-ec.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: OLPC XO-1.75 Embedded Controller bindings + +description: | + This binding describes the Embedded Controller acting as a SPI bus master + on a OLPC XO-1.75 laptop computer. + + The embedded controller requires the SPI controller driver to signal + readiness to receive a transfer (that is, when TX FIFO contains the + response data) by strobing the ACK pin with the ready signal. See the + "ready-gpios" property of the SSP binding as documented in: + <Documentation/devicetree/bindings/spi/marvell,mmp2-ssp.yaml>. + +maintainers: + - Lubomir Rintel <lkundrak@v3.sk> + +properties: + compatible: + const: olpc,xo1.75-ec + + cmd-gpios: + description: GPIO uspecifier of the CMD pin + maxItems: 1 + +required: + - compatible + - cmd-gpios + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + spi { + spi-slave; + ready-gpios = <&gpio 125 GPIO_ACTIVE_HIGH>; + + slave { + compatible = "olpc,xo1.75-ec"; + spi-cpha; + cmd-gpios = <&gpio 155 GPIO_ACTIVE_HIGH>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt b/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt deleted file mode 100644 index f29bf7dd2ece..000000000000 --- a/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt +++ /dev/null @@ -1,192 +0,0 @@ -Device Tree Bindings for the Arasan SDHCI Controller - - The bindings follow the mmc[1], clock[2], interrupt[3] and phy[4] bindings. - Only deviations are documented here. - - [1] Documentation/devicetree/bindings/mmc/mmc.txt - [2] Documentation/devicetree/bindings/clock/clock-bindings.txt - [3] Documentation/devicetree/bindings/interrupt-controller/interrupts.txt - [4] Documentation/devicetree/bindings/phy/phy-bindings.txt - -Required Properties: - - compatible: Compatibility string. One of: - - "arasan,sdhci-8.9a": generic Arasan SDHCI 8.9a PHY - - "arasan,sdhci-4.9a": generic Arasan SDHCI 4.9a PHY - - "arasan,sdhci-5.1": generic Arasan SDHCI 5.1 PHY - - "rockchip,rk3399-sdhci-5.1", "arasan,sdhci-5.1": rk3399 eMMC PHY - For this device it is strongly suggested to include arasan,soc-ctl-syscon. - - "xlnx,zynqmp-8.9a": ZynqMP SDHCI 8.9a PHY - For this device it is strongly suggested to include clock-output-names and - #clock-cells. - - "xlnx,versal-8.9a": Versal SDHCI 8.9a PHY - For this device it is strongly suggested to include clock-output-names and - #clock-cells. - - "ti,am654-sdhci-5.1", "arasan,sdhci-5.1": TI AM654 MMC PHY - Note: This binding has been deprecated and moved to [5]. - - "intel,lgm-sdhci-5.1-emmc", "arasan,sdhci-5.1": Intel LGM eMMC PHY - For this device it is strongly suggested to include arasan,soc-ctl-syscon. - - "intel,lgm-sdhci-5.1-sdxc", "arasan,sdhci-5.1": Intel LGM SDXC PHY - For this device it is strongly suggested to include arasan,soc-ctl-syscon. - - "intel,keembay-sdhci-5.1-emmc", "arasan,sdhci-5.1": Intel Keem Bay eMMC - For this device it is strongly suggested to include arasan,soc-ctl-syscon. - - "intel,keembay-sdhci-5.1-sd": Intel Keem Bay SD controller - For this device it is strongly suggested to include arasan,soc-ctl-syscon. - - "intel,keembay-sdhci-5.1-sdio": Intel Keem Bay SDIO controller - For this device it is strongly suggested to include arasan,soc-ctl-syscon. - - [5] Documentation/devicetree/bindings/mmc/sdhci-am654.txt - - - reg: From mmc bindings: Register location and length. - - clocks: From clock bindings: Handles to clock inputs. - - clock-names: From clock bindings: Tuple including "clk_xin" and "clk_ahb" - - interrupts: Interrupt specifier - -Required Properties for "arasan,sdhci-5.1": - - phys: From PHY bindings: Phandle for the Generic PHY for arasan. - - phy-names: MUST be "phy_arasan". - -Optional Properties: - - arasan,soc-ctl-syscon: A phandle to a syscon device (see ../mfd/syscon.txt) - used to access core corecfg registers. Offsets of registers in this - syscon are determined based on the main compatible string for the device. - - clock-output-names: If specified, this will be the name of the card clock - which will be exposed by this device. Required if #clock-cells is - specified. - - #clock-cells: If specified this should be the value <0> or <1>. With this - property in place we will export one or two clocks representing the Card - Clock. These clocks are expected to be consumed by our PHY. - - xlnx,fails-without-test-cd: when present, the controller doesn't work when - the CD line is not connected properly, and the line is not connected - properly. Test mode can be used to force the controller to function. - - xlnx,int-clock-stable-broken: when present, the controller always reports - that the internal clock is stable even when it is not. - - - xlnx,mio-bank: When specified, this will indicate the MIO bank number in - which the command and data lines are configured. If not specified, driver - will assume this as 0. - -Example: - sdhci@e0100000 { - compatible = "arasan,sdhci-8.9a"; - reg = <0xe0100000 0x1000>; - clock-names = "clk_xin", "clk_ahb"; - clocks = <&clkc 21>, <&clkc 32>; - interrupt-parent = <&gic>; - interrupts = <0 24 4>; - } ; - - sdhci@e2800000 { - compatible = "arasan,sdhci-5.1"; - reg = <0xe2800000 0x1000>; - clock-names = "clk_xin", "clk_ahb"; - clocks = <&cru 8>, <&cru 18>; - interrupt-parent = <&gic>; - interrupts = <0 24 4>; - phys = <&emmc_phy>; - phy-names = "phy_arasan"; - } ; - - sdhci: sdhci@fe330000 { - compatible = "rockchip,rk3399-sdhci-5.1", "arasan,sdhci-5.1"; - reg = <0x0 0xfe330000 0x0 0x10000>; - interrupts = <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cru SCLK_EMMC>, <&cru ACLK_EMMC>; - clock-names = "clk_xin", "clk_ahb"; - arasan,soc-ctl-syscon = <&grf>; - assigned-clocks = <&cru SCLK_EMMC>; - assigned-clock-rates = <200000000>; - clock-output-names = "emmc_cardclock"; - phys = <&emmc_phy>; - phy-names = "phy_arasan"; - #clock-cells = <0>; - }; - - sdhci: mmc@ff160000 { - compatible = "xlnx,zynqmp-8.9a", "arasan,sdhci-8.9a"; - interrupt-parent = <&gic>; - interrupts = <0 48 4>; - reg = <0x0 0xff160000 0x0 0x1000>; - clocks = <&clk200>, <&clk200>; - clock-names = "clk_xin", "clk_ahb"; - clock-output-names = "clk_out_sd0", "clk_in_sd0"; - #clock-cells = <1>; - clk-phase-sd-hs = <63>, <72>; - }; - - sdhci: mmc@f1040000 { - compatible = "xlnx,versal-8.9a", "arasan,sdhci-8.9a"; - interrupt-parent = <&gic>; - interrupts = <0 126 4>; - reg = <0x0 0xf1040000 0x0 0x10000>; - clocks = <&clk200>, <&clk200>; - clock-names = "clk_xin", "clk_ahb"; - clock-output-names = "clk_out_sd0", "clk_in_sd0"; - #clock-cells = <1>; - clk-phase-sd-hs = <132>, <60>; - }; - - emmc: sdhci@ec700000 { - compatible = "intel,lgm-sdhci-5.1-emmc", "arasan,sdhci-5.1"; - reg = <0xec700000 0x300>; - interrupt-parent = <&ioapic1>; - interrupts = <44 1>; - clocks = <&cgu0 LGM_CLK_EMMC5>, <&cgu0 LGM_CLK_NGI>, - <&cgu0 LGM_GCLK_EMMC>; - clock-names = "clk_xin", "clk_ahb", "gate"; - clock-output-names = "emmc_cardclock"; - #clock-cells = <0>; - phys = <&emmc_phy>; - phy-names = "phy_arasan"; - arasan,soc-ctl-syscon = <&sysconf>; - }; - - sdxc: sdhci@ec600000 { - compatible = "arasan,sdhci-5.1", "intel,lgm-sdhci-5.1-sdxc"; - reg = <0xec600000 0x300>; - interrupt-parent = <&ioapic1>; - interrupts = <43 1>; - clocks = <&cgu0 LGM_CLK_SDIO>, <&cgu0 LGM_CLK_NGI>, - <&cgu0 LGM_GCLK_SDXC>; - clock-names = "clk_xin", "clk_ahb", "gate"; - clock-output-names = "sdxc_cardclock"; - #clock-cells = <0>; - phys = <&sdxc_phy>; - phy-names = "phy_arasan"; - arasan,soc-ctl-syscon = <&sysconf>; - }; - - mmc: mmc@33000000 { - compatible = "intel,keembay-sdhci-5.1-emmc", "arasan,sdhci-5.1"; - interrupts = <GIC_SPI 82 IRQ_TYPE_LEVEL_HIGH>; - reg = <0x0 0x33000000 0x0 0x300>; - clock-names = "clk_xin", "clk_ahb"; - clocks = <&scmi_clk KEEM_BAY_PSS_AUX_EMMC>, - <&scmi_clk KEEM_BAY_PSS_EMMC>; - phys = <&emmc_phy>; - phy-names = "phy_arasan"; - assigned-clocks = <&scmi_clk KEEM_BAY_PSS_AUX_EMMC>; - assigned-clock-rates = <200000000>; - clock-output-names = "emmc_cardclock"; - #clock-cells = <0>; - arasan,soc-ctl-syscon = <&mmc_phy_syscon>; - }; - - sd0: mmc@31000000 { - compatible = "intel,keembay-sdhci-5.1-sd"; - interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; - reg = <0x0 0x31000000 0x0 0x300>; - clock-names = "clk_xin", "clk_ahb"; - clocks = <&scmi_clk KEEM_BAY_PSS_AUX_SD0>, - <&scmi_clk KEEM_BAY_PSS_SD0>; - arasan,soc-ctl-syscon = <&sd0_phy_syscon>; - }; - - sd1: mmc@32000000 { - compatible = "intel,keembay-sdhci-5.1-sdio"; - interrupts = <GIC_SPI 84 IRQ_TYPE_LEVEL_HIGH>; - reg = <0x0 0x32000000 0x0 0x300>; - clock-names = "clk_xin", "clk_ahb"; - clocks = <&scmi_clk KEEM_BAY_PSS_AUX_SD1>, - <&scmi_clk KEEM_BAY_PSS_SD1>; - arasan,soc-ctl-syscon = <&sd1_phy_syscon>; - }; diff --git a/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml b/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml new file mode 100644 index 000000000000..5887c917d480 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/arasan,sdhci.yaml @@ -0,0 +1,299 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/mmc/arasan,sdhci.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Device Tree Bindings for the Arasan SDHCI Controller + +maintainers: + - Adrian Hunter <adrian.hunter@intel.com> + +allOf: + - $ref: "mmc-controller.yaml#" + - if: + properties: + compatible: + contains: + const: arasan,sdhci-5.1 + then: + required: + - phys + - phy-names + - if: + properties: + compatible: + contains: + enum: + - xlnx,zynqmp-8.9a + - xlnx,versal-8.9a + then: + properties: + clock-output-names: + items: + - const: clk_out_sd0 + - const: clk_in_sd0 + +properties: + compatible: + oneOf: + - const: arasan,sdhci-8.9a # generic Arasan SDHCI 8.9a PHY + - const: arasan,sdhci-4.9a # generic Arasan SDHCI 4.9a PHY + - const: arasan,sdhci-5.1 # generic Arasan SDHCI 5.1 PHY + - items: + - const: rockchip,rk3399-sdhci-5.1 # rk3399 eMMC PHY + - const: arasan,sdhci-5.1 + description: + For this device it is strongly suggested to include + arasan,soc-ctl-syscon. + - items: + - const: xlnx,zynqmp-8.9a # ZynqMP SDHCI 8.9a PHY + - const: arasan,sdhci-8.9a + description: + For this device it is strongly suggested to include + clock-output-names and '#clock-cells'. + - items: + - const: xlnx,versal-8.9a # Versal SDHCI 8.9a PHY + - const: arasan,sdhci-8.9a + description: + For this device it is strongly suggested to include + clock-output-names and '#clock-cells'. + - items: + - const: intel,lgm-sdhci-5.1-emmc # Intel LGM eMMC PHY + - const: arasan,sdhci-5.1 + description: + For this device it is strongly suggested to include + arasan,soc-ctl-syscon. + - items: + - const: intel,lgm-sdhci-5.1-sdxc # Intel LGM SDXC PHY + - const: arasan,sdhci-5.1 + description: + For this device it is strongly suggested to include + arasan,soc-ctl-syscon. + - items: + - const: intel,keembay-sdhci-5.1-emmc # Intel Keem Bay eMMC PHY + - const: arasan,sdhci-5.1 + description: + For this device it is strongly suggested to include + arasan,soc-ctl-syscon. + - const: intel,keembay-sdhci-5.1-sd # Intel Keem Bay SD controller + description: + For this device it is strongly suggested to include + arasan,soc-ctl-syscon. + - const: intel,keembay-sdhci-5.1-sdio # Intel Keem Bay SDIO controller + description: + For this device it is strongly suggested to include + arasan,soc-ctl-syscon. + + reg: + maxItems: 1 + + clocks: + minItems: 2 + maxItems: 3 + + clock-names: + minItems: 2 + items: + - const: clk_xin + - const: clk_ahb + - const: gate + + interrupts: + maxItems: 1 + + phys: + maxItems: 1 + + phy-names: + const: phy_arasan + + arasan,soc-ctl-syscon: + $ref: /schemas/types.yaml#/definitions/phandle + description: + A phandle to a syscon device (see ../mfd/syscon.txt) used to access + core corecfg registers. Offsets of registers in this syscon are + determined based on the main compatible string for the device. + + clock-output-names: + minItems: 1 + maxItems: 2 + description: + Name of the card clock which will be exposed by this device. + + '#clock-cells': + enum: [0, 1] + description: + With this property in place we will export one or two clocks + representing the Card Clock. These clocks are expected to be + consumed by our PHY. + + xlnx,fails-without-test-cd: + $ref: /schemas/types.yaml#/definitions/flag + description: + When present, the controller doesn't work when the CD line is not + connected properly, and the line is not connected properly. + Test mode can be used to force the controller to function. + + xlnx,int-clock-stable-broken: + $ref: /schemas/types.yaml#/definitions/flag + description: + When present, the controller always reports that the internal clock + is stable even when it is not. + + xlnx,mio-bank: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 2] + default: 0 + description: + The MIO bank number in which the command and data lines are configured. + +dependencies: + clock-output-names: [ '#clock-cells' ] + '#clock-cells': [ clock-output-names ] + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + mmc@e0100000 { + compatible = "arasan,sdhci-8.9a"; + reg = <0xe0100000 0x1000>; + clock-names = "clk_xin", "clk_ahb"; + clocks = <&clkc 21>, <&clkc 32>; + interrupt-parent = <&gic>; + interrupts = <0 24 4>; + }; + + - | + mmc@e2800000 { + compatible = "arasan,sdhci-5.1"; + reg = <0xe2800000 0x1000>; + clock-names = "clk_xin", "clk_ahb"; + clocks = <&cru 8>, <&cru 18>; + interrupt-parent = <&gic>; + interrupts = <0 24 4>; + phys = <&emmc_phy>; + phy-names = "phy_arasan"; + }; + + - | + #include <dt-bindings/clock/rk3399-cru.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + mmc@fe330000 { + compatible = "rockchip,rk3399-sdhci-5.1", "arasan,sdhci-5.1"; + reg = <0xfe330000 0x10000>; + interrupts = <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru SCLK_EMMC>, <&cru ACLK_EMMC>; + clock-names = "clk_xin", "clk_ahb"; + arasan,soc-ctl-syscon = <&grf>; + assigned-clocks = <&cru SCLK_EMMC>; + assigned-clock-rates = <200000000>; + clock-output-names = "emmc_cardclock"; + phys = <&emmc_phy>; + phy-names = "phy_arasan"; + #clock-cells = <0>; + }; + + - | + mmc@ff160000 { + compatible = "xlnx,zynqmp-8.9a", "arasan,sdhci-8.9a"; + interrupt-parent = <&gic>; + interrupts = <0 48 4>; + reg = <0xff160000 0x1000>; + clocks = <&clk200>, <&clk200>; + clock-names = "clk_xin", "clk_ahb"; + clock-output-names = "clk_out_sd0", "clk_in_sd0"; + #clock-cells = <1>; + clk-phase-sd-hs = <63>, <72>; + }; + + - | + mmc@f1040000 { + compatible = "xlnx,versal-8.9a", "arasan,sdhci-8.9a"; + interrupt-parent = <&gic>; + interrupts = <0 126 4>; + reg = <0xf1040000 0x10000>; + clocks = <&clk200>, <&clk200>; + clock-names = "clk_xin", "clk_ahb"; + clock-output-names = "clk_out_sd0", "clk_in_sd0"; + #clock-cells = <1>; + clk-phase-sd-hs = <132>, <60>; + }; + + - | + #define LGM_CLK_EMMC5 + #define LGM_CLK_NGI + #define LGM_GCLK_EMMC + mmc@ec700000 { + compatible = "intel,lgm-sdhci-5.1-emmc", "arasan,sdhci-5.1"; + reg = <0xec700000 0x300>; + interrupt-parent = <&ioapic1>; + interrupts = <44 1>; + clocks = <&cgu0 LGM_CLK_EMMC5>, <&cgu0 LGM_CLK_NGI>, + <&cgu0 LGM_GCLK_EMMC>; + clock-names = "clk_xin", "clk_ahb", "gate"; + clock-output-names = "emmc_cardclock"; + #clock-cells = <0>; + phys = <&emmc_phy>; + phy-names = "phy_arasan"; + arasan,soc-ctl-syscon = <&sysconf>; + }; + + - | + #define LGM_CLK_SDIO + #define LGM_GCLK_SDXC + mmc@ec600000 { + compatible = "intel,lgm-sdhci-5.1-sdxc", "arasan,sdhci-5.1"; + reg = <0xec600000 0x300>; + interrupt-parent = <&ioapic1>; + interrupts = <43 1>; + clocks = <&cgu0 LGM_CLK_SDIO>, <&cgu0 LGM_CLK_NGI>, + <&cgu0 LGM_GCLK_SDXC>; + clock-names = "clk_xin", "clk_ahb", "gate"; + clock-output-names = "sdxc_cardclock"; + #clock-cells = <0>; + phys = <&sdxc_phy>; + phy-names = "phy_arasan"; + arasan,soc-ctl-syscon = <&sysconf>; + }; + + - | + #define KEEM_BAY_PSS_AUX_EMMC + #define KEEM_BAY_PSS_EMMC + mmc@33000000 { + compatible = "intel,keembay-sdhci-5.1-emmc", "arasan,sdhci-5.1"; + interrupts = <GIC_SPI 82 IRQ_TYPE_LEVEL_HIGH>; + reg = <0x33000000 0x300>; + clock-names = "clk_xin", "clk_ahb"; + clocks = <&scmi_clk KEEM_BAY_PSS_AUX_EMMC>, + <&scmi_clk KEEM_BAY_PSS_EMMC>; + phys = <&emmc_phy>; + phy-names = "phy_arasan"; + assigned-clocks = <&scmi_clk KEEM_BAY_PSS_AUX_EMMC>; + assigned-clock-rates = <200000000>; + clock-output-names = "emmc_cardclock"; + #clock-cells = <0>; + arasan,soc-ctl-syscon = <&mmc_phy_syscon>; + }; + + - | + #define KEEM_BAY_PSS_AUX_SD0 + #define KEEM_BAY_PSS_SD0 + mmc@31000000 { + compatible = "intel,keembay-sdhci-5.1-sd"; + interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; + reg = <0x31000000 0x300>; + clock-names = "clk_xin", "clk_ahb"; + clocks = <&scmi_clk KEEM_BAY_PSS_AUX_SD0>, + <&scmi_clk KEEM_BAY_PSS_SD0>; + arasan,soc-ctl-syscon = <&sd0_phy_syscon>; + }; diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt deleted file mode 100644 index de1b8bd550d3..000000000000 --- a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt +++ /dev/null @@ -1,67 +0,0 @@ -* Freescale Enhanced Secure Digital Host Controller (eSDHC) for i.MX - -The Enhanced Secure Digital Host Controller on Freescale i.MX family -provides an interface for MMC, SD, and SDIO types of memory cards. - -This file documents differences between the core properties described -by mmc.txt and the properties used by the sdhci-esdhc-imx driver. - -Required properties: -- compatible : Should be "fsl,<chip>-esdhc", the supported chips include - "fsl,imx25-esdhc" - "fsl,imx35-esdhc" - "fsl,imx51-esdhc" - "fsl,imx53-esdhc" - "fsl,imx6q-usdhc" - "fsl,imx6sl-usdhc" - "fsl,imx6sx-usdhc" - "fsl,imx6ull-usdhc" - "fsl,imx7d-usdhc" - "fsl,imx7ulp-usdhc" - "fsl,imx8mq-usdhc" - "fsl,imx8mm-usdhc" - "fsl,imx8mn-usdhc" - "fsl,imx8mp-usdhc" - "fsl,imx8qm-usdhc" - "fsl,imx8qxp-usdhc" - -Optional properties: -- fsl,wp-controller : Indicate to use controller internal write protection -- fsl,delay-line : Specify the number of delay cells for override mode. - This is used to set the clock delay for DLL(Delay Line) on override mode - to select a proper data sampling window in case the clock quality is not good - due to signal path is too long on the board. Please refer to eSDHC/uSDHC - chapter, DLL (Delay Line) section in RM for details. -- voltage-ranges : Specify the voltage range in case there are software - transparent level shifters on the outputs of the controller. Two cells are - required, first cell specifies minimum slot voltage (mV), second cell - specifies maximum slot voltage (mV). Several ranges could be specified. -- fsl,tuning-start-tap: Specify the start dealy cell point when send first CMD19 - in tuning procedure. -- fsl,tuning-step: Specify the increasing delay cell steps in tuning procedure. - The uSDHC use one delay cell as default increasing step to do tuning process. - This property allows user to change the tuning step to more than one delay - cells which is useful for some special boards or cards when the default - tuning step can't find the proper delay window within limited tuning retries. -- fsl,strobe-dll-delay-target: Specify the strobe dll control slave delay target. - This delay target programming host controller loopback read clock, and this - property allows user to change the delay target for the strobe input read clock. - If not use this property, driver default set the delay target to value 7. - Only eMMC HS400 mode need to take care of this property. - -Examples: - -esdhc@70004000 { - compatible = "fsl,imx51-esdhc"; - reg = <0x70004000 0x4000>; - interrupts = <1>; - fsl,wp-controller; -}; - -esdhc@70008000 { - compatible = "fsl,imx51-esdhc"; - reg = <0x70008000 0x4000>; - interrupts = <2>; - cd-gpios = <&gpio1 6 0>; /* GPIO1_6 */ - wp-gpios = <&gpio1 5 0>; /* GPIO1_5 */ -}; diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml new file mode 100644 index 000000000000..75dc1168d717 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml @@ -0,0 +1,124 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/fsl-imx-esdhc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale Enhanced Secure Digital Host Controller (eSDHC) for i.MX + +maintainers: + - Shawn Guo <shawn.guo@linaro.org> + +allOf: + - $ref: "mmc-controller.yaml" + +description: | + The Enhanced Secure Digital Host Controller on Freescale i.MX family + provides an interface for MMC, SD, and SDIO types of memory cards. + + This file documents differences between the core properties described + by mmc.txt and the properties used by the sdhci-esdhc-imx driver. + +properties: + compatible: + enum: + - fsl,imx25-esdhc + - fsl,imx35-esdhc + - fsl,imx51-esdhc + - fsl,imx53-esdhc + - fsl,imx6q-usdhc + - fsl,imx6sl-usdhc + - fsl,imx6sx-usdhc + - fsl,imx6ull-usdhc + - fsl,imx7d-usdhc + - fsl,imx7ulp-usdhc + - fsl,imx8mq-usdhc + - fsl,imx8mm-usdhc + - fsl,imx8mn-usdhc + - fsl,imx8mp-usdhc + - fsl,imx8qm-usdhc + - fsl,imx8qxp-usdhc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + fsl,wp-controller: + description: | + boolean, if present, indicate to use controller internal write protection. + type: boolean + + fsl,delay-line: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Specify the number of delay cells for override mode. + This is used to set the clock delay for DLL(Delay Line) on override mode + to select a proper data sampling window in case the clock quality is not good + due to signal path is too long on the board. Please refer to eSDHC/uSDHC + chapter, DLL (Delay Line) section in RM for details. + default: 0 + + voltage-ranges: + $ref: '/schemas/types.yaml#/definitions/uint32-matrix' + description: | + Specify the voltage range in case there are software transparent level + shifters on the outputs of the controller. Two cells are required, first + cell specifies minimum slot voltage (mV), second cell specifies maximum + slot voltage (mV). + items: + items: + - description: value for minimum slot voltage + - description: value for maximum slot voltage + maxItems: 1 + + fsl,tuning-start-tap: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Specify the start delay cell point when send first CMD19 in tuning procedure. + default: 0 + + fsl,tuning-step: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Specify the increasing delay cell steps in tuning procedure. + The uSDHC use one delay cell as default increasing step to do tuning process. + This property allows user to change the tuning step to more than one delay + cells which is useful for some special boards or cards when the default + tuning step can't find the proper delay window within limited tuning retries. + default: 0 + + fsl,strobe-dll-delay-target: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Specify the strobe dll control slave delay target. + This delay target programming host controller loopback read clock, and this + property allows user to change the delay target for the strobe input read clock. + If not use this property, driver default set the delay target to value 7. + Only eMMC HS400 mode need to take care of this property. + default: 0 + +required: + - compatible + - reg + - interrupts + +unevaluatedProperties: false + +examples: + - | + mmc@70004000 { + compatible = "fsl,imx51-esdhc"; + reg = <0x70004000 0x4000>; + interrupts = <1>; + fsl,wp-controller; + }; + + mmc@70008000 { + compatible = "fsl,imx51-esdhc"; + reg = <0x70008000 0x4000>; + interrupts = <2>; + cd-gpios = <&gpio1 6 0>; /* GPIO1_6 */ + wp-gpios = <&gpio1 5 0>; /* GPIO1_5 */ + }; diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-mmc.txt b/Documentation/devicetree/bindings/mmc/fsl-imx-mmc.txt deleted file mode 100644 index 184ccffe2739..000000000000 --- a/Documentation/devicetree/bindings/mmc/fsl-imx-mmc.txt +++ /dev/null @@ -1,23 +0,0 @@ -* Freescale Secure Digital Host Controller for i.MX2/3 series - -This file documents differences to the properties defined in mmc.txt. - -Required properties: -- compatible : Should be "fsl,<chip>-mmc", chip can be imx21 or imx31 - -Optional properties: -- dmas: One DMA phandle with arguments as defined by the devicetree bindings - of the used DMA controller. -- dma-names: Has to be "rx-tx". - -Example: - -sdhci1: sdhci@10014000 { - compatible = "fsl,imx27-mmc", "fsl,imx21-mmc"; - reg = <0x10014000 0x1000>; - interrupts = <11>; - dmas = <&dma 7>; - dma-names = "rx-tx"; - bus-width = <4>; - cd-gpios = <&gpio3 29>; -}; diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-mmc.yaml b/Documentation/devicetree/bindings/mmc/fsl-imx-mmc.yaml new file mode 100644 index 000000000000..ffa162722b8e --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/fsl-imx-mmc.yaml @@ -0,0 +1,53 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/fsl-imx-mmc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale Secure Digital Host Controller for i.MX2/3 series + +maintainers: + - Markus Pargmann <mpa@pengutronix.de> + +allOf: + - $ref: "mmc-controller.yaml" + +properties: + compatible: + oneOf: + - const: fsl,imx21-mmc + - const: fsl,imx31-mmc + - items: + - const: fsl,imx27-mmc + - const: fsl,imx21-mmc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + dmas: + maxItems: 1 + + dma-names: + const: rx-tx + +required: + - compatible + - reg + - interrupts + +unevaluatedProperties: false + +examples: + - | + mmc@10014000 { + compatible = "fsl,imx27-mmc", "fsl,imx21-mmc"; + reg = <0x10014000 0x1000>; + interrupts = <11>; + dmas = <&dma 7>; + dma-names = "rx-tx"; + bus-width = <4>; + cd-gpios = <&gpio3 29>; + }; diff --git a/Documentation/devicetree/bindings/mmc/mmc-controller.yaml b/Documentation/devicetree/bindings/mmc/mmc-controller.yaml index 4931fab34d81..b96da0c7f819 100644 --- a/Documentation/devicetree/bindings/mmc/mmc-controller.yaml +++ b/Documentation/devicetree/bindings/mmc/mmc-controller.yaml @@ -169,6 +169,11 @@ properties: description: Full power cycle of the card is supported. + full-pwr-cycle-in-suspend: + $ref: /schemas/types.yaml#/definitions/flag + description: + Full power cycle of the card in suspend is supported. + mmc-ddr-1_2v: $ref: /schemas/types.yaml#/definitions/flag description: diff --git a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-emmc.txt b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-emmc.txt deleted file mode 100644 index 3d965d57e00b..000000000000 --- a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-emmc.txt +++ /dev/null @@ -1,25 +0,0 @@ -* The simple eMMC hardware reset provider - -The purpose of this driver is to perform standard eMMC hw reset -procedure, as described by Jedec 4.4 specification. This procedure is -performed just after MMC core enabled power to the given mmc host (to -fix possible issues if bootloader has left eMMC card in initialized or -unknown state), and before performing complete system reboot (also in -case of emergency reboot call). The latter is needed on boards, which -doesn't have hardware reset logic connected to emmc card and (limited or -broken) ROM bootloaders are unable to read second stage from the emmc -card if the card is left in unknown or already initialized state. - -Required properties: -- compatible : contains "mmc-pwrseq-emmc". -- reset-gpios : contains a GPIO specifier. The reset GPIO is asserted - and then deasserted to perform eMMC card reset. To perform - reset procedure as described in Jedec 4.4 specification, the - gpio line should be defined as GPIO_ACTIVE_LOW. - -Example: - - sdhci0_pwrseq { - compatible = "mmc-pwrseq-emmc"; - reset-gpios = <&gpio1 12 GPIO_ACTIVE_LOW>; - } diff --git a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-emmc.yaml b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-emmc.yaml new file mode 100644 index 000000000000..77f746f57284 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-emmc.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/mmc-pwrseq-emmc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Simple eMMC hardware reset provider binding + +maintainers: + - Ulf Hansson <ulf.hansson@linaro.org> + +description: + The purpose of this driver is to perform standard eMMC hw reset + procedure, as described by Jedec 4.4 specification. This procedure is + performed just after MMC core enabled power to the given mmc host (to + fix possible issues if bootloader has left eMMC card in initialized or + unknown state), and before performing complete system reboot (also in + case of emergency reboot call). The latter is needed on boards, which + doesn't have hardware reset logic connected to emmc card and (limited or + broken) ROM bootloaders are unable to read second stage from the emmc + card if the card is left in unknown or already initialized state. + +properties: + compatible: + const: mmc-pwrseq-emmc + + reset-gpios: + minItems: 1 + description: + contains a GPIO specifier. The reset GPIO is asserted + and then deasserted to perform eMMC card reset. To perform + reset procedure as described in Jedec 4.4 specification, the + gpio line should be defined as GPIO_ACTIVE_LOW. + +required: + - compatible + - reset-gpios + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + sdhci0_pwrseq { + compatible = "mmc-pwrseq-emmc"; + reset-gpios = <&gpio1 12 GPIO_ACTIVE_LOW>; + }; +... diff --git a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-sd8787.txt b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-sd8787.txt deleted file mode 100644 index 22e9340e4ba2..000000000000 --- a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-sd8787.txt +++ /dev/null @@ -1,16 +0,0 @@ -* Marvell SD8787 power sequence provider - -Required properties: -- compatible: must be "mmc-pwrseq-sd8787". -- powerdown-gpios: contains a power down GPIO specifier with the - default active state -- reset-gpios: contains a reset GPIO specifier with the default - active state - -Example: - - wifi_pwrseq: wifi_pwrseq { - compatible = "mmc-pwrseq-sd8787"; - powerdown-gpios = <&twl_gpio 0 GPIO_ACTIVE_LOW>; - reset-gpios = <&twl_gpio 1 GPIO_ACTIVE_LOW>; - } diff --git a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-sd8787.yaml b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-sd8787.yaml new file mode 100644 index 000000000000..a68820d31d50 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-sd8787.yaml @@ -0,0 +1,39 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/mmc-pwrseq-sd8787.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell SD8787 power sequence provider binding + +maintainers: + - Ulf Hansson <ulf.hansson@linaro.org> + +properties: + compatible: + const: mmc-pwrseq-sd8787 + + powerdown-gpios: + minItems: 1 + description: + contains a power down GPIO specifier with the default active state + + reset-gpios: + minItems: 1 + description: + contains a reset GPIO specifier with the default active state + +required: + - compatible + - powerdown-gpios + - reset-gpios + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + wifi_pwrseq: wifi_pwrseq { + compatible = "mmc-pwrseq-sd8787"; + powerdown-gpios = <&twl_gpio 0 GPIO_ACTIVE_LOW>; + reset-gpios = <&twl_gpio 1 GPIO_ACTIVE_LOW>; + }; +... diff --git a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.txt b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.txt deleted file mode 100644 index 9029b45b8a22..000000000000 --- a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.txt +++ /dev/null @@ -1,31 +0,0 @@ -* The simple MMC power sequence provider - -The purpose of the simple MMC power sequence provider is to supports a set of -common properties between various SOC designs. It thus enables us to use the -same provider for several SOC designs. - -Required properties: -- compatible : contains "mmc-pwrseq-simple". - -Optional properties: -- reset-gpios : contains a list of GPIO specifiers. The reset GPIOs are asserted - at initialization and prior we start the power up procedure of the card. - They will be de-asserted right after the power has been provided to the - card. -- clocks : Must contain an entry for the entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names : Must include the following entry: - "ext_clock" (External clock provided to the card). -- post-power-on-delay-ms : Delay in ms after powering the card and - de-asserting the reset-gpios (if any) -- power-off-delay-us : Delay in us after asserting the reset-gpios (if any) - during power off of the card. - -Example: - - sdhci0_pwrseq { - compatible = "mmc-pwrseq-simple"; - reset-gpios = <&gpio1 12 GPIO_ACTIVE_LOW>; - clocks = <&clk_32768_ck>; - clock-names = "ext_clock"; - } diff --git a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.yaml b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.yaml new file mode 100644 index 000000000000..449215444723 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/mmc-pwrseq-simple.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Simple MMC power sequence provider binding + +maintainers: + - Ulf Hansson <ulf.hansson@linaro.org> + +description: + The purpose of the simple MMC power sequence provider is to supports a set + of common properties between various SOC designs. It thus enables us to use + the same provider for several SOC designs. + +properties: + compatible: + const: mmc-pwrseq-simple + + reset-gpios: + minItems: 1 + description: + contains a list of GPIO specifiers. The reset GPIOs are asserted + at initialization and prior we start the power up procedure of the card. + They will be de-asserted right after the power has been provided to the + card. + + clocks: + minItems: 1 + description: Handle for the entry in clock-names. + + clock-names: + items: + - const: ext_clock + description: External clock provided to the card. + + post-power-on-delay-ms: + description: + Delay in ms after powering the card and de-asserting the + reset-gpios (if any). + $ref: /schemas/types.yaml#/definitions/uint32 + + power-off-delay-us: + description: + Delay in us after asserting the reset-gpios (if any) + during power off of the card. + $ref: /schemas/types.yaml#/definitions/uint32 + +required: + - compatible + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + sdhci0_pwrseq { + compatible = "mmc-pwrseq-simple"; + reset-gpios = <&gpio1 12 GPIO_ACTIVE_LOW>; + clocks = <&clk_32768_ck>; + clock-names = "ext_clock"; + }; +... diff --git a/Documentation/devicetree/bindings/mmc/mtk-sd.txt b/Documentation/devicetree/bindings/mmc/mtk-sd.txt index 8a532f4453f2..0c9cf6a8808c 100644 --- a/Documentation/devicetree/bindings/mmc/mtk-sd.txt +++ b/Documentation/devicetree/bindings/mmc/mtk-sd.txt @@ -12,6 +12,7 @@ Required properties: "mediatek,mt8173-mmc": for mmc host ip compatible with mt8173 "mediatek,mt8183-mmc": for mmc host ip compatible with mt8183 "mediatek,mt8516-mmc": for mmc host ip compatible with mt8516 + "mediatek,mt6779-mmc": for mmc host ip compatible with mt6779 "mediatek,mt2701-mmc": for mmc host ip compatible with mt2701 "mediatek,mt2712-mmc": for mmc host ip compatible with mt2712 "mediatek,mt7622-mmc": for MT7622 SoC diff --git a/Documentation/devicetree/bindings/mmc/mxs-mmc.txt b/Documentation/devicetree/bindings/mmc/mxs-mmc.txt deleted file mode 100644 index 515addc20070..000000000000 --- a/Documentation/devicetree/bindings/mmc/mxs-mmc.txt +++ /dev/null @@ -1,27 +0,0 @@ -* Freescale MXS MMC controller - -The Freescale MXS Synchronous Serial Ports (SSP) can act as a MMC controller -to support MMC, SD, and SDIO types of memory cards. - -This file documents differences between the core properties in mmc.txt -and the properties used by the mxsmmc driver. - -Required properties: -- compatible: Should be "fsl,<chip>-mmc". The supported chips include - imx23 and imx28. -- interrupts: Should contain ERROR interrupt number -- dmas: DMA specifier, consisting of a phandle to DMA controller node - and SSP DMA channel ID. - Refer to dma.txt and fsl-mxs-dma.txt for details. -- dma-names: Must be "rx-tx". - -Examples: - -ssp0: ssp@80010000 { - compatible = "fsl,imx28-mmc"; - reg = <0x80010000 2000>; - interrupts = <96>; - dmas = <&dma_apbh 0>; - dma-names = "rx-tx"; - bus-width = <8>; -}; diff --git a/Documentation/devicetree/bindings/mmc/mxs-mmc.yaml b/Documentation/devicetree/bindings/mmc/mxs-mmc.yaml new file mode 100644 index 000000000000..1cccc0478d49 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/mxs-mmc.yaml @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/mxs-mmc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale MXS MMC controller + +maintainers: + - Shawn Guo <shawn.guo@linaro.org> + +description: | + The Freescale MXS Synchronous Serial Ports (SSP) can act as a MMC controller + to support MMC, SD, and SDIO types of memory cards. + + This file documents differences between the core properties in mmc.txt + and the properties used by the mxsmmc driver. + +allOf: + - $ref: "mmc-controller.yaml" + +properties: + compatible: + enum: + - fsl,imx23-mmc + - fsl,imx28-mmc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + dmas: + maxItems: 1 + + dma-names: + const: rx-tx + +required: + - compatible + - reg + - interrupts + - dmas + - dma-names + +unevaluatedProperties: false + +examples: + - | + mmc@80010000 { + compatible = "fsl,imx28-mmc"; + reg = <0x80010000 2000>; + interrupts = <96>; + dmas = <&dma_apbh 0>; + dma-names = "rx-tx"; + bus-width = <8>; + }; diff --git a/Documentation/devicetree/bindings/mmc/renesas,sdhi.txt b/Documentation/devicetree/bindings/mmc/renesas,sdhi.txt deleted file mode 100644 index 0ca9a622cce0..000000000000 --- a/Documentation/devicetree/bindings/mmc/renesas,sdhi.txt +++ /dev/null @@ -1,114 +0,0 @@ -* Renesas SDHI SD/MMC controller - -Required properties: -- compatible: should contain one or more of the following: - "renesas,sdhi-sh73a0" - SDHI IP on SH73A0 SoC - "renesas,sdhi-r7s72100" - SDHI IP on R7S72100 SoC - "renesas,sdhi-r7s9210" - SDHI IP on R7S9210 SoC - "renesas,sdhi-r8a73a4" - SDHI IP on R8A73A4 SoC - "renesas,sdhi-r8a7740" - SDHI IP on R8A7740 SoC - "renesas,sdhi-r8a7742" - SDHI IP on R8A7742 SoC - "renesas,sdhi-r8a7743" - SDHI IP on R8A7743 SoC - "renesas,sdhi-r8a7744" - SDHI IP on R8A7744 SoC - "renesas,sdhi-r8a7745" - SDHI IP on R8A7745 SoC - "renesas,sdhi-r8a774a1" - SDHI IP on R8A774A1 SoC - "renesas,sdhi-r8a774b1" - SDHI IP on R8A774B1 SoC - "renesas,sdhi-r8a774c0" - SDHI IP on R8A774C0 SoC - "renesas,sdhi-r8a77470" - SDHI IP on R8A77470 SoC - "renesas,sdhi-mmc-r8a77470" - SDHI/MMC IP on R8A77470 SoC - "renesas,sdhi-r8a7778" - SDHI IP on R8A7778 SoC - "renesas,sdhi-r8a7779" - SDHI IP on R8A7779 SoC - "renesas,sdhi-r8a7790" - SDHI IP on R8A7790 SoC - "renesas,sdhi-r8a7791" - SDHI IP on R8A7791 SoC - "renesas,sdhi-r8a7792" - SDHI IP on R8A7792 SoC - "renesas,sdhi-r8a7793" - SDHI IP on R8A7793 SoC - "renesas,sdhi-r8a7794" - SDHI IP on R8A7794 SoC - "renesas,sdhi-r8a7795" - SDHI IP on R8A7795 SoC - "renesas,sdhi-r8a7796" - SDHI IP on R8A77960 SoC - "renesas,sdhi-r8a77961" - SDHI IP on R8A77961 SoC - "renesas,sdhi-r8a77965" - SDHI IP on R8A77965 SoC - "renesas,sdhi-r8a77970" - SDHI IP on R8A77970 SoC - "renesas,sdhi-r8a77980" - SDHI IP on R8A77980 SoC - "renesas,sdhi-r8a77990" - SDHI IP on R8A77990 SoC - "renesas,sdhi-r8a77995" - SDHI IP on R8A77995 SoC - "renesas,sdhi-shmobile" - a generic sh-mobile SDHI controller - "renesas,rcar-gen1-sdhi" - a generic R-Car Gen1 SDHI controller - "renesas,rcar-gen2-sdhi" - a generic R-Car Gen2 and RZ/G1 SDHI - (not SDHI/MMC) controller - "renesas,rcar-gen3-sdhi" - a generic R-Car Gen3 or RZ/G2 - SDHI controller - - - When compatible with the generic version, nodes must list - the SoC-specific version corresponding to the platform - first followed by the generic version. - -- clocks: Most controllers only have 1 clock source per channel. However, on - some variations of this controller, the internal card detection - logic that exists in this controller is sectioned off to be run by a - separate second clock source to allow the main core clock to be turned - off to save power. - If 2 clocks are specified by the hardware, you must name them as - "core" and "cd". If the controller only has 1 clock, naming is not - required. - Devices which have more than 1 clock are listed below: - 2: R7S72100, R7S9210 - -Optional properties: -- pinctrl-names: should be "default", "state_uhs" -- pinctrl-0: should contain default/high speed pin ctrl -- pinctrl-1: should contain uhs mode pin ctrl - -Example: R8A7790 (R-Car H2) SDHI controller nodes - - sdhi0: sd@ee100000 { - compatible = "renesas,sdhi-r8a7790", "renesas,rcar-gen2-sdhi"; - reg = <0 0xee100000 0 0x328>; - interrupts = <GIC_SPI 165 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 314>; - dmas = <&dmac0 0xcd>, <&dmac0 0xce>, - <&dmac1 0xcd>, <&dmac1 0xce>; - dma-names = "tx", "rx", "tx", "rx"; - max-frequency = <195000000>; - power-domains = <&sysc R8A7790_PD_ALWAYS_ON>; - resets = <&cpg 314>; - }; - - sdhi1: sd@ee120000 { - compatible = "renesas,sdhi-r8a7790", "renesas,rcar-gen2-sdhi"; - reg = <0 0xee120000 0 0x328>; - interrupts = <GIC_SPI 166 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 313>; - dmas = <&dmac0 0xc9>, <&dmac0 0xca>, - <&dmac1 0xc9>, <&dmac1 0xca>; - dma-names = "tx", "rx", "tx", "rx"; - max-frequency = <195000000>; - power-domains = <&sysc R8A7790_PD_ALWAYS_ON>; - resets = <&cpg 313>; - }; - - sdhi2: sd@ee140000 { - compatible = "renesas,sdhi-r8a7790", "renesas,rcar-gen2-sdhi"; - reg = <0 0xee140000 0 0x100>; - interrupts = <GIC_SPI 167 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 312>; - dmas = <&dmac0 0xc1>, <&dmac0 0xc2>, - <&dmac1 0xc1>, <&dmac1 0xc2>; - dma-names = "tx", "rx", "tx", "rx"; - max-frequency = <97500000>; - power-domains = <&sysc R8A7790_PD_ALWAYS_ON>; - resets = <&cpg 312>; - }; - - sdhi3: sd@ee160000 { - compatible = "renesas,sdhi-r8a7790", "renesas,rcar-gen2-sdhi"; - reg = <0 0xee160000 0 0x100>; - interrupts = <GIC_SPI 168 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 311>; - dmas = <&dmac0 0xd3>, <&dmac0 0xd4>, - <&dmac1 0xd3>, <&dmac1 0xd4>; - dma-names = "tx", "rx", "tx", "rx"; - max-frequency = <97500000>; - power-domains = <&sysc R8A7790_PD_ALWAYS_ON>; - resets = <&cpg 311>; - }; diff --git a/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml new file mode 100644 index 000000000000..e5dbc20456e5 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml @@ -0,0 +1,191 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/mmc/renesas,sdhi.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Renesas SDHI SD/MMC controller + +maintainers: + - Wolfram Sang <wsa+renesas@sang-engineering.com> + +allOf: + - $ref: "mmc-controller.yaml" + +properties: + compatible: + oneOf: + - items: + - const: renesas,sdhi-sh73a0 # R-Mobile APE6 + - items: + - const: renesas,sdhi-r7s72100 # RZ/A1H + - items: + - const: renesas,sdhi-r7s9210 # SH-Mobile AG5 + - items: + - const: renesas,sdhi-r8a73a4 # R-Mobile APE6 + - items: + - const: renesas,sdhi-r8a7740 # R-Mobile A1 + - items: + - enum: + - renesas,sdhi-r8a7778 # R-Car M1 + - renesas,sdhi-r8a7779 # R-Car H1 + - const: renesas,rcar-gen1-sdhi # R-Car Gen1 + - items: + - enum: + - renesas,sdhi-r8a7742 # RZ/G1H + - renesas,sdhi-r8a7743 # RZ/G1M + - renesas,sdhi-r8a7744 # RZ/G1N + - renesas,sdhi-r8a7745 # RZ/G1E + - renesas,sdhi-r8a77470 # RZ/G1C + - renesas,sdhi-r8a7790 # R-Car H2 + - renesas,sdhi-r8a7791 # R-Car M2-W + - renesas,sdhi-r8a7792 # R-Car V2H + - renesas,sdhi-r8a7793 # R-Car M2-N + - renesas,sdhi-r8a7794 # R-Car E2 + - const: renesas,rcar-gen2-sdhi # R-Car Gen2 and RZ/G1 + - items: + - const: renesas,sdhi-mmc-r8a77470 # RZ/G1C (SDHI/MMC IP) + - items: + - enum: + - renesas,sdhi-r8a774a1 # RZ/G2M + - renesas,sdhi-r8a774b1 # RZ/G2N + - renesas,sdhi-r8a774c0 # RZ/G2E + - renesas,sdhi-r8a7795 # R-Car H3 + - renesas,sdhi-r8a7796 # R-Car M3-W + - renesas,sdhi-r8a77961 # R-Car M3-W+ + - renesas,sdhi-r8a77965 # R-Car M3-N + - renesas,sdhi-r8a77970 # R-Car V3M + - renesas,sdhi-r8a77980 # R-Car V3H + - renesas,sdhi-r8a77990 # R-Car E3 + - renesas,sdhi-r8a77995 # R-Car D3 + - const: renesas,rcar-gen3-sdhi # R-Car Gen3 or RZ/G2 + + reg: + maxItems: 1 + + interrupts: + minItems: 1 + maxItems: 3 + + clocks: + minItems: 1 + maxItems: 2 + + clock-names: + minItems: 1 + maxItems: 2 + items: + - const: core + - const: cd + + dmas: + minItems: 4 + maxItems: 4 + + dma-names: + minItems: 4 + maxItems: 4 + items: + enum: + - tx + - rx + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + + pinctrl-0: + minItems: 1 + maxItems: 2 + + pinctrl-1: + maxItems: 1 + + pinctrl-names: + minItems: 1 + maxItems: 2 + items: + - const: default + - const: state_uhs + + max-frequency: true + +required: + - compatible + - reg + - interrupts + - clocks + - power-domains + +if: + properties: + compatible: + items: + enum: + - renesas,sdhi-r7s72100 + - renesas,sdhi-r7s9210 +then: + required: + - clock-names + description: + The internal card detection logic that exists in these controllers is + sectioned off to be run by a separate second clock source to allow + the main core clock to be turned off to save power. + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a7790-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a7790-sysc.h> + + sdhi0: mmc@ee100000 { + compatible = "renesas,sdhi-r8a7790", "renesas,rcar-gen2-sdhi"; + reg = <0xee100000 0x328>; + interrupts = <GIC_SPI 165 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 314>; + dmas = <&dmac0 0xcd>, <&dmac0 0xce>, <&dmac1 0xcd>, <&dmac1 0xce>; + dma-names = "tx", "rx", "tx", "rx"; + max-frequency = <195000000>; + power-domains = <&sysc R8A7790_PD_ALWAYS_ON>; + resets = <&cpg 314>; + }; + + sdhi1: mmc@ee120000 { + compatible = "renesas,sdhi-r8a7790", "renesas,rcar-gen2-sdhi"; + reg = <0xee120000 0x328>; + interrupts = <GIC_SPI 166 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 313>; + dmas = <&dmac0 0xc9>, <&dmac0 0xca>, <&dmac1 0xc9>, <&dmac1 0xca>; + dma-names = "tx", "rx", "tx", "rx"; + max-frequency = <195000000>; + power-domains = <&sysc R8A7790_PD_ALWAYS_ON>; + resets = <&cpg 313>; + }; + + sdhi2: mmc@ee140000 { + compatible = "renesas,sdhi-r8a7790", "renesas,rcar-gen2-sdhi"; + reg = <0xee140000 0x100>; + interrupts = <GIC_SPI 167 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 312>; + dmas = <&dmac0 0xc1>, <&dmac0 0xc2>, <&dmac1 0xc1>, <&dmac1 0xc2>; + dma-names = "tx", "rx", "tx", "rx"; + max-frequency = <97500000>; + power-domains = <&sysc R8A7790_PD_ALWAYS_ON>; + resets = <&cpg 312>; + }; + + sdhi3: mmc@ee160000 { + compatible = "renesas,sdhi-r8a7790", "renesas,rcar-gen2-sdhi"; + reg = <0xee160000 0x100>; + interrupts = <GIC_SPI 168 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 311>; + dmas = <&dmac0 0xd3>, <&dmac0 0xd4>, <&dmac1 0xd3>, <&dmac1 0xd4>; + dma-names = "tx", "rx", "tx", "rx"; + max-frequency = <97500000>; + power-domains = <&sysc R8A7790_PD_ALWAYS_ON>; + resets = <&cpg 311>; + }; diff --git a/Documentation/devicetree/bindings/mmc/sdhci-am654.txt b/Documentation/devicetree/bindings/mmc/sdhci-am654.txt index c6ccecb9ae5a..6d202f4d9249 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-am654.txt +++ b/Documentation/devicetree/bindings/mmc/sdhci-am654.txt @@ -39,6 +39,7 @@ Optional Properties (Required for ti,am654-sdhci-5.1 and ti,j721e-sdhci-8bit): Valid values are 33, 40, 50, 66 and 100 ohms. Optional Properties: - ti,strobe-sel: strobe select delay for HS400 speed mode. Default value: 0x0. + - ti,clkbuf-sel: Clock Delay Buffer Select Example: diff --git a/Documentation/devicetree/bindings/mmc/sdhci-msm.txt b/Documentation/devicetree/bindings/mmc/sdhci-msm.txt index b8e1d2b7aea9..3b602fd6180b 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-msm.txt +++ b/Documentation/devicetree/bindings/mmc/sdhci-msm.txt @@ -54,6 +54,21 @@ Required properties: - qcom,dll-config: Chipset and Platform specific value. Use this field to specify the DLL_CONFIG register value as per Hardware Programming Guide. +Optional Properties: +* Following bus parameters are required for interconnect bandwidth scaling: +- interconnects: Pairs of phandles and interconnect provider specifier + to denote the edge source and destination ports of + the interconnect path. + +- interconnect-names: For sdhc, we have two main paths. + 1. Data path : sdhc to ddr + 2. Config path : cpu to sdhc + For Data interconnect path the name supposed to be + is "sdhc-ddr" and for config interconnect path it is + "cpu-sdhc". + Please refer to Documentation/devicetree/bindings/ + interconnect/ for more details. + Example: sdhc_1: sdhci@f9824900 { @@ -71,6 +86,9 @@ Example: clocks = <&gcc GCC_SDCC1_APPS_CLK>, <&gcc GCC_SDCC1_AHB_CLK>; clock-names = "core", "iface"; + interconnects = <&qnoc MASTER_SDCC_ID &qnoc SLAVE_DDR_ID>, + <&qnoc MASTER_CPU_ID &qnoc SLAVE_SDCC_ID>; + interconnect-names = "sdhc-ddr","cpu-sdhc"; qcom,dll-config = <0x000f642c>; qcom,ddr-config = <0x80040868>; diff --git a/Documentation/devicetree/bindings/mtd/gpmi-nand.txt b/Documentation/devicetree/bindings/mtd/gpmi-nand.txt deleted file mode 100644 index 393588385c6e..000000000000 --- a/Documentation/devicetree/bindings/mtd/gpmi-nand.txt +++ /dev/null @@ -1,75 +0,0 @@ -* Freescale General-Purpose Media Interface (GPMI) - -The GPMI nand controller provides an interface to control the -NAND flash chips. - -Required properties: - - compatible : should be "fsl,<chip>-gpmi-nand", chip can be: - * imx23 - * imx28 - * imx6q - * imx6sx - * imx7d - - reg : should contain registers location and length for gpmi and bch. - - reg-names: Should contain the reg names "gpmi-nand" and "bch" - - interrupts : BCH interrupt number. - - interrupt-names : Should be "bch". - - dmas: DMA specifier, consisting of a phandle to DMA controller node - and GPMI DMA channel ID. - Refer to dma.txt and fsl-mxs-dma.txt for details. - - dma-names: Must be "rx-tx". - - clocks : clocks phandle and clock specifier corresponding to each clock - specified in clock-names. - - clock-names : The "gpmi_io" clock is always required. Which clocks are - exactly required depends on chip: - * imx23/imx28 : "gpmi_io" - * imx6q/sx : "gpmi_io", "gpmi_apb", "gpmi_bch", "gpmi_bch_apb", "per1_bch" - * imx7d : "gpmi_io", "gpmi_bch_apb" - -Optional properties: - - nand-on-flash-bbt: boolean to enable on flash bbt option if not - present false - - fsl,use-minimum-ecc: Protect this NAND flash with the minimum ECC - strength required. The required ECC strength is - automatically discoverable for some flash - (e.g., according to the ONFI standard). - However, note that if this strength is not - discoverable or this property is not enabled, - the software may chooses an implementation-defined - ECC scheme. - - fsl,no-blockmark-swap: Don't swap the bad block marker from the OOB - area with the byte in the data area but rely on the - flash based BBT for identifying bad blocks. - NOTE: this is only valid in conjunction with - 'nand-on-flash-bbt'. - WARNING: on i.MX28 blockmark swapping cannot be - disabled for the BootROM in the FCB. Thus, - partitions written from Linux with this feature - turned on may not be accessible by the BootROM - code. - - nand-ecc-strength: integer representing the number of bits to correct - per ECC step. Needs to be a multiple of 2. - - nand-ecc-step-size: integer representing the number of data bytes - that are covered by a single ECC step. The driver - supports 512 and 1024. - -The device tree may optionally contain sub-nodes describing partitions of the -address space. See partition.txt for more detail. - -Examples: - -gpmi-nand@8000c000 { - compatible = "fsl,imx28-gpmi-nand"; - #address-cells = <1>; - #size-cells = <1>; - reg = <0x8000c000 2000>, <0x8000a000 2000>; - reg-names = "gpmi-nand", "bch"; - interrupts = <41>; - interrupt-names = "bch"; - dmas = <&dma_apbh 4>; - dma-names = "rx-tx"; - - partition@0 { - ... - }; -}; diff --git a/Documentation/devicetree/bindings/mtd/gpmi-nand.yaml b/Documentation/devicetree/bindings/mtd/gpmi-nand.yaml new file mode 100644 index 000000000000..354cb63feea3 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/gpmi-nand.yaml @@ -0,0 +1,118 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/gpmi-nand.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale General-Purpose Media Interface (GPMI) binding + +maintainers: + - Han Xu <han.xu@nxp.com> + +allOf: + - $ref: "nand-controller.yaml" + +description: | + The GPMI nand controller provides an interface to control the NAND + flash chips. The device tree may optionally contain sub-nodes + describing partitions of the address space. See partition.txt for + more detail. + +properties: + compatible: + enum: + - fsl,imx23-gpmi-nand + - fsl,imx28-gpmi-nand + - fsl,imx6q-gpmi-nand + - fsl,imx6sx-gpmi-nand + - fsl,imx7d-gpmi-nand + + reg: + items: + - description: Address and length of gpmi block. + - description: Address and length of bch block. + + reg-names: + items: + - const: gpmi-nand + - const: bch + + interrupts: + maxItems: 1 + + interrupt-names: + const: bch + + dmas: + maxItems: 1 + + dma-names: + const: rx-tx + + clocks: + minItems: 1 + maxItems: 5 + items: + - description: SoC gpmi io clock + - description: SoC gpmi apb clock + - description: SoC gpmi bch clock + - description: SoC gpmi bch apb clock + - description: SoC per1 bch clock + + clock-names: + minItems: 1 + maxItems: 5 + items: + - const: gpmi_io + - const: gpmi_apb + - const: gpmi_bch + - const: gpmi_bch_apb + - const: per1_bch + + fsl,use-minimum-ecc: + type: boolean + description: | + Protect this NAND flash with the minimum ECC strength required. + The required ECC strength is automatically discoverable for some + flash (e.g., according to the ONFI standard). However, note that + if this strength is not discoverable or this property is not enabled, + the software may chooses an implementation-defined ECC scheme. + + fsl,no-blockmark-swap: + type: boolean + description: | + Don't swap the bad block marker from the OOB area with the byte in + the data area but rely on the flash based BBT for identifying bad blocks. + NOTE: this is only valid in conjunction with 'nand-on-flash-bbt'. + WARNING: on i.MX28 blockmark swapping cannot be disabled for the BootROM + in the FCB. Thus, partitions written from Linux with this feature turned + on may not be accessible by the BootROM code. + +required: + - compatible + - reg + - reg-names + - interrupts + - interrupt-names + - clocks + - clock-names + - dmas + - dma-names + +unevaluatedProperties: false + +examples: + - | + nand-controller@8000c000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "fsl,imx28-gpmi-nand"; + reg = <0x8000c000 0x2000>, <0x8000a000 0x2000>; + reg-names = "gpmi-nand", "bch"; + interrupts = <41>; + interrupt-names = "bch"; + clocks = <&clks 50>; + clock-names = "gpmi_io"; + dmas = <&dma_apbh 4>; + dma-names = "rx-tx"; + }; diff --git a/Documentation/devicetree/bindings/mtd/mxc-nand.txt b/Documentation/devicetree/bindings/mtd/mxc-nand.txt deleted file mode 100644 index 2857c628fba4..000000000000 --- a/Documentation/devicetree/bindings/mtd/mxc-nand.txt +++ /dev/null @@ -1,19 +0,0 @@ -* Freescale's mxc_nand - -Required properties: -- compatible: "fsl,imxXX-nand" -- reg: address range of the nfc block -- interrupts: irq to be used -- nand-bus-width: see nand-controller.yaml -- nand-ecc-mode: see nand-controller.yaml -- nand-on-flash-bbt: see nand-controller.yaml - -Example: - - nand@d8000000 { - compatible = "fsl,imx27-nand"; - reg = <0xd8000000 0x1000>; - interrupts = <29>; - nand-bus-width = <8>; - nand-ecc-mode = "hw"; - }; diff --git a/Documentation/devicetree/bindings/mtd/mxc-nand.yaml b/Documentation/devicetree/bindings/mtd/mxc-nand.yaml new file mode 100644 index 000000000000..ee4d1d026fd8 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/mxc-nand.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/mxc-nand.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale's mxc_nand binding + +maintainers: + - Uwe Kleine-König <u.kleine-koenig@pengutronix.de> + +allOf: + - $ref: "nand-controller.yaml" + +properties: + compatible: + const: fsl,imx27-nand + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +unevaluatedProperties: false + +examples: + - | + nand-controller@d8000000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "fsl,imx27-nand"; + reg = <0xd8000000 0x1000>; + interrupts = <29>; + nand-bus-width = <8>; + nand-ecc-mode = "hw"; + }; diff --git a/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml b/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml index 64c20c92c07d..85fefe3a0444 100644 --- a/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml +++ b/Documentation/devicetree/bindings/net/amlogic,meson-dwmac.yaml @@ -22,6 +22,7 @@ select: - amlogic,meson8m2-dwmac - amlogic,meson-gxbb-dwmac - amlogic,meson-axg-dwmac + - amlogic,meson-g12a-dwmac required: - compatible @@ -36,6 +37,7 @@ allOf: - amlogic,meson8m2-dwmac - amlogic,meson-gxbb-dwmac - amlogic,meson-axg-dwmac + - amlogic,meson-g12a-dwmac then: properties: @@ -95,6 +97,7 @@ properties: - amlogic,meson8m2-dwmac - amlogic,meson-gxbb-dwmac - amlogic,meson-axg-dwmac + - amlogic,meson-g12a-dwmac contains: enum: - snps,dwmac-3.70a diff --git a/Documentation/devicetree/bindings/net/dsa/dsa.txt b/Documentation/devicetree/bindings/net/dsa/dsa.txt index f66bb7ecdb82..bf7328aba330 100644 --- a/Documentation/devicetree/bindings/net/dsa/dsa.txt +++ b/Documentation/devicetree/bindings/net/dsa/dsa.txt @@ -1,257 +1,4 @@ Distributed Switch Architecture Device Tree Bindings ---------------------------------------------------- -Switches are true Linux devices and can be probed by any means. Once -probed, they register to the DSA framework, passing a node -pointer. This node is expected to fulfil the following binding, and -may contain additional properties as required by the device it is -embedded within. - -Required properties: - -- ports : A container for child nodes representing switch ports. - -Optional properties: - -- dsa,member : A two element list indicates which DSA cluster, and position - within the cluster a switch takes. <0 0> is cluster 0, - switch 0. <0 1> is cluster 0, switch 1. <1 0> is cluster 1, - switch 0. A switch not part of any cluster (single device - hanging off a CPU port) must not specify this property - -The ports container has the following properties - -Required properties: - -- #address-cells : Must be 1 -- #size-cells : Must be 0 - -Each port children node must have the following mandatory properties: -- reg : Describes the port address in the switch - -An uplink/downlink port between switches in the cluster has the following -mandatory property: - -- link : Should be a list of phandles to other switch's DSA - port. This port is used as the outgoing port - towards the phandle ports. The full routing - information must be given, not just the one hop - routes to neighbouring switches. - -A CPU port has the following mandatory property: - -- ethernet : Should be a phandle to a valid Ethernet device node. - This host device is what the switch port is - connected to. - -A user port has the following optional property: - -- label : Describes the label associated with this port, which - will become the netdev name. - -Port child nodes may also contain the following optional standardised -properties, described in binding documents: - -- phy-handle : Phandle to a PHY on an MDIO bus. See - Documentation/devicetree/bindings/net/ethernet.txt - for details. - -- phy-mode : See - Documentation/devicetree/bindings/net/ethernet.txt - for details. - -- fixed-link : Fixed-link subnode describing a link to a non-MDIO - managed entity. See - Documentation/devicetree/bindings/net/fixed-link.txt - for details. - -The MAC address will be determined using the optional properties -defined in ethernet.txt. - -Example - -The following example shows three switches on three MDIO busses, -linked into one DSA cluster. - -&mdio1 { - #address-cells = <1>; - #size-cells = <0>; - - switch0: switch0@0 { - compatible = "marvell,mv88e6085"; - reg = <0>; - - dsa,member = <0 0>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - port@0 { - reg = <0>; - label = "lan0"; - }; - - port@1 { - reg = <1>; - label = "lan1"; - local-mac-address = [00 00 00 00 00 00]; - }; - - port@2 { - reg = <2>; - label = "lan2"; - }; - - switch0port5: port@5 { - reg = <5>; - phy-mode = "rgmii-txid"; - link = <&switch1port6 - &switch2port9>; - fixed-link { - speed = <1000>; - full-duplex; - }; - }; - - port@6 { - reg = <6>; - ethernet = <&fec1>; - fixed-link { - speed = <100>; - full-duplex; - }; - }; - }; - }; -}; - -&mdio2 { - #address-cells = <1>; - #size-cells = <0>; - - switch1: switch1@0 { - compatible = "marvell,mv88e6085"; - reg = <0>; - - dsa,member = <0 1>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - port@0 { - reg = <0>; - label = "lan3"; - phy-handle = <&switch1phy0>; - }; - - port@1 { - reg = <1>; - label = "lan4"; - phy-handle = <&switch1phy1>; - }; - - port@2 { - reg = <2>; - label = "lan5"; - phy-handle = <&switch1phy2>; - }; - - switch1port5: port@5 { - reg = <5>; - link = <&switch2port9>; - phy-mode = "rgmii-txid"; - fixed-link { - speed = <1000>; - full-duplex; - }; - }; - - switch1port6: port@6 { - reg = <6>; - phy-mode = "rgmii-txid"; - link = <&switch0port5>; - fixed-link { - speed = <1000>; - full-duplex; - }; - }; - }; - mdio-bus { - #address-cells = <1>; - #size-cells = <0>; - switch1phy0: switch1phy0@0 { - reg = <0>; - }; - switch1phy1: switch1phy0@1 { - reg = <1>; - }; - switch1phy2: switch1phy0@2 { - reg = <2>; - }; - }; - }; -}; - -&mdio4 { - #address-cells = <1>; - #size-cells = <0>; - - switch2: switch2@0 { - compatible = "marvell,mv88e6085"; - reg = <0>; - - dsa,member = <0 2>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - port@0 { - reg = <0>; - label = "lan6"; - }; - - port@1 { - reg = <1>; - label = "lan7"; - }; - - port@2 { - reg = <2>; - label = "lan8"; - }; - - port@3 { - reg = <3>; - label = "optical3"; - fixed-link { - speed = <1000>; - full-duplex; - link-gpios = <&gpio6 2 - GPIO_ACTIVE_HIGH>; - }; - }; - - port@4 { - reg = <4>; - label = "optical4"; - fixed-link { - speed = <1000>; - full-duplex; - link-gpios = <&gpio6 3 - GPIO_ACTIVE_HIGH>; - }; - }; - - switch2port9: port@9 { - reg = <9>; - phy-mode = "rgmii-txid"; - link = <&switch1port5 - &switch0port5>; - fixed-link { - speed = <1000>; - full-duplex; - }; - }; - }; - }; -}; +See Documentation/devicetree/bindings/net/dsa/dsa.yaml for the documenation. diff --git a/Documentation/devicetree/bindings/net/dsa/dsa.yaml b/Documentation/devicetree/bindings/net/dsa/dsa.yaml new file mode 100644 index 000000000000..faea214339ca --- /dev/null +++ b/Documentation/devicetree/bindings/net/dsa/dsa.yaml @@ -0,0 +1,92 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/dsa/dsa.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Ethernet Switch Device Tree Bindings + +maintainers: + - Andrew Lunn <andrew@lunn.ch> + - Florian Fainelli <f.fainelli@gmail.com> + - Vivien Didelot <vivien.didelot@gmail.com> + +description: + This binding represents Ethernet Switches which have a dedicated CPU + port. That port is usually connected to an Ethernet Controller of the + SoC. Such setups are typical for embedded devices. + +select: false + +properties: + $nodename: + pattern: "^switch(@.*)?$" + + dsa,member: + minItems: 2 + maxItems: 2 + description: + A two element list indicates which DSA cluster, and position within the + cluster a switch takes. <0 0> is cluster 0, switch 0. <0 1> is cluster 0, + switch 1. <1 0> is cluster 1, switch 0. A switch not part of any cluster + (single device hanging off a CPU port) must not specify this property + $ref: /schemas/types.yaml#/definitions/uint32-array + +patternProperties: + "^(ethernet-)?ports$": + type: object + properties: + '#address-cells': + const: 1 + '#size-cells': + const: 0 + + patternProperties: + "^(ethernet-)?port@[0-9]+$": + type: object + description: Ethernet switch ports + + properties: + reg: + description: Port number + + label: + description: + Describes the label associated with this port, which will become + the netdev name + $ref: /schemas/types.yaml#definitions/string + + link: + description: + Should be a list of phandles to other switch's DSA port. This + port is used as the outgoing port towards the phandle ports. The + full routing information must be given, not just the one hop + routes to neighbouring switches + $ref: /schemas/types.yaml#definitions/phandle-array + + ethernet: + description: + Should be a phandle to a valid Ethernet device node. This host + device is what the switch port is connected to + $ref: /schemas/types.yaml#definitions/phandle + + phy-handle: true + + phy-mode: true + + fixed-link: true + + mac-address: true + + required: + - reg + + additionalProperties: false + +oneOf: + - required: + - ports + - required: + - ethernet-ports + +... diff --git a/Documentation/devicetree/bindings/net/dsa/ocelot.txt b/Documentation/devicetree/bindings/net/dsa/ocelot.txt index 66a129fea705..7a271d070b72 100644 --- a/Documentation/devicetree/bindings/net/dsa/ocelot.txt +++ b/Documentation/devicetree/bindings/net/dsa/ocelot.txt @@ -4,10 +4,15 @@ Microchip Ocelot switch driver family Felix ----- -The VSC9959 core is currently the only switch supported by the driver, and is -found in the NXP LS1028A. It is a PCI device, part of the larger ENETC root -complex. As a result, the ethernet-switch node is a sub-node of the PCIe root -complex node and its "reg" property conforms to the parent node bindings: +Currently the switches supported by the felix driver are: + +- VSC9959 (Felix) +- VSC9953 (Seville) + +The VSC9959 switch is found in the NXP LS1028A. It is a PCI device, part of the +larger ENETC root complex. As a result, the ethernet-switch node is a sub-node +of the PCIe root complex node and its "reg" property conforms to the parent +node bindings: * reg: Specifies PCIe Device Number and Function Number of the endpoint device, in this case for the Ethernet L2Switch it is PF5 (of device 0, bus 0). @@ -114,3 +119,95 @@ Example: }; }; }; + +The VSC9953 switch is found inside NXP T1040. It is a platform device with the +following required properties: + +- compatible: + Must be "mscc,vsc9953-switch". + +Supported PHY interface types (appropriate SerDes protocol setting changes are +needed in the RCW binary): + +* phy_mode = "internal": on ports 8 and 9 +* phy_mode = "sgmii": on ports 0, 1, 2, 3, 4, 5, 6, 7 +* phy_mode = "qsgmii": on ports 0, 1, 2, 3, 4, 5, 6, 7 + +Example: + +&soc { + ethernet-switch@800000 { + #address-cells = <0x1>; + #size-cells = <0x0>; + compatible = "mscc,vsc9953-switch"; + little-endian; + reg = <0x800000 0x290000>; + + ports { + #address-cells = <0x1>; + #size-cells = <0x0>; + + port@0 { + reg = <0x0>; + label = "swp0"; + }; + + port@1 { + reg = <0x1>; + label = "swp1"; + }; + + port@2 { + reg = <0x2>; + label = "swp2"; + }; + + port@3 { + reg = <0x3>; + label = "swp3"; + }; + + port@4 { + reg = <0x4>; + label = "swp4"; + }; + + port@5 { + reg = <0x5>; + label = "swp5"; + }; + + port@6 { + reg = <0x6>; + label = "swp6"; + }; + + port@7 { + reg = <0x7>; + label = "swp7"; + }; + + port@8 { + reg = <0x8>; + phy-mode = "internal"; + ethernet = <&enet0>; + + fixed-link { + speed = <2500>; + full-duplex; + }; + }; + + port@9 { + reg = <0x9>; + phy-mode = "internal"; + status = "disabled"; + + fixed-link { + speed = <2500>; + full-duplex; + }; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/net/ethernet-phy.yaml b/Documentation/devicetree/bindings/net/ethernet-phy.yaml index 9b1f1147ca36..a9e547ac7905 100644 --- a/Documentation/devicetree/bindings/net/ethernet-phy.yaml +++ b/Documentation/devicetree/bindings/net/ethernet-phy.yaml @@ -162,6 +162,18 @@ properties: description: Specifies a reference to a node representing a SFP cage. + rx-internal-delay-ps: + description: | + RGMII Receive PHY Clock Delay defined in pico seconds. This is used for + PHY's that have configurable RX internal delays. If this property is + present then the PHY applies the RX delay. + + tx-internal-delay-ps: + description: | + RGMII Transmit PHY Clock Delay defined in pico seconds. This is used for + PHY's that have configurable TX internal delays. If this property is + present then the PHY applies the TX delay. + required: - reg diff --git a/Documentation/devicetree/bindings/net/mdio.yaml b/Documentation/devicetree/bindings/net/mdio.yaml index d6a3bf8550eb..26afb556dfae 100644 --- a/Documentation/devicetree/bindings/net/mdio.yaml +++ b/Documentation/devicetree/bindings/net/mdio.yaml @@ -39,6 +39,13 @@ properties: and must therefore be appropriately determined based on all devices requirements (maximum value of all per-device RESET pulse widths). + reset-post-delay-us: + description: + Delay after reset deassert in microseconds. It applies to all MDIO + devices and it's determined by how fast all devices are ready for + communication. This delay happens just before e.g. Ethernet PHY + type ID auto detection. + clock-frequency: description: Desired MDIO bus clock frequency in Hz. Values greater than IEEE 802.3 diff --git a/Documentation/devicetree/bindings/net/mediatek-bluetooth.txt b/Documentation/devicetree/bindings/net/mediatek-bluetooth.txt index 219bcbd0d344..9ef5bacda8c1 100644 --- a/Documentation/devicetree/bindings/net/mediatek-bluetooth.txt +++ b/Documentation/devicetree/bindings/net/mediatek-bluetooth.txt @@ -3,7 +3,7 @@ MediaTek SoC built-in Bluetooth Devices This device is a serial attached device to BTIF device and thus it must be a child node of the serial node with BTIF. The dt-bindings details for BTIF -device can be known via Documentation/devicetree/bindings/serial/8250.txt. +device can be known via Documentation/devicetree/bindings/serial/8250.yaml. Required properties: diff --git a/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt b/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt index 5ff37c68c941..87a27d775d48 100644 --- a/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt +++ b/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt @@ -31,6 +31,8 @@ Optional properties: VSC8531_LINK_100_ACTIVITY (2), VSC8531_LINK_ACTIVITY (0) and VSC8531_DUPLEX_COLLISION (8). +- load-save-gpios : GPIO used for the load/save operation of the PTP + hardware clock (PHC). Table: 1 - Edge rate change @@ -67,4 +69,5 @@ Example: vsc8531,edge-slowdown = <7>; vsc8531,led-0-mode = <LINK_1000_ACTIVITY>; vsc8531,led-1-mode = <LINK_100_ACTIVITY>; + load-save-gpios = <&gpio 10 GPIO_ACTIVE_HIGH>; }; diff --git a/Documentation/devicetree/bindings/net/realtek-bluetooth.yaml b/Documentation/devicetree/bindings/net/realtek-bluetooth.yaml index f15a5e5e4859..c488f24ed38f 100644 --- a/Documentation/devicetree/bindings/net/realtek-bluetooth.yaml +++ b/Documentation/devicetree/bindings/net/realtek-bluetooth.yaml @@ -44,7 +44,7 @@ examples: uart1 { pinctrl-names = "default"; pinctrl-0 = <&uart1_pins>, <&uart1_rts_cts_pins>; - uart-has-rtscts = <1>; + uart-has-rtscts; bluetooth { compatible = "realtek,rtl8723bs-bt"; diff --git a/Documentation/devicetree/bindings/net/ti,dp83867.yaml b/Documentation/devicetree/bindings/net/ti,dp83867.yaml index 554dcd7a40a9..c6716ac6cbcc 100644 --- a/Documentation/devicetree/bindings/net/ti,dp83867.yaml +++ b/Documentation/devicetree/bindings/net/ti,dp83867.yaml @@ -24,7 +24,7 @@ description: | IEEE 802.3 Standard Media Independent Interface (MII), the IEEE 802.3 Gigabit Media Independent Interface (GMII) or Reduced GMII (RGMII). - Specifications about the charger can be found at: + Specifications about the Ethernet PHY can be found at: https://www.ti.com/lit/gpn/dp83867ir properties: diff --git a/Documentation/devicetree/bindings/net/ti,dp83869.yaml b/Documentation/devicetree/bindings/net/ti,dp83869.yaml index 5b69ef03bbf7..cf40b469c719 100644 --- a/Documentation/devicetree/bindings/net/ti,dp83869.yaml +++ b/Documentation/devicetree/bindings/net/ti,dp83869.yaml @@ -8,7 +8,7 @@ $schema: "http://devicetree.org/meta-schemas/core.yaml#" title: TI DP83869 ethernet PHY allOf: - - $ref: "ethernet-controller.yaml#" + - $ref: "ethernet-phy.yaml#" maintainers: - Dan Murphy <dmurphy@ti.com> @@ -24,7 +24,7 @@ description: | conversions. The DP83869HM can also support Bridge Conversion from RGMII to SGMII and SGMII to RGMII. - Specifications about the charger can be found at: + Specifications about the Ethernet PHY can be found at: http://www.ti.com/lit/ds/symlink/dp83869hm.pdf properties: @@ -64,6 +64,18 @@ properties: Operational mode for the PHY. If this is not set then the operational mode is set by the straps. see dt-bindings/net/ti-dp83869.h for values + rx-internal-delay-ps: + description: Delay is in pico seconds + enum: [ 250, 500, 750, 1000, 1250, 1500, 1750, 2000, 2250, 2500, 2750, 3000, + 3250, 3500, 3750, 4000 ] + default: 2000 + + tx-internal-delay-ps: + description: Delay is in pico seconds + enum: [ 250, 500, 750, 1000, 1250, 1500, 1750, 2000, 2250, 2500, 2750, 3000, + 3250, 3500, 3750, 4000 ] + default: 2000 + required: - reg @@ -80,5 +92,7 @@ examples: ti,op-mode = <DP83869_RGMII_COPPER_ETHERNET>; ti,max-output-impedance = "true"; ti,clk-output-sel = <DP83869_CLK_O_SEL_CHN_A_RCLK>; + rx-internal-delay-ps = <2000>; + tx-internal-delay-ps = <2000>; }; }; diff --git a/Documentation/devicetree/bindings/net/wireless/microchip,wilc1000.yaml b/Documentation/devicetree/bindings/net/wireless/microchip,wilc1000.yaml new file mode 100644 index 000000000000..2c320eb2a8c4 --- /dev/null +++ b/Documentation/devicetree/bindings/net/wireless/microchip,wilc1000.yaml @@ -0,0 +1,71 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/wireless/microchip,wilc1000.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip WILC wireless devicetree bindings + +maintainers: + - Adham Abozaeid <adham.abozaeid@microchip.com> + - Ajay Singh <ajay.kathat@microchip.com> + +description: + The wilc1000 chips can be connected via SPI or SDIO. This document + describes the binding to connect wilc devices. + +properties: + compatible: + const: microchip,wilc1000 + + spi-max-frequency: true + + interrupts: + maxItems: 1 + + clocks: + description: phandle to the clock connected on rtc clock line. + maxItems: 1 + + clock-names: + const: rtc + +required: + - compatible + - interrupts + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + wifi@0 { + compatible = "microchip,wilc1000"; + spi-max-frequency = <48000000>; + reg = <0>; + interrupt-parent = <&pioC>; + interrupts = <27 0>; + clocks = <&pck1>; + clock-names = "rtc"; + }; + }; + + - | + mmc { + #address-cells = <1>; + #size-cells = <0>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_mmc1_clk_cmd_dat0 &pinctrl_mmc1_dat1_3>; + non-removable; + vmmc-supply = <&vcc_mmc1_reg>; + vqmmc-supply = <&vcc_3v3_reg>; + bus-width = <4>; + wifi@0 { + compatible = "microchip,wilc1000"; + reg = <0>; + interrupt-parent = <&pioC>; + interrupts = <27 0>; + clocks = <&pck1>; + clock-names = "rtc"; + }; + }; diff --git a/Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml b/Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml index daf1321d76ad..6687ab720304 100644 --- a/Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml +++ b/Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml @@ -15,14 +15,17 @@ allOf: properties: compatible: - enum: - - allwinner,sun4i-a10-sid - - allwinner,sun7i-a20-sid - - allwinner,sun8i-a83t-sid - - allwinner,sun8i-h3-sid - - allwinner,sun50i-a64-sid - - allwinner,sun50i-h5-sid - - allwinner,sun50i-h6-sid + oneOf: + - const: allwinner,sun4i-a10-sid + - const: allwinner,sun7i-a20-sid + - const: allwinner,sun8i-a83t-sid + - const: allwinner,sun8i-h3-sid + - const: allwinner,sun50i-a64-sid + - items: + - const: allwinner,sun50i-a100-sid + - const: allwinner,sun50i-a64-sid + - const: allwinner,sun50i-h5-sid + - const: allwinner,sun50i-h6-sid reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml b/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml new file mode 100644 index 000000000000..d10a0cf91ba7 --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml @@ -0,0 +1,96 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/nvmem/qcom,qfprom.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies Inc, QFPROM Efuse bindings + +maintainers: + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +allOf: + - $ref: "nvmem.yaml#" + +properties: + compatible: + const: qcom,qfprom + + reg: + # If the QFPROM is read-only OS image then only the corrected region + # needs to be provided. If the QFPROM is writable then all 4 regions + # must be provided. + oneOf: + - items: + - description: The corrected region. + - items: + - description: The corrected region. + - description: The raw region. + - description: The config region. + - description: The security control region. + + # Clock must be provided if QFPROM is writable from the OS image. + clocks: + maxItems: 1 + clock-names: + const: core + + # Supply reference must be provided if QFPROM is writable from the OS image. + vcc-supply: + description: Our power supply. + + # Needed if any child nodes are present. + "#address-cells": + const: 1 + "#size-cells": + const: 1 + +required: + - compatible + - reg + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-sc7180.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + efuse@784000 { + compatible = "qcom,qfprom"; + reg = <0 0x00784000 0 0x8ff>, + <0 0x00780000 0 0x7a0>, + <0 0x00782000 0 0x100>, + <0 0x00786000 0 0x1fff>; + clocks = <&gcc GCC_SEC_CTRL_CLK_SRC>; + clock-names = "core"; + #address-cells = <1>; + #size-cells = <1>; + + vcc-supply = <&vreg_l11a_1p8>; + + hstx-trim-primary@25b { + reg = <0x25b 0x1>; + bits = <1 3>; + }; + }; + }; + + - | + soc { + #address-cells = <2>; + #size-cells = <2>; + + efuse@784000 { + compatible = "qcom,qfprom"; + reg = <0 0x00784000 0 0x8ff>; + #address-cells = <1>; + #size-cells = <1>; + + hstx-trim-primary@1eb { + reg = <0x1eb 0x1>; + bits = <1 4>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/nvmem/qfprom.txt b/Documentation/devicetree/bindings/nvmem/qfprom.txt deleted file mode 100644 index 26fe878d5c86..000000000000 --- a/Documentation/devicetree/bindings/nvmem/qfprom.txt +++ /dev/null @@ -1,35 +0,0 @@ -= Qualcomm QFPROM device tree bindings = - -This binding is intended to represent QFPROM which is found in most QCOM SOCs. - -Required properties: -- compatible: should be "qcom,qfprom" -- reg: Should contain registers location and length - -= Data cells = -Are child nodes of qfprom, bindings of which as described in -bindings/nvmem/nvmem.txt - -Example: - - qfprom: qfprom@700000 { - compatible = "qcom,qfprom"; - reg = <0x00700000 0x8000>; - ... - /* Data cells */ - tsens_calibration: calib@404 { - reg = <0x4404 0x10>; - }; - }; - - -= Data consumers = -Are device nodes which consume nvmem data cells. - -For example: - - tsens { - ... - nvmem-cells = <&tsens_calibration>; - nvmem-cell-names = "calibration"; - }; diff --git a/Documentation/devicetree/bindings/phy/brcm,bcm63xx-usbh-phy.yaml b/Documentation/devicetree/bindings/phy/brcm,bcm63xx-usbh-phy.yaml new file mode 100644 index 000000000000..9a2e779e6d38 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/brcm,bcm63xx-usbh-phy.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/phy/brcm,bcm63xx-usbh-phy.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: BCM63xx USBH PHY + +maintainers: + - Ãlvaro Fernández Rojas <noltari@gmail.com> + +properties: + compatible: + enum: + - brcm,bcm6318-usbh-phy + - brcm,bcm6328-usbh-phy + - brcm,bcm6358-usbh-phy + - brcm,bcm6362-usbh-phy + - brcm,bcm6368-usbh-phy + - brcm,bcm63268-usbh-phy + + reg: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 2 + + clock-names: + minItems: 1 + maxItems: 2 + items: + - const: usbh + - const: usb_ref + + resets: + maxItems: 1 + + "#phy-cells": + const: 1 + +additionalProperties: false + +required: + - compatible + - reg + - clocks + - clock-names + - resets + - "#phy-cells" + +if: + properties: + compatible: + enum: + - brcm,bcm6318-usbh-phy + - brcm,bcm6328-usbh-phy + - brcm,bcm6362-usbh-phy + - brcm,bcm63268-usbh-phy +then: + properties: + power-domains: + maxItems: 1 + required: + - power-domains +else: + properties: + power-domains: false + +examples: + - | + usbh: usb-phy@10001700 { + compatible = "brcm,bcm6368-usbh-phy"; + reg = <0x10001700 0x38>; + clocks = <&periph_clk 15>; + clock-names = "usbh"; + resets = <&periph_rst 12>; + #phy-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/phy/phy-armada38x-comphy.txt b/Documentation/devicetree/bindings/phy/phy-armada38x-comphy.txt index ad49e5c01334..8b5a7a28a35b 100644 --- a/Documentation/devicetree/bindings/phy/phy-armada38x-comphy.txt +++ b/Documentation/devicetree/bindings/phy/phy-armada38x-comphy.txt @@ -12,6 +12,13 @@ Required properties: - #address-cells: should be 1. - #size-cells: should be 0. +Optional properties: + +- reg-names: must be "comphy" as the first name, and "conf". +- reg: must contain the comphy register location and length as the first + pair, followed by an optional configuration register address and + length pair. + A sub-node is required for each comphy lane provided by the comphy. Required properties (child nodes): @@ -24,7 +31,8 @@ Example: comphy: phy@18300 { compatible = "marvell,armada-380-comphy"; - reg = <0x18300 0x100>; + reg-names = "comphy", "conf"; + reg = <0x18300 0x100>, <0x18460 4>; #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/phy/qcom,ipq806x-usb-phy-hs.yaml b/Documentation/devicetree/bindings/phy/qcom,ipq806x-usb-phy-hs.yaml new file mode 100644 index 000000000000..23887ebe08fd --- /dev/null +++ b/Documentation/devicetree/bindings/phy/qcom,ipq806x-usb-phy-hs.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/qcom,ipq806x-usb-phy-hs.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm ipq806x usb DWC3 HS PHY CONTROLLER + +maintainers: + - Ansuel Smith <ansuelsmth@gmail.com> + +description: + DWC3 PHY nodes are defined to describe on-chip Synopsis Physical layer + controllers used in ipq806x. Each DWC3 PHY controller should have its + own node. + +properties: + compatible: + const: qcom,ipq806x-usb-phy-hs + + "#phy-cells": + const: 0 + + reg: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 2 + + clock-names: + minItems: 1 + maxItems: 2 + items: + - const: ref + - const: xo + +required: + - compatible + - "#phy-cells" + - reg + - clocks + - clock-names + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-ipq806x.h> + + hs_phy_0: phy@110f8800 { + compatible = "qcom,ipq806x-usb-phy-hs"; + reg = <0x110f8800 0x30>; + clocks = <&gcc USB30_0_UTMI_CLK>; + clock-names = "ref"; + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/qcom,ipq806x-usb-phy-ss.yaml b/Documentation/devicetree/bindings/phy/qcom,ipq806x-usb-phy-ss.yaml new file mode 100644 index 000000000000..fa30c24b4405 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/qcom,ipq806x-usb-phy-ss.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/qcom,ipq806x-usb-phy-ss.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm ipq806x usb DWC3 SS PHY CONTROLLER + +maintainers: + - Ansuel Smith <ansuelsmth@gmail.com> + +description: + DWC3 PHY nodes are defined to describe on-chip Synopsis Physical layer + controllers used in ipq806x. Each DWC3 PHY controller should have its + own node. + +properties: + compatible: + const: qcom,ipq806x-usb-phy-ss + + "#phy-cells": + const: 0 + + reg: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 2 + + clock-names: + minItems: 1 + maxItems: 2 + items: + - const: ref + - const: xo + + qcom,rx-eq: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Override value for rx_eq. + default: 4 + maximum: 7 + + qcom,tx-deamp-3_5db: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Override value for transmit preemphasis. + default: 23 + maximum: 63 + + qcom,mpll: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Override value for mpll. + default: 0 + maximum: 7 + +required: + - compatible + - "#phy-cells" + - reg + - clocks + - clock-names + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-ipq806x.h> + + ss_phy_0: phy@110f8830 { + compatible = "qcom,ipq806x-usb-phy-ss"; + reg = <0x110f8830 0x30>; + clocks = <&gcc USB30_0_MASTER_CLK>; + clock-names = "ref"; + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml index f80f8896d527..e4cd4a1deae9 100644 --- a/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml @@ -18,6 +18,7 @@ properties: compatible: enum: - qcom,ipq8074-qmp-pcie-phy + - qcom,ipq8074-qmp-usb3-phy - qcom,msm8996-qmp-pcie-phy - qcom,msm8996-qmp-ufs-phy - qcom,msm8996-qmp-usb3-phy @@ -161,6 +162,7 @@ allOf: compatible: contains: enum: + - qcom,ipq8074-qmp-usb3-phy - qcom,msm8996-qmp-usb3-phy - qcom,msm8998-qmp-pcie-phy - qcom,msm8998-qmp-usb3-phy diff --git a/Documentation/devicetree/bindings/phy/qcom,qusb2-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,qusb2-phy.yaml index b5a6195de7ff..9ba62dcb1e5d 100644 --- a/Documentation/devicetree/bindings/phy/qcom,qusb2-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,qusb2-phy.yaml @@ -18,6 +18,7 @@ properties: oneOf: - items: - enum: + - qcom,ipq8074-qusb2-phy - qcom,msm8996-qusb2-phy - qcom,msm8998-qusb2-phy - items: diff --git a/Documentation/devicetree/bindings/phy/renesas,usb2-phy.yaml b/Documentation/devicetree/bindings/phy/renesas,usb2-phy.yaml index 440f09fddf93..829e8c7e467a 100644 --- a/Documentation/devicetree/bindings/phy/renesas,usb2-phy.yaml +++ b/Documentation/devicetree/bindings/phy/renesas,usb2-phy.yaml @@ -21,6 +21,7 @@ properties: - renesas,usb2-phy-r8a774a1 # RZ/G2M - renesas,usb2-phy-r8a774b1 # RZ/G2N - renesas,usb2-phy-r8a774c0 # RZ/G2E + - renesas,usb2-phy-r8a774e1 # RZ/G2H - renesas,usb2-phy-r8a7795 # R-Car H3 - renesas,usb2-phy-r8a7796 # R-Car M3-W - renesas,usb2-phy-r8a77961 # R-Car M3-W+ diff --git a/Documentation/devicetree/bindings/phy/renesas,usb3-phy.yaml b/Documentation/devicetree/bindings/phy/renesas,usb3-phy.yaml index 68cf9dd0390d..f3ef738a3ff6 100644 --- a/Documentation/devicetree/bindings/phy/renesas,usb3-phy.yaml +++ b/Documentation/devicetree/bindings/phy/renesas,usb3-phy.yaml @@ -15,6 +15,7 @@ properties: - enum: - renesas,r8a774a1-usb3-phy # RZ/G2M - renesas,r8a774b1-usb3-phy # RZ/G2N + - renesas,r8a774e1-usb3-phy # RZ/G2H - renesas,r8a7795-usb3-phy # R-Car H3 - renesas,r8a7796-usb3-phy # R-Car M3-W - renesas,r8a77961-usb3-phy # R-Car M3-W+ diff --git a/Documentation/devicetree/bindings/phy/samsung,ufs-phy.yaml b/Documentation/devicetree/bindings/phy/samsung,ufs-phy.yaml new file mode 100644 index 000000000000..636cc501b54f --- /dev/null +++ b/Documentation/devicetree/bindings/phy/samsung,ufs-phy.yaml @@ -0,0 +1,75 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/samsung,ufs-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung SoC series UFS PHY Device Tree Bindings + +maintainers: + - Alim Akhtar <alim.akhtar@samsung.com> + +properties: + "#phy-cells": + const: 0 + + compatible: + enum: + - samsung,exynos7-ufs-phy + + reg: + maxItems: 1 + + reg-names: + items: + - const: phy-pma + + clocks: + items: + - description: PLL reference clock + - description: symbol clock for input symbol ( rx0-ch0 symbol clock) + - description: symbol clock for input symbol ( rx1-ch1 symbol clock) + - description: symbol clock for output symbol ( tx0 symbol clock) + + clock-names: + items: + - const: ref_clk + - const: rx1_symbol_clk + - const: rx0_symbol_clk + - const: tx0_symbol_clk + + samsung,pmu-syscon: + $ref: '/schemas/types.yaml#/definitions/phandle' + description: phandle for PMU system controller interface, used to + control pmu registers bits for ufs m-phy + +required: + - "#phy-cells" + - compatible + - reg + - reg-names + - clocks + - clock-names + - samsung,pmu-syscon + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/exynos7-clk.h> + + ufs_phy: ufs-phy@15571800 { + compatible = "samsung,exynos7-ufs-phy"; + reg = <0x15571800 0x240>; + reg-names = "phy-pma"; + samsung,pmu-syscon = <&pmu_system_controller>; + #phy-cells = <0>; + clocks = <&clock_fsys1 SCLK_COMBO_PHY_EMBEDDED_26M>, + <&clock_fsys1 PHYCLK_UFS20_RX1_SYMBOL_USER>, + <&clock_fsys1 PHYCLK_UFS20_RX0_SYMBOL_USER>, + <&clock_fsys1 PHYCLK_UFS20_TX0_SYMBOL_USER>; + clock-names = "ref_clk", "rx1_symbol_clk", + "rx0_symbol_clk", "tx0_symbol_clk"; + + }; +... diff --git a/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3hs-phy.yaml b/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3hs-phy.yaml index f88d36207b87..c871d462c952 100644 --- a/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3hs-phy.yaml +++ b/Documentation/devicetree/bindings/phy/socionext,uniphier-usb3hs-phy.yaml @@ -31,12 +31,16 @@ properties: clocks: minItems: 1 - maxItems: 2 + maxItems: 3 clock-names: oneOf: - const: link # for PXs2 - - items: # for PXs3 + - items: # for PXs3 with phy-ext + - const: link + - const: phy + - const: phy-ext + - items: # for others - const: link - const: phy diff --git a/Documentation/devicetree/bindings/phy/ti,phy-gmii-sel.yaml b/Documentation/devicetree/bindings/phy/ti,phy-gmii-sel.yaml new file mode 100644 index 000000000000..bcec422d7734 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/ti,phy-gmii-sel.yaml @@ -0,0 +1,104 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2020 Texas Instruments Incorporated - http://www.ti.com/ +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/phy/ti,phy-gmii-sel.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: CPSW Port's Interface Mode Selection PHY Tree Bindings + +maintainers: + - Kishon Vijay Abraham I <kishon@ti.com> + +description: | + TI am335x/am437x/dra7(am5)/dm814x CPSW3G Ethernet Subsystem supports + two 10/100/1000 Ethernet ports with selectable G/MII, RMII, and RGMII interfaces. + The interface mode is selected by configuring the MII mode selection register(s) + (GMII_SEL) in the System Control Module chapter (SCM). GMII_SEL register(s) and + bit fields placement in SCM are different between SoCs while fields meaning + is the same. + +--------------+ + +-------------------------------+ |SCM | + | CPSW | | +---------+ | + | +--------------------------------+gmii_sel | | + | | | | +---------+ | + | +----v---+ +--------+ | +--------------+ + | |Port 1..<--+-->GMII/MII<-------> + | | | | | | | + | +--------+ | +--------+ | + | | | + | | +--------+ | + | | | RMII <-------> + | +--> | | + | | +--------+ | + | | | + | | +--------+ | + | | | RGMII <-------> + | +--> | | + | +--------+ | + +-------------------------------+ + + CPSW Port's Interface Mode Selection PHY describes MII interface mode between + CPSW Port and Ethernet PHY which depends on Eth PHY and board configuration. + | + CPSW Port's Interface Mode Selection PHY device should defined as child device + of SCM node (scm_conf) and can be attached to each CPSW port node using standard + PHY bindings. + +properties: + compatible: + enum: + - ti,am3352-phy-gmii-sel + - ti,dra7xx-phy-gmii-sel + - ti,am43xx-phy-gmii-sel + - ti,dm814-phy-gmii-sel + - ti,am654-phy-gmii-sel + + reg: + description: Address and length of the register set for the device + + '#phy-cells': true + +allOf: + - if: + properties: + compatible: + contains: + enum: + - ti,dra7xx-phy-gmii-sel + - ti,dm814-phy-gmii-sel + - ti,am654-phy-gmii-sel + then: + properties: + '#phy-cells': + const: 1 + description: CPSW port number (starting from 1) + - if: + properties: + compatible: + contains: + enum: + - ti,am3352-phy-gmii-sel + - ti,am43xx-phy-gmii-sel + then: + properties: + '#phy-cells': + const: 2 + description: | + - CPSW port number (starting from 1) + - RMII refclk mode + +required: + - compatible + - reg + - '#phy-cells' + +additionalProperties: false + +examples: + - | + phy_gmii_sel: phy-gmii-sel@650 { + compatible = "ti,am3352-phy-gmii-sel"; + reg = <0x650 0x4>; + #phy-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/phy/ti-phy-gmii-sel.txt b/Documentation/devicetree/bindings/phy/ti-phy-gmii-sel.txt deleted file mode 100644 index 83b78c1c0644..000000000000 --- a/Documentation/devicetree/bindings/phy/ti-phy-gmii-sel.txt +++ /dev/null @@ -1,69 +0,0 @@ -CPSW Port's Interface Mode Selection PHY Tree Bindings ------------------------------------------------ - -TI am335x/am437x/dra7(am5)/dm814x CPSW3G Ethernet Subsystem supports -two 10/100/1000 Ethernet ports with selectable G/MII, RMII, and RGMII interfaces. -The interface mode is selected by configuring the MII mode selection register(s) -(GMII_SEL) in the System Control Module chapter (SCM). GMII_SEL register(s) and -bit fields placement in SCM are different between SoCs while fields meaning -is the same. - +--------------+ - +-------------------------------+ |SCM | - | CPSW | | +---------+ | - | +--------------------------------+gmii_sel | | - | | | | +---------+ | - | +----v---+ +--------+ | +--------------+ - | |Port 1..<--+-->GMII/MII<-------> - | | | | | | | - | +--------+ | +--------+ | - | | | - | | +--------+ | - | | | RMII <-------> - | +--> | | - | | +--------+ | - | | | - | | +--------+ | - | | | RGMII <-------> - | +--> | | - | +--------+ | - +-------------------------------+ - -CPSW Port's Interface Mode Selection PHY describes MII interface mode between -CPSW Port and Ethernet PHY which depends on Eth PHY and board configuration. - -CPSW Port's Interface Mode Selection PHY device should defined as child device -of SCM node (scm_conf) and can be attached to each CPSW port node using standard -PHY bindings (See phy/phy-bindings.txt). - -Required properties: -- compatible : Should be "ti,am3352-phy-gmii-sel" for am335x platform - "ti,dra7xx-phy-gmii-sel" for dra7xx/am57xx platform - "ti,am43xx-phy-gmii-sel" for am43xx platform - "ti,dm814-phy-gmii-sel" for dm814x platform - "ti,am654-phy-gmii-sel" for AM654x/J721E platform -- reg : Address and length of the register set for the device -- #phy-cells : must be 2. - cell 1 - CPSW port number (starting from 1) - cell 2 - RMII refclk mode - -Examples: - phy_gmii_sel: phy-gmii-sel { - compatible = "ti,am3352-phy-gmii-sel"; - reg = <0x650 0x4>; - #phy-cells = <2>; - }; - - mac: ethernet@4a100000 { - compatible = "ti,am335x-cpsw","ti,cpsw"; - ... - - cpsw_emac0: slave@4a100200 { - ... - phys = <&phy_gmii_sel 1 1>; - }; - - cpsw_emac1: slave@4a100300 { - ... - phys = <&phy_gmii_sel 2 1>; - }; - }; diff --git a/Documentation/devicetree/bindings/phy/xlnx,zynqmp-psgtr.yaml b/Documentation/devicetree/bindings/phy/xlnx,zynqmp-psgtr.yaml new file mode 100644 index 000000000000..04d5654efb38 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/xlnx,zynqmp-psgtr.yaml @@ -0,0 +1,105 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/xlnx,zynqmp-psgtr.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx ZynqMP Gigabit Transceiver PHY Device Tree Bindings + +maintainers: + - Laurent Pinchart <laurent.pinchart@ideasonboard.com> + +description: | + This binding describes the Xilinx ZynqMP Gigabit Transceiver (GTR) PHY. The + GTR provides four lanes and is used by USB, SATA, PCIE, Display port and + Ethernet SGMII controllers. + +properties: + "#phy-cells": + const: 4 + description: | + The cells contain the following arguments. + + - description: The GTR lane + minimum: 0 + maximum: 3 + - description: The PHY type + enum: + - PHY_TYPE_DP + - PHY_TYPE_PCIE + - PHY_TYPE_SATA + - PHY_TYPE_SGMII + - PHY_TYPE_USB + - description: The PHY instance + minimum: 0 + maximum: 1 # for DP, SATA or USB + maximum: 3 # for PCIE or SGMII + - description: The reference clock number + minimum: 0 + maximum: 3 + + compatible: + enum: + - xlnx,zynqmp-psgtr-v1.1 + - xlnx,zynqmp-psgtr + + clocks: + minItems: 1 + maxItems: 4 + description: | + Clock for each PS_MGTREFCLK[0-3] reference clock input. Unconnected + inputs shall not have an entry. + + clock-names: + minItems: 1 + maxItems: 4 + items: + pattern: "^ref[0-3]$" + + reg: + items: + - description: SERDES registers block + - description: SIOU registers block + + reg-names: + items: + - const: serdes + - const: siou + + xlnx,tx-termination-fix: + description: | + Include this for fixing functional issue with the TX termination + resistance in GT, which can be out of spec for the XCZU9EG silicon + version. + type: boolean + +required: + - "#phy-cells" + - compatible + - reg + - reg-names + +if: + properties: + compatible: + const: xlnx,zynqmp-psgtr-v1.1 + +then: + properties: + xlnx,tx-termination-fix: false + +additionalProperties: false + +examples: + - | + phy: phy@fd400000 { + compatible = "xlnx,zynqmp-psgtr-v1.1"; + reg = <0xfd400000 0x40000>, + <0xfd3d0000 0x1000>; + reg-names = "serdes", "siou"; + clocks = <&refclks 3>, <&refclks 2>, <&refclks 0>; + clock-names = "ref1", "ref2", "ref3"; + #phy-cells = <4>; + }; + +... diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt index b68613188c19..1b8e8b4a6379 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt @@ -114,7 +114,7 @@ with values derived from the SoC user manual. [flags]> On other mach-shmobile platforms GPIO is handled by the gpio-rcar driver. -Please refer to Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt +Please refer to Documentation/devicetree/bindings/gpio/renesas,rcar-gpio.yaml for documentation of the GPIO device tree bindings on those platforms. diff --git a/Documentation/devicetree/bindings/power/mti,mips-cpc.txt b/Documentation/devicetree/bindings/power/mti,mips-cpc.txt deleted file mode 100644 index c6b82511ae8a..000000000000 --- a/Documentation/devicetree/bindings/power/mti,mips-cpc.txt +++ /dev/null @@ -1,8 +0,0 @@ -Binding for MIPS Cluster Power Controller (CPC). - -This binding allows a system to specify where the CPC registers are -located. - -Required properties: -compatible : Should be "mti,mips-cpc". -regs: Should describe the address & size of the CPC register region. diff --git a/Documentation/devicetree/bindings/power/mti,mips-cpc.yaml b/Documentation/devicetree/bindings/power/mti,mips-cpc.yaml new file mode 100644 index 000000000000..ccdeaece169e --- /dev/null +++ b/Documentation/devicetree/bindings/power/mti,mips-cpc.yaml @@ -0,0 +1,35 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/mti,mips-cpc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MIPS Cluster Power Controller + +description: | + Defines a location of the MIPS Cluster Power Controller registers. + +maintainers: + - Paul Burton <paulburton@kernel.org> + +properties: + compatible: + const: mti,mips-cpc + + reg: + description: | + Base address and size of an unoccupied memory region, which will be + used to map the MIPS CPC registers block. + maxItems: 1 + +required: + - compatible + - reg + +examples: + - | + cpc@1bde0000 { + compatible = "mti,mips-cpc"; + reg = <0x1bde0000 0x8000>; + }; +... diff --git a/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml b/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml index 55b6ab2d8784..ec2aaeee78dc 100644 --- a/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml +++ b/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml @@ -25,6 +25,7 @@ properties: - renesas,r8a774a1-sysc # RZ/G2M - renesas,r8a774b1-sysc # RZ/G2N - renesas,r8a774c0-sysc # RZ/G2E + - renesas,r8a774e1-sysc # RZ/G2H - renesas,r8a7779-sysc # R-Car H1 - renesas,r8a7790-sysc # R-Car H2 - renesas,r8a7791-sysc # R-Car M2-W diff --git a/Documentation/devicetree/bindings/property-units.txt b/Documentation/devicetree/bindings/property-units.txt index c80a110c1e26..218f99fa311f 100644 --- a/Documentation/devicetree/bindings/property-units.txt +++ b/Documentation/devicetree/bindings/property-units.txt @@ -17,6 +17,7 @@ Time/Frequency -ms : millisecond -us : microsecond -ns : nanosecond +-ps : picosecond Distance ---------------------------------------- diff --git a/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml b/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml index fc799b0577d4..188679cb8b8c 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml +++ b/Documentation/devicetree/bindings/pwm/pwm-samsung.yaml @@ -18,9 +18,6 @@ description: |+ Be aware that the clocksource driver supports only uniprocessor systems. -allOf: - - $ref: pwm.yaml# - properties: compatible: enum: @@ -63,7 +60,8 @@ properties: interrupts: description: - One interrupt per timer, starting at timer 0. + One interrupt per timer, starting at timer 0. Necessary only for SoCs which + use PWM clocksource. minItems: 1 maxItems: 5 @@ -88,12 +86,27 @@ required: - clocks - clock-names - compatible - - interrupts - "#pwm-cells" - reg additionalProperties: false +allOf: + - $ref: pwm.yaml# + + - if: + properties: + compatible: + contains: + enum: + - samsung,s3c2410-pwm + - samsung,s3c6400-pwm + - samsung,s5p6440-pwm + - samsung,s5pc100-pwm + then: + required: + - interrupts + examples: - | pwm@7f006000 { diff --git a/Documentation/devicetree/bindings/regulator/da9211.txt b/Documentation/devicetree/bindings/regulator/da9211.txt index 27717e816e71..eb871447d508 100644 --- a/Documentation/devicetree/bindings/regulator/da9211.txt +++ b/Documentation/devicetree/bindings/regulator/da9211.txt @@ -15,6 +15,8 @@ Required properties: Optional properties: - enable-gpios: platform gpio for control of BUCKA/BUCKB. - Any optional property defined in regulator.txt + - regulator-initial-mode and regulator-allowed-modes may be specified using + mode values from dt-bindings/regulator/dlg,da9211-regulator.h Example 1) DA9211 pmic: da9211@68 { @@ -30,6 +32,8 @@ Example 1) DA9211 regulator-min-microamp = <2000000>; regulator-max-microamp = <5000000>; enable-gpios = <&gpio 27 0>; + regulator-allowed-modes = <DA9211_BUCK_MODE_SYNC + DA9211_BUCK_MODE_AUTO>; }; }; }; diff --git a/Documentation/devicetree/bindings/regulator/google,cros-ec-regulator.yaml b/Documentation/devicetree/bindings/regulator/google,cros-ec-regulator.yaml new file mode 100644 index 000000000000..c9453d7ce227 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/google,cros-ec-regulator.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/google,cros-ec-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ChromeOS EC controlled voltage regulators + +maintainers: + - Pi-Hsun Shih <pihsun@chromium.org> + +description: + Any property defined as part of the core regulator binding, defined in + regulator.yaml, can also be used. + +allOf: + - $ref: "regulator.yaml#" + +properties: + compatible: + const: google,cros-ec-regulator + + reg: + maxItems: 1 + description: Identifier for the voltage regulator to ChromeOS EC. + +required: + - compatible + - reg + +examples: + - | + spi0 { + #address-cells = <1>; + #size-cells = <0>; + + cros_ec: ec@0 { + compatible = "google,cros-ec-spi"; + reg = <0>; + #address-cells = <1>; + #size-cells = <0>; + + regulator@0 { + compatible = "google,cros-ec-regulator"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3300000>; + reg = <0>; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/lp872x.txt b/Documentation/devicetree/bindings/regulator/lp872x.txt index ca58a68ffdf1..ab895cd1cac1 100644 --- a/Documentation/devicetree/bindings/regulator/lp872x.txt +++ b/Documentation/devicetree/bindings/regulator/lp872x.txt @@ -37,8 +37,8 @@ Optional properties: (Documentation/devicetree/bindings/regulator/regulator.txt) Datasheet - - LP8720: http://www.ti.com/lit/ds/symlink/lp8720.pdf - - LP8725: http://www.ti.com/lit/ds/symlink/lp8725.pdf + - LP8720: https://www.ti.com/lit/ds/symlink/lp8720.pdf + - LP8725: https://www.ti.com/lit/ds/symlink/lp8725.pdf Example 1) LP8720 diff --git a/Documentation/devicetree/bindings/regulator/mt6397-regulator.txt b/Documentation/devicetree/bindings/regulator/mt6397-regulator.txt index 01141fb00875..c080086d3e62 100644 --- a/Documentation/devicetree/bindings/regulator/mt6397-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/mt6397-regulator.txt @@ -16,6 +16,9 @@ LDO: ldo_vemc3v3, ldo_vgp1, ldo_vgp2, ldo_vgp3, ldo_vgp4, ldo_vgp5, ldo_vgp6, ldo_vibr +BUCK regulators can set regulator-initial-mode and regulator-allowed-modes to +values specified in dt-bindings/regulator/mediatek,mt6397-regulator.h + Example: pmic { compatible = "mediatek,mt6397"; diff --git a/Documentation/devicetree/bindings/regulator/nxp,pca9450-regulator.yaml b/Documentation/devicetree/bindings/regulator/nxp,pca9450-regulator.yaml new file mode 100644 index 000000000000..c2b0a8b6da1e --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/nxp,pca9450-regulator.yaml @@ -0,0 +1,190 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/nxp,pca9450-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP PCA9450A/B/C Power Management Integrated Circuit regulators + +maintainers: + - Robin Gong <yibin.gong@nxp.com> + +description: | + Regulator nodes should be named to BUCK_<number> and LDO_<number>. The + definition for each of these nodes is defined using the standard + binding for regulators at + Documentation/devicetree/bindings/regulator/regulator.txt. + Datasheet is available at + https://www.nxp.com/docs/en/data-sheet/PCA9450DS.pdf + +#The valid names for PCA9450 regulator nodes are: +#BUCK1, BUCK2, BUCK3, BUCK4, BUCK5, BUCK6, +#LDO1, LDO2, LDO3, LDO4, LDO5 +#Note: Buck3 removed on PCA9450B and connect with Buck1 on PCA9450C. + +properties: + compatible: + enum: + - nxp,pca9450a + - nxp,pca9450b + - nxp,pca9450c + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + regulators: + type: object + description: | + list of regulators provided by this controller + + patternProperties: + "^LDO[1-5]$": + type: object + $ref: regulator.yaml# + description: + Properties for single LDO regulator. + + properties: + regulator-name: + pattern: "^LDO[1-5]$" + description: + should be "LDO1", ..., "LDO5" + + unevaluatedProperties: false + + "^BUCK[1-6]$": + type: object + $ref: regulator.yaml# + description: + Properties for single BUCK regulator. + + properties: + regulator-name: + pattern: "^BUCK[1-6]$" + description: + should be "BUCK1", ..., "BUCK6" + + nxp,dvs-run-voltage: + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 600000 + maximum: 2187500 + description: + PMIC default "RUN" state voltage in uV. Only Buck1~3 have such + dvs(dynamic voltage scaling) property. + + nxp,dvs-standby-voltage: + $ref: "/schemas/types.yaml#/definitions/uint32" + minimum: 600000 + maximum: 2187500 + description: + PMIC default "STANDBY" state voltage in uV. Only Buck1~3 have such + dvs(dynamic voltage scaling) property. + + unevaluatedProperties: false + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - regulators + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + pmic: pmic@25 { + compatible = "nxp,pca9450b"; + reg = <0x25>; + pinctrl-0 = <&pinctrl_pmic>; + interrupt-parent = <&gpio1>; + interrupts = <3 IRQ_TYPE_LEVEL_LOW>; + + regulators { + buck1: BUCK1 { + regulator-name = "BUCK1"; + regulator-min-microvolt = <600000>; + regulator-max-microvolt = <2187500>; + regulator-boot-on; + regulator-always-on; + regulator-ramp-delay = <3125>; + }; + buck2: BUCK2 { + regulator-name = "BUCK2"; + regulator-min-microvolt = <600000>; + regulator-max-microvolt = <2187500>; + regulator-boot-on; + regulator-always-on; + regulator-ramp-delay = <3125>; + nxp,dvs-run-voltage = <950000>; + nxp,dvs-standby-voltage = <850000>; + }; + buck4: BUCK4 { + regulator-name = "BUCK4"; + regulator-min-microvolt = <600000>; + regulator-max-microvolt = <3400000>; + regulator-boot-on; + regulator-always-on; + }; + buck5: BUCK5 { + regulator-name = "BUCK5"; + regulator-min-microvolt = <600000>; + regulator-max-microvolt = <3400000>; + regulator-boot-on; + regulator-always-on; + }; + buck6: BUCK6 { + regulator-name = "BUCK6"; + regulator-min-microvolt = <600000>; + regulator-max-microvolt = <3400000>; + regulator-boot-on; + regulator-always-on; + }; + + ldo1: LDO1 { + regulator-name = "LDO1"; + regulator-min-microvolt = <1600000>; + regulator-max-microvolt = <3300000>; + regulator-boot-on; + regulator-always-on; + }; + ldo2: LDO2 { + regulator-name = "LDO2"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <1150000>; + regulator-boot-on; + regulator-always-on; + }; + ldo3: LDO3 { + regulator-name = "LDO3"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <3300000>; + regulator-boot-on; + regulator-always-on; + }; + ldo4: LDO4 { + regulator-name = "LDO4"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <3300000>; + regulator-boot-on; + regulator-always-on; + }; + ldo5: LDO5 { + regulator-name = "LDO5"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3300000>; + regulator-boot-on; + regulator-always-on; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/onnn,fan53880.yaml b/Documentation/devicetree/bindings/regulator/onnn,fan53880.yaml new file mode 100644 index 000000000000..eb61e04ef852 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/onnn,fan53880.yaml @@ -0,0 +1,85 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/onnn,fan53880.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Onsemi FAN53880 PMIC + +maintainers: + - Christoph Fritz <chf.fritz@googlemail.com> + +description: | + The FAN53880 is an I2C porgrammable power management IC (PMIC) + that contains a BUCK (step-down converter), four low dropouts (LDO) + and one BOOST (step-up converter) output. It is designed for mobile + power applications. + +properties: + $nodename: + pattern: "pmic@[0-9a-f]{1,2}" + compatible: + enum: + - onnn,fan53880 + + reg: + maxItems: 1 + + VIN12-supply: + description: Input supply phandle(s) for LDO1 and LDO2 + + VIN3-supply: + description: Input supply phandle(s) for LDO3 + + VIN4-supply: + description: Input supply phandle(s) for LDO4 + + PVIN-supply: + description: Input supply phandle(s) for BUCK and BOOST + + regulators: + type: object + $ref: regulator.yaml# + description: | + list of regulators provided by this controller, must be named + after their hardware counterparts LDO[1-4], BUCK and BOOST + + patternProperties: + "^LDO[1-4]$": + type: object + $ref: regulator.yaml# + + "^BUCK|BOOST$": + type: object + $ref: regulator.yaml# + + additionalProperties: false + +required: + - compatible + - reg + - regulators + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@35 { + compatible = "onnn,fan53880"; + reg = <0x35>; + + PVIN-supply = <&fixreg_example_vcc>; + + regulators { + BUCK { + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt deleted file mode 100644 index dea4384f4c03..000000000000 --- a/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt +++ /dev/null @@ -1,320 +0,0 @@ -QCOM SMD RPM REGULATOR - -The Qualcomm RPM over SMD regulator is modelled as a subdevice of the RPM. -Because SMD is used as the communication transport mechanism, the RPM resides as -a subnode of the SMD. As such, the SMD-RPM regulator requires that the SMD and -RPM nodes be present. - -Please refer to Documentation/devicetree/bindings/soc/qcom/qcom,smd.txt for -information pertaining to the SMD node. - -Please refer to Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.txt for -information regarding the RPM node. - -== Regulator - -Regulator nodes are identified by their compatible: - -- compatible: - Usage: required - Value type: <string> - Definition: must be one of: - "qcom,rpm-pm8841-regulators" - "qcom,rpm-pm8916-regulators" - "qcom,rpm-pm8941-regulators" - "qcom,rpm-pm8950-regulators" - "qcom,rpm-pm8994-regulators" - "qcom,rpm-pm8998-regulators" - "qcom,rpm-pma8084-regulators" - "qcom,rpm-pmi8994-regulators" - "qcom,rpm-pmi8998-regulators" - "qcom,rpm-pms405-regulators" - -- vdd_s1-supply: -- vdd_s2-supply: -- vdd_s3-supply: -- vdd_s4-supply: -- vdd_s5-supply: -- vdd_s6-supply: -- vdd_s7-supply: -- vdd_s8-supply: - Usage: optional (pm8841 only) - Value type: <phandle> - Definition: reference to regulator supplying the input pin, as - described in the data sheet - -- vdd_s1-supply: -- vdd_s2-supply: -- vdd_s3-supply: -- vdd_s4-supply: -- vdd_l1_l2_l3-supply: -- vdd_l4_l5_l6-supply: -- vdd_l7-supply: -- vdd_l8_l9_l10_l11_l12_l13_l14_l15_l16_l17_l18-supply: - Usage: optional (pm8916 only) - Value type: <phandle> - Definition: reference to regulator supplying the input pin, as - described in the data sheet - -- vdd_s1-supply: -- vdd_s2-supply: -- vdd_s3-supply: -- vdd_s4-supply: -- vdd_s4-supply: -- vdd_s5-supply: -- vdd_s6-supply: -- vdd_l1_l19-supply: -- vdd_l2_l23-supply: -- vdd_l3-supply: -- vdd_l4_l5_l6_l7_l16-supply: -- vdd_l8_l11_l12_l17_l22-supply: -- vdd_l9_l10_l13_l14_l15_l18-supply: -- vdd_l20-supply: -- vdd_l21-supply: - Usage: optional (pm8950 only) - Value type: <phandle> - Definition: reference to regulator supplying the input pin, as - described in the data sheet - -- vdd_s1-supply: -- vdd_s2-supply: -- vdd_s3-supply: -- vdd_l1_l3-supply: -- vdd_l2_lvs1_2_3-supply: -- vdd_l4_l11-supply: -- vdd_l5_l7-supply: -- vdd_l6_l12_l14_l15-supply: -- vdd_l8_l16_l18_l19-supply: -- vdd_l9_l10_l17_l22-supply: -- vdd_l13_l20_l23_l24-supply: -- vdd_l21-supply: -- vin_5vs-supply: - Usage: optional (pm8941 only) - Value type: <phandle> - Definition: reference to regulator supplying the input pin, as - described in the data sheet - -- vdd_s1-supply: -- vdd_s2-supply: -- vdd_s3-supply: -- vdd_s4-supply: -- vdd_s5-supply: -- vdd_s6-supply: -- vdd_s7-supply: -- vdd_s8-supply: -- vdd_s9-supply: -- vdd_s10-supply: -- vdd_s11-supply: -- vdd_s12-supply: -- vdd_l1-supply: -- vdd_l2_l26_l28-supply: -- vdd_l3_l11-supply: -- vdd_l4_l27_l31-supply: -- vdd_l5_l7-supply: -- vdd_l6_l12_l32-supply: -- vdd_l5_l7-supply: -- vdd_l8_l16_l30-supply: -- vdd_l9_l10_l18_l22-supply: -- vdd_l9_l10_l18_l22-supply: -- vdd_l3_l11-supply: -- vdd_l6_l12_l32-supply: -- vdd_l13_l19_l23_l24-supply: -- vdd_l14_l15-supply: -- vdd_l14_l15-supply: -- vdd_l8_l16_l30-supply: -- vdd_l17_l29-supply: -- vdd_l9_l10_l18_l22-supply: -- vdd_l13_l19_l23_l24-supply: -- vdd_l20_l21-supply: -- vdd_l20_l21-supply: -- vdd_l9_l10_l18_l22-supply: -- vdd_l13_l19_l23_l24-supply: -- vdd_l13_l19_l23_l24-supply: -- vdd_l25-supply: -- vdd_l2_l26_l28-supply: -- vdd_l4_l27_l31-supply: -- vdd_l2_l26_l28-supply: -- vdd_l17_l29-supply: -- vdd_l8_l16_l30-supply: -- vdd_l4_l27_l31-supply: -- vdd_l6_l12_l32-supply: -- vdd_lvs1_2-supply: - Usage: optional (pm8994 only) - Value type: <phandle> - Definition: reference to regulator supplying the input pin, as - described in the data sheet - -- vdd_s1-supply: -- vdd_s2-supply: -- vdd_s3-supply: -- vdd_bst_byp-supply: - Usage: optional (pmi8994 only) - Value type: <phandle> - Definition: reference to regulator supplying the input pin, as - described in the data sheet - -- vdd_s1-supply: -- vdd_s2-supply: -- vdd_s3-supply: -- vdd_s4-supply: -- vdd_s5-supply: -- vdd_s6-supply: -- vdd_s7-supply: -- vdd_s8-supply: -- vdd_s9-supply: -- vdd_s10-supply: -- vdd_s11-supply: -- vdd_s12-supply: -- vdd_s13-supply: -- vdd_l1_l27-supply: -- vdd_l20_l24-supply: -- vdd_l26-supply: -- vdd_l2_l8_l17-supply: -- vdd_l3_l11-supply: -- vdd_l4_l5-supply: -- vdd_l6-supply: -- vdd_l7_l12_l14_l15-supply: -- vdd_l9-supply: -- vdd_l10_l23_l25-supply: -- vdd_l13_l19_l21-supply: -- vdd_l16_l28-supply: -- vdd_l18_l22-supply: -- vdd_lvs1_lvs2-supply: - Usage: optional (pmi8998 only) - Value type: <phandle> - Definition: reference to regulator supplying the input pin, as - described in the data sheet - -- vdd_s1-supply: -- vdd_s2-supply: -- vdd_s3-supply: -- vdd_s4-supply: -- vdd_s5-supply: -- vdd_s6-supply: -- vdd_s7-supply: -- vdd_s8-supply: -- vdd_s9-supply: -- vdd_s10-supply: -- vdd_s11-supply: -- vdd_s12-supply: -- vdd_l1_l11-supply: -- vdd_l2_l3_l4_l27-supply: -- vdd_l5_l7-supply: -- vdd_l6_l12_l14_l15_l26-supply: -- vdd_l8-supply: -- vdd_l9_l10_l13_l20_l23_l24-supply: -- vdd_l16_l25-supply: -- vdd_l17-supply: -- vdd_l18-supply: -- vdd_l19-supply: -- vdd_l21-supply: -- vdd_l22-supply: - Usage: optional (pma8084 only) - Value type: <phandle> - Definition: reference to regulator supplying the input pin, as - described in the data sheet - -- vdd_bob-supply: - Usage: optional (pmi8998 only) - Value type: <phandle> - Definition: reference to regulator supplying the input pin, as - described in the data sheet - -- vdd_s1-supply: -- vdd_s2-supply: -- vdd_s3-supply: -- vdd_s4-supply: -- vdd_s5-supply: -- vdd_l1_l2-supply: -- vdd_l3_l8-supply: -- vdd_l4-supply: -- vdd_l5_l6-supply: -- vdd_l7-supply: -- vdd_l3_l8-supply: -- vdd_l9-supply: -- vdd_l10_l11_l12_l13-supply: - Usage: optional (pms405 only) - Value type: <phandle> - Definition: reference to regulator supplying the input pin, as - described in the data sheet - -The regulator node houses sub-nodes for each regulator within the device. Each -sub-node is identified using the node's name, with valid values listed for each -of the pmics below. - -pm8841: - s1, s2, s3, s4, s5, s6, s7, s8 - -pm8916: - s1, s2, s3, s4, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, - l14, l15, l16, l17, l18 - -pm8941: - s1, s2, s3, s4, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, - l14, l15, l16, l17, l18, l19, l20, l21, l22, l23, l24, lvs1, lvs2, - lvs3, 5vs1, 5vs2 - -pm8994: - s1, s2, s3, s4, s5, s6, s7, s8, s9, s10, s11, s12, l1, l2, l3, l4, l5, - l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19, l20, - l21, l22, l23, l24, l25, l26, l27, l28, l29, l30, l31, l32, lvs1, lvs2 - -pm8998: - s1, s2, s3, s4, s5, s6, s7, s8, s9, s10, s11, s12, s13, l1, l2, l3, l4, - l5, l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19, - l20, l21, l22, l23, l24, l25, l26, l27, l28, lvs1, lvs2 - -pma8084: - s1, s2, s3, s4, s5, s6, s7, s8, s9, s10, s11, s12, l1, l2, l3, l4, l5, - l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19, l20, - l21, l22, l23, l24, l25, l26, l27, lvs1, lvs2, lvs3, lvs4, 5vs1 - -pmi8994: - s1, s2, s3, boost-bypass - -pmi8998: - bob - -pms405: - s1, s2, s3, s4, s5, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, - l13 - -The content of each sub-node is defined by the standard binding for regulators - -see regulator.txt. - -= EXAMPLE - - smd { - compatible = "qcom,smd"; - - rpm { - interrupts = <0 168 1>; - qcom,ipc = <&apcs 8 0>; - qcom,smd-edge = <15>; - - rpm_requests { - compatible = "qcom,rpm-msm8974"; - qcom,smd-channels = "rpm_requests"; - - pm8941-regulators { - compatible = "qcom,rpm-pm8941-regulators"; - vdd_l13_l20_l23_l24-supply = <&pm8941_boost>; - - pm8941_s3: s3 { - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - }; - - pm8941_boost: s4 { - regulator-min-microvolt = <5000000>; - regulator-max-microvolt = <5000000>; - }; - - pm8941_l20: l20 { - regulator-min-microvolt = <2950000>; - regulator-max-microvolt = <2950000>; - }; - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml new file mode 100644 index 000000000000..d2022206081f --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.yaml @@ -0,0 +1,108 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/qcom,smd-rpm-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: QCOM SMD RPM REGULATOR + +description: + The Qualcomm RPM over SMD regulator is modelled as a subdevice of the RPM. + Because SMD is used as the communication transport mechanism, the RPM + resides as a subnode of the SMD. As such, the SMD-RPM regulator requires + that the SMD and RPM nodes be present. + + Please refer to Documentation/devicetree/bindings/soc/qcom/qcom,smd.txt for + information pertaining to the SMD node. + + Please refer to Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml + for information regarding the RPM node. + + The regulator node houses sub-nodes for each regulator within the device. + Each sub-node is identified using the node's name, with valid values listed + for each of the pmics below. + + For mp5496, s2 + + For pm8841, s1, s2, s3, s4, s5, s6, s7, s8 + + For pm8916, s1, s2, s3, s4, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, + l12, l13, l14, l15, l16, l17, l18 + + For pm8941, s1, s2, s3, s4, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, + l12, l13, l14, l15, l16, l17, l18, l19, l20, l21, l22, l23, l24, lvs1, lvs2, + lvs3, 5vs1, 5vs2 + + For pm8994, s1, s2, s3, s4, s5, s6, s7, s8, s9, s10, s11, s12, l1, l2, l3, + l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19, + l20, l21, l22, l23, l24, l25, l26, l27, l28, l29, l30, l31, l32, lvs1, lvs2 + + For pm8998, s1, s2, s3, s4, s5, s6, s7, s8, s9, s10, s11, s12, s13, l1, l2, + l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19, + l20, l21, l22, l23, l24, l25, l26, l27, l28, lvs1, lvs2 + + For pma8084, s1, s2, s3, s4, s5, s6, s7, s8, s9, s10, s11, s12, l1, l2, l3, + l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19, + l20, l21, l22, l23, l24, l25, l26, l27, lvs1, lvs2, lvs3, lvs4, 5vs1 + + For pmi8994, s1, s2, s3, boost-bypass + + For pmi8998, bob + + For pms405, s1, s2, s3, s4, s5, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, + l12, l13 + +maintainers: + - Kathiravan T <kathirav@codeaurora.org> + +properties: + compatible: + enum: + - qcom,rpm-mp5496-regulators + - qcom,rpm-pm8841-regulators + - qcom,rpm-pm8916-regulators + - qcom,rpm-pm8941-regulators + - qcom,rpm-pm8950-regulators + - qcom,rpm-pm8994-regulators + - qcom,rpm-pm8998-regulators + - qcom,rpm-pma8084-regulators + - qcom,rpm-pmi8994-regulators + - qcom,rpm-pmi8998-regulators + - qcom,rpm-pms405-regulators + +patternProperties: + ".*-supply$": + description: Input supply phandle(s) for this node + + "^((s|l|lvs|5vs)[0-9]*)|(boost-bypass)|(bob)$": + description: List of regulators and its properties + allOf: + - $ref: regulator.yaml# + +additionalProperties: false + +required: + - compatible + +examples: + - | + pm8941-regulators { + compatible = "qcom,rpm-pm8941-regulators"; + vdd_l13_l20_l23_l24-supply = <&pm8941_boost>; + + pm8941_s3: s3 { + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + }; + + pm8941_boost: s4 { + regulator-min-microvolt = <5000000>; + regulator-max-microvolt = <5000000>; + }; + + pm8941_l20: l20 { + regulator-min-microvolt = <2950000>; + regulator-max-microvolt = <2950000>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml new file mode 100644 index 000000000000..12ed98c28aaa --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml @@ -0,0 +1,41 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/qcom,usb-vbus-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: The Qualcomm PMIC VBUS output regulator driver + +maintainers: + - Wesley Cheng <wcheng@codeaurora.org> + +description: | + This regulator driver controls the VBUS output by the Qualcomm PMIC. This + regulator will be enabled in situations where the device is required to + provide power to the connected peripheral. + +properties: + compatible: + enum: + - qcom,pm8150b-vbus-reg + + reg: + maxItems: 1 + description: VBUS output base address + +required: + - compatible + +additionalProperties: false + +examples: + - | + pm8150b { + #address-cells = <1>; + #size-cells = <0>; + pm8150b_vbus: dcdc@1100 { + compatible = "qcom,pm8150b-vbus-reg"; + reg = <0x1100>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml new file mode 100644 index 000000000000..085cbd1ad8d0 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/qcom-labibb-regulator.yaml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/qcom-labibb-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm's LAB(LCD AMOLED Boost)/IBB(Inverting Buck Boost) Regulator + +maintainers: + - Sumit Semwal <sumit.semwal@linaro.org> + +description: + LAB can be used as a positive boost power supply and IBB can be used as a + negative boost power supply for display panels. Currently implemented for + pmi8998. + +properties: + compatible: + const: qcom,pmi8998-lab-ibb + + lab: + type: object + + properties: + + interrupts: + maxItems: 1 + description: + Short-circuit interrupt for lab. + + required: + - interrupts + + ibb: + type: object + + properties: + + interrupts: + maxItems: 1 + description: + Short-circuit interrupt for lab. + + required: + - interrupts + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + labibb { + compatible = "qcom,pmi8998-lab-ibb"; + + lab { + interrupts = <0x3 0x0 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "sc-err"; + }; + + ibb { + interrupts = <0x3 0x2 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "sc-err"; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/regulator/silergy,sy8827n.yaml b/Documentation/devicetree/bindings/regulator/silergy,sy8827n.yaml new file mode 100644 index 000000000000..15983cdc7c28 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/silergy,sy8827n.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/silergy,sy8827n.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: silergy sy8827n PMIC + +maintainers: + - Jisheng Zhang <jszhang@kernel.org> + +properties: + compatible: + enum: + - silergy,sy8827n + + reg: + maxItems: 1 + + enable-gpios: + description: GPIO to enable/disable the regulator. + maxItems: 1 + + silergy,vsel-state-high: + type: boolean + description: + Indicates if the VSEL pin is set to high. + If this property is missing, assume the VSEL pin is set to low. + +required: + - compatible + - reg + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + regulator@60 { + compatible = "silergy,sy8827n"; + reg = <0x60>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/reset/fsl,imx-src.txt b/Documentation/devicetree/bindings/reset/fsl,imx-src.txt deleted file mode 100644 index 6ed79e60248a..000000000000 --- a/Documentation/devicetree/bindings/reset/fsl,imx-src.txt +++ /dev/null @@ -1,49 +0,0 @@ -Freescale i.MX System Reset Controller -====================================== - -Please also refer to reset.txt in this directory for common reset -controller binding usage. - -Required properties: -- compatible: Should be "fsl,<chip>-src" -- reg: should be register base and length as documented in the - datasheet -- interrupts: Should contain SRC interrupt and CPU WDOG interrupt, - in this order. -- #reset-cells: 1, see below - -example: - -src: src@20d8000 { - compatible = "fsl,imx6q-src"; - reg = <0x020d8000 0x4000>; - interrupts = <0 91 0x04 0 96 0x04>; - #reset-cells = <1>; -}; - -Specifying reset lines connected to IP modules -============================================== - -The system reset controller can be used to reset the GPU, VPU, -IPU, and OpenVG IP modules on i.MX5 and i.MX6 ICs. Those device -nodes should specify the reset line on the SRC in their resets -property, containing a phandle to the SRC device node and a -RESET_INDEX specifying which module to reset, as described in -reset.txt - -example: - - ipu1: ipu@2400000 { - resets = <&src 2>; - }; - ipu2: ipu@2800000 { - resets = <&src 4>; - }; - -The following RESET_INDEX values are valid for i.MX5: -GPU_RESET 0 -VPU_RESET 1 -IPU1_RESET 2 -OPEN_VG_RESET 3 -The following additional RESET_INDEX value is valid for i.MX6: -IPU2_RESET 4 diff --git a/Documentation/devicetree/bindings/reset/fsl,imx-src.yaml b/Documentation/devicetree/bindings/reset/fsl,imx-src.yaml new file mode 100644 index 000000000000..27c5e34a3ac6 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/fsl,imx-src.yaml @@ -0,0 +1,82 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/reset/fsl,imx-src.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale i.MX System Reset Controller + +maintainers: + - Philipp Zabel <p.zabel@pengutronix.de> + +description: | + The system reset controller can be used to reset the GPU, VPU, + IPU, and OpenVG IP modules on i.MX5 and i.MX6 ICs. Those device + nodes should specify the reset line on the SRC in their resets + property, containing a phandle to the SRC device node and a + RESET_INDEX specifying which module to reset, as described in + reset.txt + + The following RESET_INDEX values are valid for i.MX5: + GPU_RESET 0 + VPU_RESET 1 + IPU1_RESET 2 + OPEN_VG_RESET 3 + The following additional RESET_INDEX value is valid for i.MX6: + IPU2_RESET 4 + +properties: + compatible: + oneOf: + - const: "fsl,imx51-src" + - items: + - const: "fsl,imx50-src" + - const: "fsl,imx51-src" + - items: + - const: "fsl,imx53-src" + - const: "fsl,imx51-src" + - items: + - const: "fsl,imx6q-src" + - const: "fsl,imx51-src" + - items: + - const: "fsl,imx6sx-src" + - const: "fsl,imx51-src" + - items: + - const: "fsl,imx6sl-src" + - const: "fsl,imx51-src" + - items: + - const: "fsl,imx6ul-src" + - const: "fsl,imx51-src" + - items: + - const: "fsl,imx6sll-src" + - const: "fsl,imx51-src" + + reg: + maxItems: 1 + + interrupts: + items: + - description: SRC interrupt + - description: CPU WDOG interrupts out of SRC + minItems: 1 + maxItems: 2 + + '#reset-cells': + const: 1 + +required: + - compatible + - reg + - interrupts + - '#reset-cells' + +additionalProperties: false + +examples: + - | + reset-controller@73fd0000 { + compatible = "fsl,imx51-src"; + reg = <0x73fd0000 0x4000>; + interrupts = <75>; + #reset-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt b/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt deleted file mode 100644 index e10502d9153e..000000000000 --- a/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt +++ /dev/null @@ -1,56 +0,0 @@ -Freescale i.MX7 System Reset Controller -====================================== - -Please also refer to reset.txt in this directory for common reset -controller binding usage. - -Required properties: -- compatible: - - For i.MX7 SoCs should be "fsl,imx7d-src", "syscon" - - For i.MX8MQ SoCs should be "fsl,imx8mq-src", "syscon" - - For i.MX8MM SoCs should be "fsl,imx8mm-src", "fsl,imx8mq-src", "syscon" - - For i.MX8MN SoCs should be "fsl,imx8mn-src", "fsl,imx8mq-src", "syscon" - - For i.MX8MP SoCs should be "fsl,imx8mp-src", "syscon" -- reg: should be register base and length as documented in the - datasheet -- interrupts: Should contain SRC interrupt -- #reset-cells: 1, see below - -example: - -src: reset-controller@30390000 { - compatible = "fsl,imx7d-src", "syscon"; - reg = <0x30390000 0x2000>; - interrupts = <GIC_SPI 89 IRQ_TYPE_LEVEL_HIGH>; - #reset-cells = <1>; -}; - - -Specifying reset lines connected to IP modules -============================================== - -The system reset controller can be used to reset various set of -peripherals. Device nodes that need access to reset lines should -specify them as a reset phandle in their corresponding node as -specified in reset.txt. - -Example: - - pcie: pcie@33800000 { - - ... - - resets = <&src IMX7_RESET_PCIEPHY>, - <&src IMX7_RESET_PCIE_CTRL_APPS_EN>; - reset-names = "pciephy", "apps"; - - ... - }; - - -For list of all valid reset indices see -<dt-bindings/reset/imx7-reset.h> for i.MX7, -<dt-bindings/reset/imx8mq-reset.h> for i.MX8MQ and -<dt-bindings/reset/imx8mq-reset.h> for i.MX8MM and -<dt-bindings/reset/imx8mq-reset.h> for i.MX8MN and -<dt-bindings/reset/imx8mp-reset.h> for i.MX8MP diff --git a/Documentation/devicetree/bindings/reset/fsl,imx7-src.yaml b/Documentation/devicetree/bindings/reset/fsl,imx7-src.yaml new file mode 100644 index 000000000000..b1a71c1bb05b --- /dev/null +++ b/Documentation/devicetree/bindings/reset/fsl,imx7-src.yaml @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/reset/fsl,imx7-src.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale i.MX7 System Reset Controller + +maintainers: + - Andrey Smirnov <andrew.smirnov@gmail.com> + +description: | + The system reset controller can be used to reset various set of + peripherals. Device nodes that need access to reset lines should + specify them as a reset phandle in their corresponding node as + specified in reset.txt. + + For list of all valid reset indices see + <dt-bindings/reset/imx7-reset.h> for i.MX7, + <dt-bindings/reset/imx8mq-reset.h> for i.MX8MQ, i.MX8MM and i.MX8MN, + <dt-bindings/reset/imx8mp-reset.h> for i.MX8MP. + +properties: + compatible: + items: + - enum: + - fsl,imx7d-src + - fsl,imx8mq-src + - fsl,imx8mp-src + - const: syscon + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + '#reset-cells': + const: 1 + +required: + - compatible + - reg + - interrupts + - '#reset-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + reset-controller@30390000 { + compatible = "fsl,imx7d-src", "syscon"; + reg = <0x30390000 0x2000>; + interrupts = <GIC_SPI 89 IRQ_TYPE_LEVEL_HIGH>; + #reset-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/reset/renesas,rst.yaml b/Documentation/devicetree/bindings/reset/renesas,rst.yaml index 4c2b429ac702..2849ce45703c 100644 --- a/Documentation/devicetree/bindings/reset/renesas,rst.yaml +++ b/Documentation/devicetree/bindings/reset/renesas,rst.yaml @@ -31,6 +31,7 @@ properties: - renesas,r8a774a1-rst # RZ/G2M - renesas,r8a774b1-rst # RZ/G2N - renesas,r8a774c0-rst # RZ/G2E + - renesas,r8a774e1-rst # RZ/G2H - renesas,r8a7778-reset-wdt # R-Car M1A - renesas,r8a7779-reset-wdt # R-Car H1 - renesas,r8a7790-rst # R-Car H2 diff --git a/Documentation/devicetree/bindings/reset/socionext,uniphier-reset.yaml b/Documentation/devicetree/bindings/reset/socionext,uniphier-reset.yaml new file mode 100644 index 000000000000..4c9b0ebf6869 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/socionext,uniphier-reset.yaml @@ -0,0 +1,112 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/reset/socionext,uniphier-reset.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: UniPhier reset controller + +maintainers: + - Masahiro Yamada <yamada.masahiro@socionext.com> + +properties: + compatible: + oneOf: + - description: System reset + enum: + - socionext,uniphier-ld4-reset + - socionext,uniphier-pro4-reset + - socionext,uniphier-sld8-reset + - socionext,uniphier-pro5-reset + - socionext,uniphier-pxs2-reset + - socionext,uniphier-ld6b-reset + - socionext,uniphier-ld11-reset + - socionext,uniphier-ld20-reset + - socionext,uniphier-pxs3-reset + - description: Media I/O (MIO) reset, SD reset + enum: + - socionext,uniphier-ld4-mio-reset + - socionext,uniphier-pro4-mio-reset + - socionext,uniphier-sld8-mio-reset + - socionext,uniphier-pro5-sd-reset + - socionext,uniphier-pxs2-sd-reset + - socionext,uniphier-ld11-mio-reset + - socionext,uniphier-ld11-sd-reset + - socionext,uniphier-ld20-sd-reset + - socionext,uniphier-pxs3-sd-reset + - description: Peripheral reset + enum: + - socionext,uniphier-ld4-peri-reset + - socionext,uniphier-pro4-peri-reset + - socionext,uniphier-sld8-peri-reset + - socionext,uniphier-pro5-peri-reset + - socionext,uniphier-pxs2-peri-reset + - socionext,uniphier-ld11-peri-reset + - socionext,uniphier-ld20-peri-reset + - socionext,uniphier-pxs3-peri-reset + - description: Analog signal amplifier reset + enum: + - socionext,uniphier-ld11-adamv-reset + - socionext,uniphier-ld20-adamv-reset + + "#reset-cells": + const: 1 + +additionalProperties: false + +required: + - compatible + - "#reset-cells" + +examples: + - | + sysctrl@61840000 { + compatible = "socionext,uniphier-sysctrl", "simple-mfd", "syscon"; + reg = <0x61840000 0x4000>; + + reset { + compatible = "socionext,uniphier-ld11-reset"; + #reset-cells = <1>; + }; + + // other nodes ... + }; + + - | + mioctrl@59810000 { + compatible = "socionext,uniphier-mioctrl", "simple-mfd", "syscon"; + reg = <0x59810000 0x800>; + + reset { + compatible = "socionext,uniphier-ld11-mio-reset"; + #reset-cells = <1>; + }; + + // other nodes ... + }; + + - | + perictrl@59820000 { + compatible = "socionext,uniphier-perictrl", "simple-mfd", "syscon"; + reg = <0x59820000 0x200>; + + reset { + compatible = "socionext,uniphier-ld11-peri-reset"; + #reset-cells = <1>; + }; + + // other nodes ... + }; + + - | + adamv@57920000 { + compatible = "socionext,uniphier-ld11-adamv", "simple-mfd", "syscon"; + reg = <0x57920000 0x1000>; + + reset { + compatible = "socionext,uniphier-ld11-adamv-reset"; + #reset-cells = <1>; + }; + + // other nodes ... + }; diff --git a/Documentation/devicetree/bindings/reset/uniphier-reset.txt b/Documentation/devicetree/bindings/reset/uniphier-reset.txt index e320a8cc9e4d..88e06e5e8d23 100644 --- a/Documentation/devicetree/bindings/reset/uniphier-reset.txt +++ b/Documentation/devicetree/bindings/reset/uniphier-reset.txt @@ -1,123 +1,4 @@ -UniPhier reset controller - - -System reset ------------- - -Required properties: -- compatible: should be one of the following: - "socionext,uniphier-ld4-reset" - for LD4 SoC - "socionext,uniphier-pro4-reset" - for Pro4 SoC - "socionext,uniphier-sld8-reset" - for sLD8 SoC - "socionext,uniphier-pro5-reset" - for Pro5 SoC - "socionext,uniphier-pxs2-reset" - for PXs2/LD6b SoC - "socionext,uniphier-ld11-reset" - for LD11 SoC - "socionext,uniphier-ld20-reset" - for LD20 SoC - "socionext,uniphier-pxs3-reset" - for PXs3 SoC -- #reset-cells: should be 1. - -Example: - - sysctrl@61840000 { - compatible = "socionext,uniphier-ld11-sysctrl", - "simple-mfd", "syscon"; - reg = <0x61840000 0x4000>; - - reset { - compatible = "socionext,uniphier-ld11-reset"; - #reset-cells = <1>; - }; - - other nodes ... - }; - - -Media I/O (MIO) reset, SD reset -------------------------------- - -Required properties: -- compatible: should be one of the following: - "socionext,uniphier-ld4-mio-reset" - for LD4 SoC - "socionext,uniphier-pro4-mio-reset" - for Pro4 SoC - "socionext,uniphier-sld8-mio-reset" - for sLD8 SoC - "socionext,uniphier-pro5-sd-reset" - for Pro5 SoC - "socionext,uniphier-pxs2-sd-reset" - for PXs2/LD6b SoC - "socionext,uniphier-ld11-mio-reset" - for LD11 SoC (MIO) - "socionext,uniphier-ld11-sd-reset" - for LD11 SoC (SD) - "socionext,uniphier-ld20-sd-reset" - for LD20 SoC - "socionext,uniphier-pxs3-sd-reset" - for PXs3 SoC -- #reset-cells: should be 1. - -Example: - - mioctrl@59810000 { - compatible = "socionext,uniphier-ld11-mioctrl", - "simple-mfd", "syscon"; - reg = <0x59810000 0x800>; - - reset { - compatible = "socionext,uniphier-ld11-mio-reset"; - #reset-cells = <1>; - }; - - other nodes ... - }; - - -Peripheral reset ----------------- - -Required properties: -- compatible: should be one of the following: - "socionext,uniphier-ld4-peri-reset" - for LD4 SoC - "socionext,uniphier-pro4-peri-reset" - for Pro4 SoC - "socionext,uniphier-sld8-peri-reset" - for sLD8 SoC - "socionext,uniphier-pro5-peri-reset" - for Pro5 SoC - "socionext,uniphier-pxs2-peri-reset" - for PXs2/LD6b SoC - "socionext,uniphier-ld11-peri-reset" - for LD11 SoC - "socionext,uniphier-ld20-peri-reset" - for LD20 SoC - "socionext,uniphier-pxs3-peri-reset" - for PXs3 SoC -- #reset-cells: should be 1. - -Example: - - perictrl@59820000 { - compatible = "socionext,uniphier-ld11-perictrl", - "simple-mfd", "syscon"; - reg = <0x59820000 0x200>; - - reset { - compatible = "socionext,uniphier-ld11-peri-reset"; - #reset-cells = <1>; - }; - - other nodes ... - }; - - -Analog signal amplifier reset ------------------------------ - -Required properties: -- compatible: should be one of the following: - "socionext,uniphier-ld11-adamv-reset" - for LD11 SoC - "socionext,uniphier-ld20-adamv-reset" - for LD20 SoC -- #reset-cells: should be 1. - -Example: - - adamv@57920000 { - compatible = "socionext,uniphier-ld11-adamv", - "simple-mfd", "syscon"; - reg = <0x57920000 0x1000>; - - adamv_rst: reset { - compatible = "socionext,uniphier-ld11-adamv-reset"; - #reset-cells = <1>; - }; - - other nodes ... - }; +UniPhier glue reset controller Peripheral core reset in glue layer diff --git a/Documentation/devicetree/bindings/rng/imx-rng.txt b/Documentation/devicetree/bindings/rng/imx-rng.txt index 405c2b00ccb0..659d4efdd664 100644 --- a/Documentation/devicetree/bindings/rng/imx-rng.txt +++ b/Documentation/devicetree/bindings/rng/imx-rng.txt @@ -5,6 +5,9 @@ Required properties: "fsl,imx21-rnga" "fsl,imx31-rnga" (backward compatible with "fsl,imx21-rnga") "fsl,imx25-rngb" + "fsl,imx6sl-rngb" (backward compatible with "fsl,imx25-rngb") + "fsl,imx6sll-rngb" (backward compatible with "fsl,imx25-rngb") + "fsl,imx6ull-rngb" (backward compatible with "fsl,imx25-rngb") "fsl,imx35-rngc" - reg : offset and length of the register set of this block - interrupts : the interrupt number for the RNG block diff --git a/Documentation/devicetree/bindings/rng/ingenic,rng.yaml b/Documentation/devicetree/bindings/rng/ingenic,rng.yaml new file mode 100644 index 000000000000..b2e4a6a7f93a --- /dev/null +++ b/Documentation/devicetree/bindings/rng/ingenic,rng.yaml @@ -0,0 +1,36 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rng/ingenic,rng.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Bindings for RNG in Ingenic SoCs + +maintainers: + - 周ç°æ° (Zhou Yanjie) <zhouyanjie@wanyeetech.com> + +description: + The Random Number Generator in Ingenic SoCs. + +properties: + compatible: + enum: + - ingenic,jz4780-rng + - ingenic,x1000-rng + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + rng: rng@d8 { + compatible = "ingenic,jz4780-rng"; + reg = <0xd8 0x8>; + }; +... diff --git a/Documentation/devicetree/bindings/rng/silex-insight,ba431-rng.yaml b/Documentation/devicetree/bindings/rng/silex-insight,ba431-rng.yaml new file mode 100644 index 000000000000..48ab82abf50e --- /dev/null +++ b/Documentation/devicetree/bindings/rng/silex-insight,ba431-rng.yaml @@ -0,0 +1,36 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rng/silex-insight,ba431-rng.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Silex Insight BA431 RNG bindings + +description: | + The BA431 hardware random number generator is an IP that is FIPS-140-2/3 + certified. + +maintainers: + - Olivier Sobrie <olivier.sobrie@silexinsight.com> + +properties: + compatible: + const: silex-insight,ba431-rng + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + rng@42800000 { + compatible = "silex-insight,ba431-rng"; + reg = <0x42800000 0x1000>; + }; + +... diff --git a/Documentation/devicetree/bindings/rtc/atmel,at91sam9-rtc.txt b/Documentation/devicetree/bindings/rtc/atmel,at91sam9-rtc.txt index 6ae79d1843f3..3f0e2a5950eb 100644 --- a/Documentation/devicetree/bindings/rtc/atmel,at91sam9-rtc.txt +++ b/Documentation/devicetree/bindings/rtc/atmel,at91sam9-rtc.txt @@ -1,7 +1,9 @@ Atmel AT91SAM9260 Real Time Timer Required properties: -- compatible: should be: "atmel,at91sam9260-rtt" +- compatible: should be one of the following: + - "atmel,at91sam9260-rtt" + - "microchip,sam9x60-rtt", "atmel,at91sam9260-rtt" - reg: should encode the memory region of the RTT controller - interrupts: rtt alarm/event interrupt - clocks: should contain the 32 KHz slow clk that will drive the RTT block. diff --git a/Documentation/devicetree/bindings/rtc/imxdi-rtc.txt b/Documentation/devicetree/bindings/rtc/imxdi-rtc.txt deleted file mode 100644 index c797bc9d77d2..000000000000 --- a/Documentation/devicetree/bindings/rtc/imxdi-rtc.txt +++ /dev/null @@ -1,20 +0,0 @@ -* i.MX25 Real Time Clock controller - -Required properties: -- compatible: should be: "fsl,imx25-rtc" -- reg: physical base address of the controller and length of memory mapped - region. -- clocks: should contain the phandle for the rtc clock -- interrupts: rtc alarm interrupt - -Optional properties: -- interrupts: dryice security violation interrupt (second entry) - -Example: - -rtc@53ffc000 { - compatible = "fsl,imx25-rtc"; - reg = <0x53ffc000 0x4000>; - clocks = <&clks 81>; - interrupts = <25 56>; -}; diff --git a/Documentation/devicetree/bindings/rtc/imxdi-rtc.yaml b/Documentation/devicetree/bindings/rtc/imxdi-rtc.yaml new file mode 100644 index 000000000000..06bd737821c1 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/imxdi-rtc.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/imxdi-rtc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: i.MX25 Real Time Clock controller + +maintainers: + - Roland Stigge <stigge@antcom.de> + +properties: + compatible: + const: fsl,imx25-rtc + + reg: + maxItems: 1 + + interrupts: + items: + - description: rtc alarm interrupt + - description: dryice security violation interrupt + minItems: 1 + maxItems: 2 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + +additionalProperties: false + +examples: + - | + rtc@53ffc000 { + compatible = "fsl,imx25-rtc"; + reg = <0x53ffc000 0x4000>; + clocks = <&clks 81>; + interrupts = <25>, <56>; + }; diff --git a/Documentation/devicetree/bindings/rtc/sa1100-rtc.txt b/Documentation/devicetree/bindings/rtc/sa1100-rtc.txt deleted file mode 100644 index 968ac820254b..000000000000 --- a/Documentation/devicetree/bindings/rtc/sa1100-rtc.txt +++ /dev/null @@ -1,17 +0,0 @@ -* Marvell Real Time Clock controller - -Required properties: -- compatible: should be "mrvl,sa1100-rtc" -- reg: physical base address of the controller and length of memory mapped - region. -- interrupts: Should be two. The first interrupt number is the rtc alarm - interrupt and the second interrupt number is the rtc hz interrupt. -- interrupt-names: Assign name of irq resource. - -Example: - rtc: rtc@d4010000 { - compatible = "mrvl,mmp-rtc"; - reg = <0xd4010000 0x1000>; - interrupts = <5>, <6>; - interrupt-names = "rtc 1Hz", "rtc alarm"; - }; diff --git a/Documentation/devicetree/bindings/rtc/sa1100-rtc.yaml b/Documentation/devicetree/bindings/rtc/sa1100-rtc.yaml new file mode 100644 index 000000000000..482e5af215b3 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/sa1100-rtc.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/sa1100-rtc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell Real Time Clock controller bindings + +allOf: + - $ref: rtc.yaml# + +maintainers: + - Alessandro Zummo <a.zummo@towertech.it> + - Alexandre Belloni <alexandre.belloni@bootlin.com> + - Rob Herring <robh+dt@kernel.org> + +properties: + compatible: + enum: + - mrvl,sa1100-rtc + - mrvl,mmp-rtc + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + + interrupts: + minItems: 2 + + interrupt-names: + items: + - const: 'rtc 1Hz' + - const: 'rtc alarm' + +required: + - compatible + - reg + - interrupts + - interrupt-names + +additionalProperties: false + +examples: + - | + rtc: rtc@d4010000 { + compatible = "mrvl,mmp-rtc"; + reg = <0xd4010000 0x1000>; + interrupts = <5>, <6>; + interrupt-names = "rtc 1Hz", "rtc alarm"; + }; + +... diff --git a/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml b/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml index 75b8521eb7cb..06d5f251ec88 100644 --- a/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml +++ b/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml @@ -35,9 +35,11 @@ properties: description: label associated with this uart st,hw-flow-ctrl: - description: enable hardware flow control + description: enable hardware flow control (deprecated) $ref: /schemas/types.yaml#/definitions/flag + uart-has-rtscts: true + dmas: minItems: 1 maxItems: 2 diff --git a/Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml b/Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml new file mode 100644 index 000000000000..3cd0b70cd6cf --- /dev/null +++ b/Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml @@ -0,0 +1,181 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/soc/microchip/atmel,at91rm9200-tcb.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Atmel Timer Counter Block + +maintainers: + - Alexandre Belloni <alexandre.belloni@bootlin.com> + +description: | + The Atmel (now Microchip) SoCs have timers named Timer Counter Block. Each + timer has three channels with two counters each. + +properties: + compatible: + items: + - enum: + - atmel,at91rm9200-tcb + - atmel,at91sam9x5-tcb + - atmel,sama5d2-tcb + - const: simple-mfd + - const: syscon + + reg: + maxItems: 1 + + interrupts: + description: + List of interrupts. One interrupt per TCB channel if available or one + interrupt for the TC block + minItems: 1 + maxItems: 3 + + clock-names: + description: + List of clock names. Always includes t0_clk and slow clk. Also includes + t1_clk and t2_clk if a clock per channel is available. + minItems: 2 + maxItems: 4 + + clocks: + minItems: 2 + maxItems: 4 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + +patternProperties: + "^timer@[0-2]$": + description: The timer block channels that are used as timers or counters. + type: object + properties: + compatible: + items: + - enum: + - atmel,tcb-timer + - microchip,tcb-capture + reg: + description: + List of channels to use for this particular timer. In Microchip TCB capture + mode channels are registered as a counter devices, for the qdec mode TCB0's + channel <0> and <1> are required. + + minItems: 1 + maxItems: 3 + + required: + - compatible + - reg + +allOf: + - if: + properties: + compatible: + contains: + const: atmel,sama5d2-tcb + then: + properties: + clocks: + minItems: 3 + maxItems: 3 + clock-names: + items: + - const: t0_clk + - const: gclk + - const: slow_clk + else: + properties: + clocks: + minItems: 2 + maxItems: 4 + clock-names: + oneOf: + - items: + - const: t0_clk + - const: slow_clk + - items: + - const: t0_clk + - const: t1_clk + - const: t2_clk + - const: slow_clk + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - '#address-cells' + - '#size-cells' + +additionalProperties: false + +examples: + - | + /* One interrupt per TC block: */ + tcb0: timer@fff7c000 { + compatible = "atmel,at91rm9200-tcb", "simple-mfd", "syscon"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xfff7c000 0x100>; + interrupts = <18 4>; + clocks = <&tcb0_clk>, <&clk32k>; + clock-names = "t0_clk", "slow_clk"; + + timer@0 { + compatible = "atmel,tcb-timer"; + reg = <0>, <1>; + }; + + timer@2 { + compatible = "atmel,tcb-timer"; + reg = <2>; + }; + }; + + /* One interrupt per TC channel in a TC block: */ + tcb1: timer@fffdc000 { + compatible = "atmel,at91rm9200-tcb", "simple-mfd", "syscon"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xfffdc000 0x100>; + interrupts = <26 4>, <27 4>, <28 4>; + clocks = <&tcb1_clk>, <&clk32k>; + clock-names = "t0_clk", "slow_clk"; + + timer@0 { + compatible = "atmel,tcb-timer"; + reg = <0>; + }; + + timer@1 { + compatible = "atmel,tcb-timer"; + reg = <1>; + }; + }; + /* TCB0 Capture with QDEC: */ + timer@f800c000 { + compatible = "atmel,at91rm9200-tcb", "simple-mfd", "syscon"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xfff7c000 0x100>; + interrupts = <18 4>; + clocks = <&tcb0_clk>, <&clk32k>; + clock-names = "t0_clk", "slow_clk"; + + timer@0 { + compatible = "microchip,tcb-capture"; + reg = <0>, <1>; + }; + + timer@2 { + compatible = "atmel,tcb-timer"; + reg = <2>; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.txt deleted file mode 100644 index 616fddcd09fd..000000000000 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.txt +++ /dev/null @@ -1,62 +0,0 @@ -Qualcomm Resource Power Manager (RPM) over SMD - -This driver is used to interface with the Resource Power Manager (RPM) found in -various Qualcomm platforms. The RPM allows each component in the system to vote -for state of the system resources, such as clocks, regulators and bus -frequencies. - -The SMD information for the RPM edge should be filled out. See qcom,smd.txt for -the required edge properties. All SMD related properties will reside within the -RPM node itself. - -= SUBDEVICES - -The RPM exposes resources to its subnodes. The rpm_requests node must be -present and this subnode may contain children that designate regulator -resources. - -- compatible: - Usage: required - Value type: <string> - Definition: must be one of: - "qcom,rpm-apq8084" - "qcom,rpm-msm8916" - "qcom,rpm-msm8974" - "qcom,rpm-msm8976" - "qcom,rpm-msm8998" - "qcom,rpm-sdm660" - "qcom,rpm-qcs404" - -- qcom,smd-channels: - Usage: required - Value type: <string> - Definition: must be "rpm_requests" - -Refer to Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt -for information on the regulator subnodes that can exist under the rpm_requests. - -Example: - - soc { - apcs: syscon@f9011000 { - compatible = "syscon"; - reg = <0xf9011000 0x1000>; - }; - }; - - smd { - compatible = "qcom,smd"; - - rpm { - interrupts = <0 168 1>; - qcom,ipc = <&apcs 8 0>; - qcom,smd-edge = <15>; - - rpm_requests { - compatible = "qcom,rpm-msm8974"; - qcom,smd-channels = "rpm_requests"; - - ... - }; - }; - }; diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml new file mode 100644 index 000000000000..468d658ce3e7 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.yaml @@ -0,0 +1,87 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/soc/qcom/qcom,smd-rpm.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Qualcomm Resource Power Manager (RPM) over SMD + +description: | + This driver is used to interface with the Resource Power Manager (RPM) found + in various Qualcomm platforms. The RPM allows each component in the system + to vote for state of the system resources, such as clocks, regulators and bus + frequencies. + + The SMD information for the RPM edge should be filled out. See qcom,smd.txt + for the required edge properties. All SMD related properties will reside + within the RPM node itself. + + The RPM exposes resources to its subnodes. The rpm_requests node must be + present and this subnode may contain children that designate regulator + resources. + + Refer to Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt + for information on the regulator subnodes that can exist under the + rpm_requests. + +maintainers: + - Kathiravan T <kathirav@codeaurora.org> + +properties: + compatible: + enum: + - qcom,rpm-apq8084 + - qcom,rpm-ipq6018 + - qcom,rpm-msm8916 + - qcom,rpm-msm8974 + - qcom,rpm-msm8976 + - qcom,rpm-msm8996 + - qcom,rpm-msm8998 + - qcom,rpm-sdm660 + - qcom,rpm-qcs404 + + qcom,smd-channels: + $ref: /schemas/types.yaml#/definitions/string-array + description: Channel name used for the RPM communication + items: + - const: rpm_requests + +if: + properties: + compatible: + contains: + enum: + - qcom,rpm-apq8084 + - qcom,rpm-msm8916 + - qcom,rpm-msm8974 +then: + required: + - qcom,smd-channels + +required: + - compatible + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + smd { + compatible = "qcom,smd"; + + rpm { + interrupts = <GIC_SPI 168 IRQ_TYPE_EDGE_RISING>; + qcom,ipc = <&apcs 8 0>; + qcom,smd-edge = <15>; + + rpm_requests { + compatible = "qcom,rpm-msm8974"; + qcom,smd-channels = "rpm_requests"; + + /* Regulator nodes to follow */ + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/soc/ti/k3-ringacc.txt b/Documentation/devicetree/bindings/soc/ti/k3-ringacc.txt deleted file mode 100644 index 59758ccce809..000000000000 --- a/Documentation/devicetree/bindings/soc/ti/k3-ringacc.txt +++ /dev/null @@ -1,59 +0,0 @@ -* Texas Instruments K3 NavigatorSS Ring Accelerator - -The Ring Accelerator (RA) is a machine which converts read/write accesses -from/to a constant address into corresponding read/write accesses from/to a -circular data structure in memory. The RA eliminates the need for each DMA -controller which needs to access ring elements from having to know the current -state of the ring (base address, current offset). The DMA controller -performs a read or write access to a specific address range (which maps to the -source interface on the RA) and the RA replaces the address for the transaction -with a new address which corresponds to the head or tail element of the ring -(head for reads, tail for writes). - -The Ring Accelerator is a hardware module that is responsible for accelerating -management of the packet queues. The K3 SoCs can have more than one RA instances - -Required properties: -- compatible : Must be "ti,am654-navss-ringacc"; -- reg : Should contain register location and length of the following - named register regions. -- reg-names : should be - "rt" - The RA Ring Real-time Control/Status Registers - "fifos" - The RA Queues Registers - "proxy_gcfg" - The RA Proxy Global Config Registers - "proxy_target" - The RA Proxy Datapath Registers -- ti,num-rings : Number of rings supported by RA -- ti,sci-rm-range-gp-rings : TI-SCI RM subtype for GP ring range -- ti,sci : phandle on TI-SCI compatible System controller node -- ti,sci-dev-id : TI-SCI device id of the ring accelerator -- msi-parent : phandle for "ti,sci-inta" interrupt controller - -Optional properties: - -- ti,dma-ring-reset-quirk : enable ringacc / udma ring state interoperability - issue software w/a - -Example: - -ringacc: ringacc@3c000000 { - compatible = "ti,am654-navss-ringacc"; - reg = <0x0 0x3c000000 0x0 0x400000>, - <0x0 0x38000000 0x0 0x400000>, - <0x0 0x31120000 0x0 0x100>, - <0x0 0x33000000 0x0 0x40000>; - reg-names = "rt", "fifos", - "proxy_gcfg", "proxy_target"; - ti,num-rings = <818>; - ti,sci-rm-range-gp-rings = <0x2>; /* GP ring range */ - ti,dma-ring-reset-quirk; - ti,sci = <&dmsc>; - ti,sci-dev-id = <187>; - msi-parent = <&inta_main_udmass>; -}; - -client: - -dma_ipx: dma_ipx@<addr> { - ... - ti,ringacc = <&ringacc>; - ... -} diff --git a/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml b/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml new file mode 100644 index 000000000000..ae33fc957141 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/ti/k3-ringacc.yaml @@ -0,0 +1,102 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2020 Texas Instruments Incorporated - http://www.ti.com/ +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/soc/ti/k3-ringacc.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Texas Instruments K3 NavigatorSS Ring Accelerator + +maintainers: + - Santosh Shilimkar <ssantosh@kernel.org> + - Grygorii Strashko <grygorii.strashko@ti.com> + +description: | + The Ring Accelerator (RA) is a machine which converts read/write accesses + from/to a constant address into corresponding read/write accesses from/to a + circular data structure in memory. The RA eliminates the need for each DMA + controller which needs to access ring elements from having to know the current + state of the ring (base address, current offset). The DMA controller + performs a read or write access to a specific address range (which maps to the + source interface on the RA) and the RA replaces the address for the transaction + with a new address which corresponds to the head or tail element of the ring + (head for reads, tail for writes). + + The Ring Accelerator is a hardware module that is responsible for accelerating + management of the packet queues. The K3 SoCs can have more than one RA instances + +properties: + compatible: + items: + - const: ti,am654-navss-ringacc + + reg: + items: + - description: real time registers regions + - description: fifos registers regions + - description: proxy gcfg registers regions + - description: proxy target registers regions + + reg-names: + items: + - const: rt + - const: fifos + - const: proxy_gcfg + - const: proxy_target + + msi-parent: true + + ti,num-rings: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Number of rings supported by RA + + ti,sci-rm-range-gp-rings: + $ref: /schemas/types.yaml#/definitions/uint32 + description: TI-SCI RM subtype for GP ring range + + ti,sci: + $ref: /schemas/types.yaml#definitions/phandle-array + description: phandle on TI-SCI compatible System controller node + + ti,sci-dev-id: + $ref: /schemas/types.yaml#/definitions/uint32 + description: TI-SCI device id of the ring accelerator + + ti,dma-ring-reset-quirk: + $ref: /schemas/types.yaml#definitions/flag + description: | + enable ringacc/udma ring state interoperability issue software w/a + +required: + - compatible + - reg + - reg-names + - msi-parent + - ti,num-rings + - ti,sci-rm-range-gp-rings + - ti,sci + - ti,sci-dev-id + +additionalProperties: false + +examples: + - | + bus { + #address-cells = <2>; + #size-cells = <2>; + + ringacc: ringacc@3c000000 { + compatible = "ti,am654-navss-ringacc"; + reg = <0x0 0x3c000000 0x0 0x400000>, + <0x0 0x38000000 0x0 0x400000>, + <0x0 0x31120000 0x0 0x100>, + <0x0 0x33000000 0x0 0x40000>; + reg-names = "rt", "fifos", "proxy_gcfg", "proxy_target"; + ti,num-rings = <818>; + ti,sci-rm-range-gp-rings = <0x2>; /* GP ring range */ + ti,dma-ring-reset-quirk; + ti,sci = <&dmsc>; + ti,sci-dev-id = <187>; + msi-parent = <&inta_main_udmass>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/adi,adau1977.txt b/Documentation/devicetree/bindings/sound/adi,adau1977.txt index 9225472c80b4..37f8aad01203 100644 --- a/Documentation/devicetree/bindings/sound/adi,adau1977.txt +++ b/Documentation/devicetree/bindings/sound/adi,adau1977.txt @@ -1,9 +1,9 @@ Analog Devices ADAU1977/ADAU1978/ADAU1979 Datasheets: -http://www.analog.com/media/en/technical-documentation/data-sheets/ADAU1977.pdf -http://www.analog.com/media/en/technical-documentation/data-sheets/ADAU1978.pdf -http://www.analog.com/media/en/technical-documentation/data-sheets/ADAU1979.pdf +https://www.analog.com/media/en/technical-documentation/data-sheets/ADAU1977.pdf +https://www.analog.com/media/en/technical-documentation/data-sheets/ADAU1978.pdf +https://www.analog.com/media/en/technical-documentation/data-sheets/ADAU1979.pdf This driver supports both the I2C and SPI bus. diff --git a/Documentation/devicetree/bindings/sound/ak4613.txt b/Documentation/devicetree/bindings/sound/ak4613.txt deleted file mode 100644 index 49a2e74fd9cb..000000000000 --- a/Documentation/devicetree/bindings/sound/ak4613.txt +++ /dev/null @@ -1,27 +0,0 @@ -AK4613 I2C transmitter - -This device supports I2C mode only. - -Required properties: - -- compatible : "asahi-kasei,ak4613" -- reg : The chip select number on the I2C bus - -Optional properties: -- asahi-kasei,in1-single-end : Boolean. Indicate input / output pins are single-ended. -- asahi-kasei,in2-single-end rather than differential. -- asahi-kasei,out1-single-end -- asahi-kasei,out2-single-end -- asahi-kasei,out3-single-end -- asahi-kasei,out4-single-end -- asahi-kasei,out5-single-end -- asahi-kasei,out6-single-end - -Example: - -&i2c { - ak4613: ak4613@10 { - compatible = "asahi-kasei,ak4613"; - reg = <0x10>; - }; -}; diff --git a/Documentation/devicetree/bindings/sound/ak4613.yaml b/Documentation/devicetree/bindings/sound/ak4613.yaml new file mode 100644 index 000000000000..ef4055ef0ccd --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ak4613.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/ak4613.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: AK4613 I2C transmitter Device Tree Bindings + +maintainers: + - Kuninori Morimoto <kuninori.morimoto.gx@renesas.com> + +properties: + compatible: + const: asahi-kasei,ak4613 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + "#sound-dai-cells": + const: 0 + +patternProperties: + "^asahi-kasei,in[1-2]-single-end$": + description: Input Pin 1 - 2. + $ref: /schemas/types.yaml#/definitions/flag + + "^asahi-kasei,out[1-6]-single-end$": + description: Output Pin 1 - 6. + $ref: /schemas/types.yaml#/definitions/flag + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + ak4613: codec@10 { + compatible = "asahi-kasei,ak4613"; + reg = <0x10>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/ak4642.txt b/Documentation/devicetree/bindings/sound/ak4642.txt deleted file mode 100644 index 58e48ee97175..000000000000 --- a/Documentation/devicetree/bindings/sound/ak4642.txt +++ /dev/null @@ -1,37 +0,0 @@ -AK4642 I2C transmitter - -This device supports I2C mode only. - -Required properties: - - - compatible : "asahi-kasei,ak4642" or "asahi-kasei,ak4643" or "asahi-kasei,ak4648" - - reg : The chip select number on the I2C bus - -Optional properties: - - - #clock-cells : common clock binding; shall be set to 0 - - clocks : common clock binding; MCKI clock - - clock-frequency : common clock binding; frequency of MCKO - - clock-output-names : common clock binding; MCKO clock name - -Example 1: - -&i2c { - ak4648: ak4648@12 { - compatible = "asahi-kasei,ak4642"; - reg = <0x12>; - }; -}; - -Example 2: - -&i2c { - ak4643: codec@12 { - compatible = "asahi-kasei,ak4643"; - reg = <0x12>; - #clock-cells = <0>; - clocks = <&audio_clock>; - clock-frequency = <12288000>; - clock-output-names = "ak4643_mcko"; - }; -}; diff --git a/Documentation/devicetree/bindings/sound/ak4642.yaml b/Documentation/devicetree/bindings/sound/ak4642.yaml new file mode 100644 index 000000000000..6cd213be2266 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ak4642.yaml @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/ak4642.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: AK4642 I2C transmitter Device Tree Bindings + +maintainers: + - Kuninori Morimoto <kuninori.morimoto.gx@renesas.com> + +properties: + compatible: + enum: + - asahi-kasei,ak4642 + - asahi-kasei,ak4643 + - asahi-kasei,ak4648 + + reg: + maxItems: 1 + + "#clock-cells": + const: 0 + "#sound-dai-cells": + const: 0 + + clocks: + maxItems: 1 + + clock-frequency: + description: common clock binding; frequency of MCKO + $ref: /schemas/types.yaml#/definitions/uint32 + + clock-output-names: + description: common clock name + $ref: /schemas/types.yaml#/definitions/string + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + ak4643: codec@12 { + compatible = "asahi-kasei,ak4643"; + #sound-dai-cells = <0>; + reg = <0x12>; + #clock-cells = <0>; + clocks = <&audio_clock>; + clock-frequency = <12288000>; + clock-output-names = "ak4643_mcko"; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/audio-graph-card.txt b/Documentation/devicetree/bindings/sound/audio-graph-card.txt index 269682619a70..d5f6919a2d69 100644 --- a/Documentation/devicetree/bindings/sound/audio-graph-card.txt +++ b/Documentation/devicetree/bindings/sound/audio-graph-card.txt @@ -5,7 +5,7 @@ It is based on common bindings for device graphs. see ${LINUX}/Documentation/devicetree/bindings/graph.txt Basically, Audio Graph Card property is same as Simple Card. -see ${LINUX}/Documentation/devicetree/bindings/sound/simple-card.txt +see ${LINUX}/Documentation/devicetree/bindings/sound/simple-card.yaml Below are same as Simple-Card. diff --git a/Documentation/devicetree/bindings/sound/everest,es8316.txt b/Documentation/devicetree/bindings/sound/everest,es8316.txt deleted file mode 100644 index 1bf03c5f2af4..000000000000 --- a/Documentation/devicetree/bindings/sound/everest,es8316.txt +++ /dev/null @@ -1,23 +0,0 @@ -Everest ES8316 audio CODEC - -This device supports both I2C and SPI. - -Required properties: - - - compatible : should be "everest,es8316" - - reg : the I2C address of the device for I2C - -Optional properties: - - - clocks : a list of phandle, should contain entries for clock-names - - clock-names : should include as follows: - "mclk" : master clock (MCLK) of the device - -Example: - -es8316: codec@11 { - compatible = "everest,es8316"; - reg = <0x11>; - clocks = <&clks 10>; - clock-names = "mclk"; -}; diff --git a/Documentation/devicetree/bindings/sound/everest,es8316.yaml b/Documentation/devicetree/bindings/sound/everest,es8316.yaml new file mode 100644 index 000000000000..3b752bba748b --- /dev/null +++ b/Documentation/devicetree/bindings/sound/everest,es8316.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/everest,es8316.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Everest ES8316 audio CODEC + +maintainers: + - Daniel Drake <drake@endlessm.com> + - Katsuhiro Suzuki <katsuhiro@katsuster.net> + +properties: + compatible: + const: everest,es8316 + + reg: + maxItems: 1 + + clocks: + items: + - description: clock for master clock (MCLK) + + clock-names: + items: + - const: mclk + + "#sound-dai-cells": + const: 0 + +required: + - compatible + - reg + - "#sound-dai-cells" + +additionalProperties: false + +examples: + - | + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + es8316: codec@11 { + compatible = "everest,es8316"; + reg = <0x11>; + clocks = <&clks 10>; + clock-names = "mclk"; + #sound-dai-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/fsl,spdif.txt b/Documentation/devicetree/bindings/sound/fsl,spdif.txt index 8b324f82a782..e1365b0ee1e9 100644 --- a/Documentation/devicetree/bindings/sound/fsl,spdif.txt +++ b/Documentation/devicetree/bindings/sound/fsl,spdif.txt @@ -6,7 +6,11 @@ a fibre cable. Required properties: - - compatible : Compatible list, must contain "fsl,imx35-spdif". + - compatible : Compatible list, should contain one of the following + compatibles: + "fsl,imx35-spdif", + "fsl,vf610-spdif", + "fsl,imx6sx-spdif", - reg : Offset and length of the register set for the device. diff --git a/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt b/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt index c60a5732d29c..63ebf52b43e8 100644 --- a/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt +++ b/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt @@ -34,6 +34,10 @@ The compatible list for this generic sound card currently: "fsl,imx-audio-wm8960" + "fsl,imx-audio-mqs" + + "fsl,imx-audio-wm8524" + Required properties: - compatible : Contains one of entries in the compatible list. @@ -44,6 +48,11 @@ Required properties: - audio-codec : The phandle of an audio codec +Optional properties: + + - audio-asrc : The phandle of ASRC. It can be absent if there's no + need to add ASRC support via DPCM. + - audio-routing : A list of the connections between audio components. Each entry is a pair of strings, the first being the connection's sink, the second being the connection's @@ -60,10 +69,13 @@ Required properties: coexisting in order to support the old bindings of wm8962 and sgtl5000. -Optional properties: - - - audio-asrc : The phandle of ASRC. It can be absent if there's no - need to add ASRC support via DPCM. + - hp-det-gpio : The GPIO that detect headphones are plugged in + - mic-det-gpio : The GPIO that detect microphones are plugged in + - bitclock-master : Indicates dai-link bit clock master; for details see simple-card.yaml. + - frame-master : Indicates dai-link frame master; for details see simple-card.yaml. + - dai-format : audio format, for details see simple-card.yaml. + - frame-inversion : dai-link uses frame clock inversion, for details see simple-card.yaml. + - bitclock-inversion : dai-link uses bit clock inversion, for details see simple-card.yaml. Optional unless SSI is selected as a CPU DAI: diff --git a/Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml b/Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml new file mode 100644 index 000000000000..2e0bbc1c868a --- /dev/null +++ b/Documentation/devicetree/bindings/sound/intel,keembay-i2s.yaml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2020 Intel Corporation +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/intel,keembay-i2s.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel KeemBay I2S Device Tree Bindings + +maintainers: + - Sia, Jee Heng <jee.heng.sia@intel.com> + +description: | + Intel KeemBay I2S + +properties: + compatible: + enum: + - intel,keembay-i2s + + "#sound-dai-cells": + const: 0 + + reg: + items: + - description: I2S registers + - description: I2S gen configuration + + reg-names: + items: + - const: i2s-regs + - const: i2s_gen_cfg + + interrupts: + maxItems: 1 + + clocks: + items: + - description: Bus Clock + - description: Module Clock + + clock-names: + items: + - const: osc + - const: apb_clk + +required: + - compatible + - "#sound-dai-cells" + - reg + - clocks + - clock-names + - interrupts + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + #define KEEM_BAY_PSS_AUX_I2S3 + #define KEEM_BAY_PSS_I2S3 + i2s3: i2s@20140000 { + compatible = "intel,keembay-i2s"; + #sound-dai-cells = <0>; + reg = <0x20140000 0x200>, /* I2S registers */ + <0x202a00a4 0x4>; /* I2S gen configuration */ + reg-names = "i2s-regs", "i2s_gen_cfg"; + interrupts = <GIC_SPI 120 IRQ_TYPE_LEVEL_HIGH>; + clock-names = "osc", "apb_clk"; + clocks = <&scmi_clk KEEM_BAY_PSS_AUX_I2S3>, <&scmi_clk KEEM_BAY_PSS_I2S3>; + }; diff --git a/Documentation/devicetree/bindings/sound/max98357a.txt b/Documentation/devicetree/bindings/sound/max98357a.txt index 4bce14ce806f..75db84d06240 100644 --- a/Documentation/devicetree/bindings/sound/max98357a.txt +++ b/Documentation/devicetree/bindings/sound/max98357a.txt @@ -1,9 +1,10 @@ -Maxim MAX98357A audio DAC +Maxim MAX98357A/MAX98360A audio DAC -This node models the Maxim MAX98357A DAC. +This node models the Maxim MAX98357A/MAX98360A DAC. Required properties: -- compatible : "maxim,max98357a" +- compatible : "maxim,max98357a" for MAX98357A. + "maxim,max98360a" for MAX98360A. Optional properties: - sdmode-gpios : GPIO specifier for the chip's SD_MODE pin. @@ -20,3 +21,8 @@ max98357a { compatible = "maxim,max98357a"; sdmode-gpios = <&qcom_pinmux 25 0>; }; + +max98360a { + compatible = "maxim,max98360a"; + sdmode-gpios = <&qcom_pinmux 25 0>; +}; diff --git a/Documentation/devicetree/bindings/sound/maxim,max98390.yaml b/Documentation/devicetree/bindings/sound/maxim,max98390.yaml new file mode 100644 index 000000000000..e5ac35280da3 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/maxim,max98390.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/maxim,max98390.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim Integrated MAX98390 Speaker Amplifier with Integrated Dynamic Speaker Management + +maintainers: + - Steve Lee <steves.lee@maximintegrated.com> + +properties: + compatible: + const: maxim,max98390 + + reg: + maxItems: 1 + description: I2C address of the device. + + maxim,temperature_calib: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + description: The calculated temperature data was measured while doing the calibration. + minimum: 0 + maximum: 65535 + + maxim,r0_calib: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + description: This is r0 calibration data which was measured in factory mode. + minimum: 1 + maximum: 8388607 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + max98390: amplifier@38 { + compatible = "maxim,max98390"; + reg = <0x38>; + maxim,temperature_calib = <1024>; + maxim,r0_calib = <100232>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/mt6358.txt b/Documentation/devicetree/bindings/sound/mt6358.txt index 5465730013a1..59a73ffdf1d3 100644 --- a/Documentation/devicetree/bindings/sound/mt6358.txt +++ b/Documentation/devicetree/bindings/sound/mt6358.txt @@ -10,9 +10,15 @@ Required properties: - compatible : "mediatek,mt6358-sound". - Avdd-supply : power source of AVDD +Optional properties: +- mediatek,dmic-mode : Indicates how many data pins are used to transmit two + channels of PDM signal. 0 means two wires, 1 means one wire. Default + value is 0. + Example: mt6358_snd { compatible = "mediatek,mt6358-sound"; Avdd-supply = <&mt6358_vaud28_reg>; + mediatek,dmic-mode = <0>; }; diff --git a/Documentation/devicetree/bindings/sound/mt8183-da7219-max98357.txt b/Documentation/devicetree/bindings/sound/mt8183-da7219-max98357.txt index 92ac86f83822..6787ce8789dd 100644 --- a/Documentation/devicetree/bindings/sound/mt8183-da7219-max98357.txt +++ b/Documentation/devicetree/bindings/sound/mt8183-da7219-max98357.txt @@ -1,15 +1,20 @@ -MT8183 with MT6358, DA7219 and MAX98357 CODECS +MT8183 with MT6358, DA7219, MAX98357, and RT1015 CODECS Required properties: -- compatible : "mediatek,mt8183_da7219_max98357" +- compatible : "mediatek,mt8183_da7219_max98357" for MAX98357A codec + "mediatek,mt8183_da7219_rt1015" for RT1015 codec - mediatek,headset-codec: the phandles of da7219 codecs - mediatek,platform: the phandle of MT8183 ASoC platform +Optional properties: +- mediatek,hdmi-codec: the phandles of HDMI codec + Example: sound { compatible = "mediatek,mt8183_da7219_max98357"; mediatek,headset-codec = <&da7219>; + mediatek,hdmi-codec = <&it6505dptx>; mediatek,platform = <&afe>; }; diff --git a/Documentation/devicetree/bindings/sound/mt8183-mt6358-ts3a227-max98357.txt b/Documentation/devicetree/bindings/sound/mt8183-mt6358-ts3a227-max98357.txt index decaa013a07e..235eac8aea7b 100644 --- a/Documentation/devicetree/bindings/sound/mt8183-mt6358-ts3a227-max98357.txt +++ b/Documentation/devicetree/bindings/sound/mt8183-mt6358-ts3a227-max98357.txt @@ -1,13 +1,16 @@ -MT8183 with MT6358, TS3A227 and MAX98357 CODECS +MT8183 with MT6358, TS3A227, MAX98357, and RT1015 CODECS Required properties: -- compatible : "mediatek,mt8183_mt6358_ts3a227_max98357" +- compatible : "mediatek,mt8183_mt6358_ts3a227_max98357" for MAX98357A codec + "mediatek,mt8183_mt6358_ts3a227_max98357b" for MAX98357B codec + "mediatek,mt8183_mt6358_ts3a227_rt1015" for RT1015 codec - mediatek,platform: the phandle of MT8183 ASoC platform Optional properties: - mediatek,headset-codec: the phandles of ts3a227 codecs - mediatek,ec-codec: the phandle of EC codecs. See google,cros-ec-codec.txt for more details. +- mediatek,hdmi-codec: the phandles of HDMI codec Example: @@ -15,6 +18,7 @@ Example: compatible = "mediatek,mt8183_mt6358_ts3a227_max98357"; mediatek,headset-codec = <&ts3a227>; mediatek,ec-codec = <&ec_codec>; + mediatek,hdmi-codec = <&it6505dptx>; mediatek,platform = <&afe>; }; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml new file mode 100644 index 000000000000..e620c77d0728 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra186-dspk.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nvidia,tegra186-dspk.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Tegra186 DSPK Controller Device Tree Bindings + +description: | + The Digital Speaker Controller (DSPK) can be viewed as a Pulse + Density Modulation (PDM) transmitter that up-samples the input to + the desired sampling rate by interpolation and then converts the + over sampled Pulse Code Modulation (PCM) input to the desired 1-bit + output via Delta Sigma Modulation (DSM). + +maintainers: + - Jon Hunter <jonathanh@nvidia.com> + - Sameer Pujar <spujar@nvidia.com> + +properties: + $nodename: + pattern: "^dspk@[0-9a-f]*$" + + compatible: + oneOf: + - const: nvidia,tegra186-dspk + - items: + - const: nvidia,tegra194-dspk + - const: nvidia,tegra186-dspk + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + const: dspk + + assigned-clocks: + maxItems: 1 + + assigned-clock-parents: + maxItems: 1 + + assigned-clock-rates: + maxItems: 1 + + sound-name-prefix: + pattern: "^DSPK[1-9]$" + allOf: + - $ref: /schemas/types.yaml#/definitions/string + description: + Used as prefix for sink/source names of the component. Must be a + unique string among multiple instances of the same component. + The name can be "DSPK1" or "DSPKx", where x depends on the maximum + available instances on a Tegra SoC. + +required: + - compatible + - reg + - clocks + - clock-names + - assigned-clocks + - assigned-clock-parents + - sound-name-prefix + +examples: + - | + #include<dt-bindings/clock/tegra186-clock.h> + + dspk@2905000 { + compatible = "nvidia,tegra186-dspk"; + reg = <0x2905000 0x100>; + clocks = <&bpmp TEGRA186_CLK_DSPK1>; + clock-names = "dspk"; + assigned-clocks = <&bpmp TEGRA186_CLK_DSPK1>; + assigned-clock-parents = <&bpmp TEGRA186_CLK_PLL_A_OUT0>; + assigned-clock-rates = <12288000>; + sound-name-prefix = "DSPK1"; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-admaif.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-admaif.yaml new file mode 100644 index 000000000000..41c77f45d2fd --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-admaif.yaml @@ -0,0 +1,111 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nvidia,tegra210-admaif.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Tegra210 ADMAIF Device Tree Bindings + +description: | + ADMAIF is the interface between ADMA and AHUB. Each ADMA channel + that sends/receives data to/from AHUB must interface through an + ADMAIF channel. ADMA channel sending data to AHUB pairs with ADMAIF + Tx channel and ADMA channel receiving data from AHUB pairs with + ADMAIF Rx channel. + +maintainers: + - Jon Hunter <jonathanh@nvidia.com> + - Sameer Pujar <spujar@nvidia.com> + +properties: + $nodename: + pattern: "^admaif@[0-9a-f]*$" + + compatible: + oneOf: + - enum: + - nvidia,tegra210-admaif + - nvidia,tegra186-admaif + - items: + - const: nvidia,tegra194-admaif + - const: nvidia,tegra186-admaif + + reg: + maxItems: 1 + + dmas: true + + dma-names: true + +if: + properties: + compatible: + contains: + const: nvidia,tegra210-admaif + +then: + properties: + dmas: + description: + DMA channel specifiers, equally divided for Tx and Rx. + minItems: 1 + maxItems: 20 + dma-names: + items: + pattern: "^[rt]x(10|[1-9])$" + description: + Should be "rx1", "rx2" ... "rx10" for DMA Rx channel + Should be "tx1", "tx2" ... "tx10" for DMA Tx channel + minItems: 1 + maxItems: 20 + +else: + properties: + dmas: + description: + DMA channel specifiers, equally divided for Tx and Rx. + minItems: 1 + maxItems: 40 + dma-names: + items: + pattern: "^[rt]x(1[0-9]|[1-9]|20)$" + description: + Should be "rx1", "rx2" ... "rx20" for DMA Rx channel + Should be "tx1", "tx2" ... "tx20" for DMA Tx channel + minItems: 1 + maxItems: 40 + +required: + - compatible + - reg + - dmas + - dma-names + +examples: + - | + admaif@702d0000 { + compatible = "nvidia,tegra210-admaif"; + reg = <0x702d0000 0x800>; + dmas = <&adma 1>, <&adma 1>, + <&adma 2>, <&adma 2>, + <&adma 3>, <&adma 3>, + <&adma 4>, <&adma 4>, + <&adma 5>, <&adma 5>, + <&adma 6>, <&adma 6>, + <&adma 7>, <&adma 7>, + <&adma 8>, <&adma 8>, + <&adma 9>, <&adma 9>, + <&adma 10>, <&adma 10>; + dma-names = "rx1", "tx1", + "rx2", "tx2", + "rx3", "tx3", + "rx4", "tx4", + "rx5", "tx5", + "rx6", "tx6", + "rx7", "tx7", + "rx8", "tx8", + "rx9", "tx9", + "rx10", "tx10"; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml new file mode 100644 index 000000000000..44ee9d844ae0 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-ahub.yaml @@ -0,0 +1,136 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nvidia,tegra210-ahub.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Tegra210 AHUB Device Tree Bindings + +description: | + The Audio Hub (AHUB) comprises a collection of hardware accelerators + for audio pre-processing, post-processing and a programmable full + crossbar for routing audio data across these accelerators. It has + external interfaces such as I2S, DMIC, DSPK. It interfaces with ADMA + engine through ADMAIF. + +maintainers: + - Jon Hunter <jonathanh@nvidia.com> + - Sameer Pujar <spujar@nvidia.com> + +properties: + $nodename: + pattern: "^ahub@[0-9a-f]*$" + + compatible: + oneOf: + - enum: + - nvidia,tegra210-ahub + - nvidia,tegra186-ahub + - items: + - const: nvidia,tegra194-ahub + - const: nvidia,tegra186-ahub + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + const: ahub + + assigned-clocks: + maxItems: 1 + + assigned-clock-parents: + maxItems: 1 + + assigned-clock-rates: + maxItems: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + ranges: true + +required: + - compatible + - reg + - clocks + - clock-names + - assigned-clocks + - assigned-clock-parents + - "#address-cells" + - "#size-cells" + - ranges + +examples: + - | + #include<dt-bindings/clock/tegra210-car.h> + + ahub@702d0800 { + compatible = "nvidia,tegra210-ahub"; + reg = <0x702d0800 0x800>; + clocks = <&tegra_car TEGRA210_CLK_D_AUDIO>; + clock-names = "ahub"; + assigned-clocks = <&tegra_car TEGRA210_CLK_D_AUDIO>; + assigned-clock-parents = <&tegra_car TEGRA210_CLK_PLL_A_OUT0>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x702d0000 0x702d0000 0x0000e400>; + + // All AHUB child nodes below + admaif@702d0000 { + compatible = "nvidia,tegra210-admaif"; + reg = <0x702d0000 0x800>; + dmas = <&adma 1>, <&adma 1>, + <&adma 2>, <&adma 2>, + <&adma 3>, <&adma 3>, + <&adma 4>, <&adma 4>, + <&adma 5>, <&adma 5>, + <&adma 6>, <&adma 6>, + <&adma 7>, <&adma 7>, + <&adma 8>, <&adma 8>, + <&adma 9>, <&adma 9>, + <&adma 10>, <&adma 10>; + dma-names = "rx1", "tx1", + "rx2", "tx2", + "rx3", "tx3", + "rx4", "tx4", + "rx5", "tx5", + "rx6", "tx6", + "rx7", "tx7", + "rx8", "tx8", + "rx9", "tx9", + "rx10", "tx10"; + }; + + i2s@702d1000 { + compatible = "nvidia,tegra210-i2s"; + reg = <0x702d1000 0x100>; + clocks = <&tegra_car TEGRA210_CLK_I2S0>; + clock-names = "i2s"; + assigned-clocks = <&tegra_car TEGRA210_CLK_I2S0>; + assigned-clock-parents = <&tegra_car TEGRA210_CLK_PLL_A_OUT0>; + assigned-clock-rates = <1536000>; + sound-name-prefix = "I2S1"; + }; + + dmic@702d4000 { + compatible = "nvidia,tegra210-dmic"; + reg = <0x702d4000 0x100>; + clocks = <&tegra_car TEGRA210_CLK_DMIC1>; + clock-names = "dmic"; + assigned-clocks = <&tegra_car TEGRA210_CLK_DMIC1>; + assigned-clock-parents = <&tegra_car TEGRA210_CLK_PLL_A_OUT0>; + assigned-clock-rates = <3072000>; + sound-name-prefix = "DMIC1"; + }; + + // More child nodes to follow + }; + +... diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml new file mode 100644 index 000000000000..1c14e83f67c7 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-dmic.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nvidia,tegra210-dmic.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Tegra210 DMIC Controller Device Tree Bindings + +description: | + The Digital MIC (DMIC) Controller is used to interface with Pulse + Density Modulation (PDM) input devices. It converts PDM signals to + Pulse Coded Modulation (PCM) signals. DMIC can be viewed as a PDM + receiver. + +maintainers: + - Jon Hunter <jonathanh@nvidia.com> + - Sameer Pujar <spujar@nvidia.com> + +properties: + $nodename: + pattern: "^dmic@[0-9a-f]*$" + + compatible: + oneOf: + - const: nvidia,tegra210-dmic + - items: + - enum: + - nvidia,tegra194-dmic + - nvidia,tegra186-dmic + - const: nvidia,tegra210-dmic + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + const: dmic + + assigned-clocks: + maxItems: 1 + + assigned-clock-parents: + maxItems: 1 + + assigned-clock-rates: + maxItems: 1 + + sound-name-prefix: + pattern: "^DMIC[1-9]$" + allOf: + - $ref: /schemas/types.yaml#/definitions/string + description: + used as prefix for sink/source names of the component. Must be a + unique string among multiple instances of the same component. + The name can be "DMIC1" or "DMIC2" ... "DMICx", where x depends + on the maximum available instances on a Tegra SoC. + +required: + - compatible + - reg + - clocks + - clock-names + - assigned-clocks + - assigned-clock-parents + +examples: + - | + #include<dt-bindings/clock/tegra210-car.h> + + dmic@702d4000 { + compatible = "nvidia,tegra210-dmic"; + reg = <0x702d4000 0x100>; + clocks = <&tegra_car TEGRA210_CLK_DMIC1>; + clock-names = "dmic"; + assigned-clocks = <&tegra_car TEGRA210_CLK_DMIC1>; + assigned-clock-parents = <&tegra_car TEGRA210_CLK_PLL_A_OUT0>; + assigned-clock-rates = <3072000>; + sound-name-prefix = "DMIC1"; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml b/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml new file mode 100644 index 000000000000..795797001843 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra210-i2s.yaml @@ -0,0 +1,101 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nvidia,tegra210-i2s.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Tegra210 I2S Controller Device Tree Bindings + +description: | + The Inter-IC Sound (I2S) controller implements full-duplex, + bi-directional and single direction point-to-point serial + interfaces. It can interface with I2S compatible devices. + I2S controller can operate both in master and slave mode. + +maintainers: + - Jon Hunter <jonathanh@nvidia.com> + - Sameer Pujar <spujar@nvidia.com> + +properties: + $nodename: + pattern: "^i2s@[0-9a-f]*$" + + compatible: + oneOf: + - const: nvidia,tegra210-i2s + - items: + - enum: + - nvidia,tegra194-i2s + - nvidia,tegra186-i2s + - const: nvidia,tegra210-i2s + + reg: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 2 + items: + - description: I2S bit clock + - description: + Sync input clock, which can act as clock source to other I/O + modules in AHUB. The Tegra I2S driver sets this clock rate as + per bit clock rate. I/O module which wants to use this clock + as source, can mention this clock as parent in the DT bindings. + This is an optional clock entry, since it is only required when + some other I/O wants to reference from a particular I2Sx + instance. + + clock-names: + minItems: 1 + maxItems: 2 + items: + - const: i2s + - const: sync_input + + assigned-clocks: + minItems: 1 + maxItems: 2 + + assigned-clock-parents: + minItems: 1 + maxItems: 2 + + assigned-clock-rates: + minItems: 1 + maxItems: 2 + + sound-name-prefix: + pattern: "^I2S[1-9]$" + allOf: + - $ref: /schemas/types.yaml#/definitions/string + description: + Used as prefix for sink/source names of the component. Must be a + unique string among multiple instances of the same component. + The name can be "I2S1" or "I2S2" ... "I2Sx", where x depends + on the maximum available instances on a Tegra SoC. + +required: + - compatible + - reg + - clocks + - clock-names + - assigned-clocks + - assigned-clock-parents + +examples: + - | + #include<dt-bindings/clock/tegra210-car.h> + + i2s@702d1000 { + compatible = "nvidia,tegra210-i2s"; + reg = <0x702d1000 0x100>; + clocks = <&tegra_car TEGRA210_CLK_I2S0>; + clock-names = "i2s"; + assigned-clocks = <&tegra_car TEGRA210_CLK_I2S0>; + assigned-clock-parents = <&tegra_car TEGRA210_CLK_PLL_A_OUT0>; + assigned-clock-rates = <1536000>; + sound-name-prefix = "I2S1"; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/qcom,q6asm.txt b/Documentation/devicetree/bindings/sound/qcom,q6asm.txt index 6b9a88d0ea3f..8c4883becae9 100644 --- a/Documentation/devicetree/bindings/sound/qcom,q6asm.txt +++ b/Documentation/devicetree/bindings/sound/qcom,q6asm.txt @@ -39,9 +39,9 @@ configuration of each dai. Must contain the following properties. Usage: Required for Compress offload dais Value type: <u32> Definition: Specifies the direction of the dai stream - 0 for both tx and rx - 1 for only tx (Capture/Encode) - 2 for only rx (Playback/Decode) + Q6ASM_DAI_TX_RX (0) for both tx and rx + Q6ASM_DAI_TX (1) for only tx (Capture/Encode) + Q6ASM_DAI_RX (2) for only rx (Playback/Decode) - is-compress-dai: Usage: Required for Compress offload dais @@ -50,6 +50,7 @@ configuration of each dai. Must contain the following properties. = EXAMPLE +#include <dt-bindings/sound/qcom,q6asm.h> apr-service@7 { compatible = "qcom,q6asm"; @@ -62,7 +63,7 @@ apr-service@7 { dai@0 { reg = <0>; - direction = <2>; + direction = <Q6ASM_DAI_RX>; is-compress-dai; }; }; diff --git a/Documentation/devicetree/bindings/sound/renesas,fsi.yaml b/Documentation/devicetree/bindings/sound/renesas,fsi.yaml index 8a4406be387a..0dd3f7361399 100644 --- a/Documentation/devicetree/bindings/sound/renesas,fsi.yaml +++ b/Documentation/devicetree/bindings/sound/renesas,fsi.yaml @@ -43,30 +43,19 @@ properties: '#sound-dai-cells': const: 1 - fsia,spdif-connection: +patternProperties: + "^fsi(a|b),spdif-connection$": $ref: /schemas/types.yaml#/definitions/flag description: FSI is connected by S/PDIF - fsia,stream-mode-support: + "^fsi(a|b),stream-mode-support$": $ref: /schemas/types.yaml#/definitions/flag description: FSI supports 16bit stream mode - fsia,use-internal-clock: + "^fsi(a|b),use-internal-clock$": $ref: /schemas/types.yaml#/definitions/flag description: FSI uses internal clock when master mode - fsib,spdif-connection: - $ref: /schemas/types.yaml#/definitions/flag - description: same as fsia - - fsib,stream-mode-support: - $ref: /schemas/types.yaml#/definitions/flag - description: same as fsia - - fsib,use-internal-clock: - $ref: /schemas/types.yaml#/definitions/flag - description: same as fsia - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt index 1596f0d1e2fe..b39743d3f7c4 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt +++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt @@ -271,6 +271,7 @@ Required properties: - "renesas,rcar_sound-r8a774a1" (RZ/G2M) - "renesas,rcar_sound-r8a774b1" (RZ/G2N) - "renesas,rcar_sound-r8a774c0" (RZ/G2E) + - "renesas,rcar_sound-r8a774e1" (RZ/G2H) - "renesas,rcar_sound-r8a7778" (R-Car M1A) - "renesas,rcar_sound-r8a7779" (R-Car H1) - "renesas,rcar_sound-r8a7790" (R-Car H2) diff --git a/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.txt b/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.txt deleted file mode 100644 index 1ecd75d2032a..000000000000 --- a/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.txt +++ /dev/null @@ -1,28 +0,0 @@ -* Rockchip Rk3328 internal codec - -Required properties: - -- compatible: "rockchip,rk3328-codec" -- reg: physical base address of the controller and length of memory mapped - region. -- rockchip,grf: the phandle of the syscon node for GRF register. -- clocks: a list of phandle + clock-specifer pairs, one for each entry in clock-names. -- clock-names: should be "pclk". -- spk-depop-time-ms: speak depop time msec. - -Optional properties: - -- mute-gpios: GPIO specifier for external line driver control (typically the - dedicated GPIO_MUTE pin) - -Example for rk3328 internal codec: - -codec: codec@ff410000 { - compatible = "rockchip,rk3328-codec"; - reg = <0x0 0xff410000 0x0 0x1000>; - rockchip,grf = <&grf>; - clocks = <&cru PCLK_ACODEC>; - clock-names = "pclk"; - mute-gpios = <&grf_gpio 0 GPIO_ACTIVE_LOW>; - spk-depop-time-ms = 100; -}; diff --git a/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.yaml b/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.yaml new file mode 100644 index 000000000000..5b85ad5e4834 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.yaml @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/rockchip,rk3328-codec.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip rk3328 internal codec + +maintainers: + - Heiko Stuebner <heiko@sntech.de> + +properties: + compatible: + const: rockchip,rk3328-codec + + reg: + maxItems: 1 + + clocks: + items: + - description: clock for audio codec + - description: clock for I2S master clock + + clock-names: + items: + - const: pclk + - const: mclk + + rockchip,grf: + $ref: /schemas/types.yaml#/definitions/phandle + description: + The phandle of the syscon node for the GRF register. + + spk-depop-time-ms: + default: 200 + description: + Speaker depop time in msec. + + mute-gpios: + maxItems: 1 + description: + GPIO specifier for external line driver control (typically the + dedicated GPIO_MUTE pin) + + "#sound-dai-cells": + const: 0 + +required: + - compatible + - reg + - clocks + - clock-names + - rockchip,grf + - "#sound-dai-cells" + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/clock/rk3328-cru.h> + codec: codec@ff410000 { + compatible = "rockchip,rk3328-codec"; + reg = <0xff410000 0x1000>; + clocks = <&cru PCLK_ACODECPHY>, <&cru SCLK_I2S1>; + clock-names = "pclk", "mclk"; + rockchip,grf = <&grf>; + mute-gpios = <&grf_gpio 0 GPIO_ACTIVE_LOW>; + spk-depop-time-ms = <100>; + #sound-dai-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/sound/rohm,bd28623.txt b/Documentation/devicetree/bindings/sound/rohm,bd28623.txt deleted file mode 100644 index d84557c2686e..000000000000 --- a/Documentation/devicetree/bindings/sound/rohm,bd28623.txt +++ /dev/null @@ -1,29 +0,0 @@ -ROHM BD28623MUV Class D speaker amplifier for digital input - -This codec does not have any control buses such as I2C, it detect format and -rate of I2S signal automatically. It has two signals that can be connected -to GPIOs: reset and mute. - -Required properties: -- compatible : should be "rohm,bd28623" -- #sound-dai-cells: should be 0. -- VCCA-supply : regulator phandle for the VCCA supply -- VCCP1-supply : regulator phandle for the VCCP1 supply -- VCCP2-supply : regulator phandle for the VCCP2 supply - -Optional properties: -- reset-gpios : GPIO specifier for the active low reset line -- mute-gpios : GPIO specifier for the active low mute line - -Example: - - codec { - compatible = "rohm,bd28623"; - #sound-dai-cells = <0>; - - VCCA-supply = <&vcc_reg>; - VCCP1-supply = <&vcc_reg>; - VCCP2-supply = <&vcc_reg>; - reset-gpios = <&gpio 0 GPIO_ACTIVE_LOW>; - mute-gpios = <&gpio 1 GPIO_ACTIVE_LOW>; - }; diff --git a/Documentation/devicetree/bindings/sound/rohm,bd28623.yaml b/Documentation/devicetree/bindings/sound/rohm,bd28623.yaml new file mode 100644 index 000000000000..859ce64da152 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rohm,bd28623.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/rohm,bd28623.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ROHM BD28623MUV Class D speaker amplifier for digital input + +description: + This codec does not have any control buses such as I2C, it detect + format and rate of I2S signal automatically. It has two signals + that can be connected to GPIOs reset and mute. + +maintainers: + - Katsuhiro Suzuki <katsuhiro@katsuster.net> + +properties: + compatible: + const: rohm,bd28623 + + "#sound-dai-cells": + const: 0 + + VCCA-supply: + description: + regulator phandle for the VCCA (for analog) power supply + + VCCP1-supply: + description: + regulator phandle for the VCCP1 (for ch1) power supply + + VCCP2-supply: + description: + regulator phandle for the VCCP2 (for ch2) power supply + + reset-gpios: + maxItems: 1 + description: + GPIO specifier for the active low reset line + + mute-gpios: + maxItems: 1 + description: + GPIO specifier for the active low mute line + +required: + - compatible + - VCCA-supply + - VCCP1-supply + - VCCP2-supply + - "#sound-dai-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + codec { + compatible = "rohm,bd28623"; + #sound-dai-cells = <0>; + + VCCA-supply = <&vcc_reg>; + VCCP1-supply = <&vcc_reg>; + VCCP2-supply = <&vcc_reg>; + reset-gpios = <&gpio 0 GPIO_ACTIVE_LOW>; + mute-gpios = <&gpio 1 GPIO_ACTIVE_LOW>; + }; diff --git a/Documentation/devicetree/bindings/sound/samsung,aries-wm8994.yaml b/Documentation/devicetree/bindings/sound/samsung,aries-wm8994.yaml new file mode 100644 index 000000000000..902a0b66628e --- /dev/null +++ b/Documentation/devicetree/bindings/sound/samsung,aries-wm8994.yaml @@ -0,0 +1,147 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/samsung,aries-wm8994.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung Aries audio complex with WM8994 codec + +maintainers: + - Jonathan Bakker <xc-racer2@live.ca> + +properties: + compatible: + oneOf: + - const: samsung,aries-wm8994 + description: With FM radio and modem master + + - const: samsung,fascinate4g-wm8994 + description: Without FM radio and modem slave + + model: + $ref: /schemas/types.yaml#/definitions/string + description: The user-visible name of this sound complex. + + cpu: + type: object + properties: + sound-dai: + minItems: 2 + maxItems: 2 + $ref: /schemas/types.yaml#/definitions/phandle-array + description: | + phandles to the I2S controller and bluetooth codec, + in that order + + codec: + type: object + properties: + sound-dai: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: phandle to the WM8994 CODEC + + samsung,audio-routing: + $ref: /schemas/types.yaml#/definitions/non-unique-string-array + description: | + List of the connections between audio + components; each entry is a pair of strings, the first being the + connection's sink, the second being the connection's source; + valid names for sources and sinks are the WM8994's pins (as + documented in its binding), and the jacks on the board - + For samsung,aries-wm8994: HP, SPK, RCV, LINE, Main Mic, Headset Mic, + or FM In + For samsung,fascinate4g-wm8994: HP, SPK, RCV, LINE, Main Mic, + or HeadsetMic + + extcon: + description: Extcon phandle for dock detection + + main-micbias-supply: + description: Supply for the micbias on the main mic + + headset-micbias-supply: + description: Supply for the micbias on the headset mic + + earpath-sel-gpios: + description: GPIO for switching between tv-out and mic paths + + headset-detect-gpios: + description: GPIO for detection of headset insertion + + headset-key-gpios: + description: GPIO for detection of headset key press + + io-channels: + maxItems: 1 + description: IO channel to read micbias voltage for headset detection + + io-channel-names: + const: headset-detect + +required: + - compatible + - model + - cpu + - codec + - samsung,audio-routing + - extcon + - main-micbias-supply + - headset-micbias-supply + - earpath-sel-gpios + - headset-detect-gpios + - headset-key-gpios + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + sound { + compatible = "samsung,fascinate4g-wm8994"; + + model = "Fascinate4G"; + + extcon = <&fsa9480>; + + main-micbias-supply = <&main_micbias_reg>; + headset-micbias-supply = <&headset_micbias_reg>; + + earpath-sel-gpios = <&gpj2 6 GPIO_ACTIVE_HIGH>; + + io-channels = <&adc 3>; + io-channel-names = "headset-detect"; + headset-detect-gpios = <&gph0 6 GPIO_ACTIVE_HIGH>; + headset-key-gpios = <&gph3 6 GPIO_ACTIVE_HIGH>; + + samsung,audio-routing = + "HP", "HPOUT1L", + "HP", "HPOUT1R", + + "SPK", "SPKOUTLN", + "SPK", "SPKOUTLP", + + "RCV", "HPOUT2N", + "RCV", "HPOUT2P", + + "LINE", "LINEOUT2N", + "LINE", "LINEOUT2P", + + "IN1LP", "Main Mic", + "IN1LN", "Main Mic", + + "IN1RP", "Headset Mic", + "IN1RN", "Headset Mic"; + + pinctrl-names = "default"; + pinctrl-0 = <&headset_det &earpath_sel>; + + cpu { + sound-dai = <&i2s0>, <&bt_codec>; + }; + + codec { + sound-dai = <&wm8994>; + }; + }; + diff --git a/Documentation/devicetree/bindings/sound/samsung,midas-audio.yaml b/Documentation/devicetree/bindings/sound/samsung,midas-audio.yaml new file mode 100644 index 000000000000..1c755de686f7 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/samsung,midas-audio.yaml @@ -0,0 +1,108 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/samsung,midas-audio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung Midas audio complex with WM1811 codec + +maintainers: + - Sylwester Nawrocki <s.nawrocki@samsung.com> + +properties: + compatible: + const: samsung,midas-audio + + model: + $ref: /schemas/types.yaml#/definitions/string + description: The user-visible name of this sound complex. + + cpu: + type: object + properties: + sound-dai: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to the I2S controller + required: + - sound-dai + + codec: + type: object + properties: + sound-dai: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to the WM1811 CODEC + required: + - sound-dai + + samsung,audio-routing: + $ref: /schemas/types.yaml#/definitions/non-unique-string-array + description: | + List of the connections between audio components; each entry is + a pair of strings, the first being the connection's sink, the second + being the connection's source; valid names for sources and sinks are + the WM1811's pins (as documented in its binding), and the jacks + on the board: HP, SPK, Main Mic, Sub Mic, Headset Mic. + + mic-bias-supply: + description: Supply for the micbias on the Main microphone + + submic-bias-supply: + description: Supply for the micbias on the Sub microphone + + fm-sel-gpios: + description: GPIO pin for FM selection + + lineout-sel-gpios: + description: GPIO pin for line out selection + +required: + - compatible + - model + - cpu + - codec + - samsung,audio-routing + - mic-bias-supply + - submic-bias-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + sound { + compatible = "samsung,midas-audio"; + model = "Midas"; + + fm-sel-gpios = <&gpaa0 3 GPIO_ACTIVE_HIGH>; + + mic-bias-supply = <&mic_bias_reg>; + submic-bias-supply = <&submic_bias_reg>; + + samsung,audio-routing = + "HP", "HPOUT1L", + "HP", "HPOUT1R", + + "SPK", "SPKOUTLN", + "SPK", "SPKOUTLP", + "SPK", "SPKOUTRN", + "SPK", "SPKOUTRP", + + "RCV", "HPOUT2N", + "RCV", "HPOUT2P", + + "IN1LP", "Main Mic", + "IN1LN", "Main Mic", + "IN1RP", "Sub Mic", + "IN1LP", "Sub Mic"; + + cpu { + sound-dai = <&i2s0>; + }; + + codec { + sound-dai = <&wm1811>; + }; + + }; diff --git a/Documentation/devicetree/bindings/sound/sgtl5000.txt b/Documentation/devicetree/bindings/sound/sgtl5000.txt deleted file mode 100644 index 9d9ff5184939..000000000000 --- a/Documentation/devicetree/bindings/sound/sgtl5000.txt +++ /dev/null @@ -1,60 +0,0 @@ -* Freescale SGTL5000 Stereo Codec - -Required properties: -- compatible : "fsl,sgtl5000". - -- reg : the I2C address of the device - -- #sound-dai-cells: must be equal to 0 - -- clocks : the clock provider of SYS_MCLK - -- VDDA-supply : the regulator provider of VDDA - -- VDDIO-supply: the regulator provider of VDDIO - -Optional properties: - -- VDDD-supply : the regulator provider of VDDD - -- micbias-resistor-k-ohms : the bias resistor to be used in kOhms - The resistor can take values of 2k, 4k or 8k. - If set to 0 it will be off. - If this node is not mentioned or if the value is unknown, then - micbias resistor is set to 4K. - -- micbias-voltage-m-volts : the bias voltage to be used in mVolts - The voltage can take values from 1.25V to 3V by 250mV steps - If this node is not mentioned or the value is unknown, then - the value is set to 1.25V. - -- lrclk-strength: the LRCLK pad strength. Possible values are: -0, 1, 2 and 3 as per the table below: - -VDDIO 1.8V 2.5V 3.3V -0 = Disable -1 = 1.66 mA 2.87 mA 4.02 mA -2 = 3.33 mA 5.74 mA 8.03 mA -3 = 4.99 mA 8.61 mA 12.05 mA - -- sclk-strength: the SCLK pad strength. Possible values are: -0, 1, 2 and 3 as per the table below: - -VDDIO 1.8V 2.5V 3.3V -0 = Disable -1 = 1.66 mA 2.87 mA 4.02 mA -2 = 3.33 mA 5.74 mA 8.03 mA -3 = 4.99 mA 8.61 mA 12.05 mA - -Example: - -sgtl5000: codec@a { - compatible = "fsl,sgtl5000"; - reg = <0x0a>; - #sound-dai-cells = <0>; - clocks = <&clks 150>; - micbias-resistor-k-ohms = <2>; - micbias-voltage-m-volts = <2250>; - VDDA-supply = <®_3p3v>; - VDDIO-supply = <®_3p3v>; -}; diff --git a/Documentation/devicetree/bindings/sound/sgtl5000.yaml b/Documentation/devicetree/bindings/sound/sgtl5000.yaml new file mode 100644 index 000000000000..4f29b63c54d3 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/sgtl5000.yaml @@ -0,0 +1,103 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/sgtl5000.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale SGTL5000 Stereo Codec + +maintainers: + - Fabio Estevam <festevam@gmail.com> + +properties: + compatible: + const: fsl,sgtl5000 + + reg: + maxItems: 1 + + "#sound-dai-cells": + const: 0 + + clocks: + items: + - description: the clock provider of SYS_MCLK + + VDDA-supply: + description: the regulator provider of VDDA + + VDDIO-supply: + description: the regulator provider of VDDIO + + VDDD-supply: + description: the regulator provider of VDDD + + micbias-resistor-k-ohms: + description: The bias resistor to be used in kOhms. The resistor can take + values of 2k, 4k or 8k. If set to 0 it will be off. If this node is not + mentioned or if the value is unknown, then micbias resistor is set to + 4k. + $ref: "/schemas/types.yaml#/definitions/uint32" + enum: [ 0, 2, 4, 8 ] + + micbias-voltage-m-volts: + description: The bias voltage to be used in mVolts. The voltage can take + values from 1.25V to 3V by 250mV steps. If this node is not mentioned + or the value is unknown, then the value is set to 1.25V. + $ref: "/schemas/types.yaml#/definitions/uint32" + enum: [ 1250, 1500, 1750, 2000, 2250, 2500, 2750, 3000 ] + + lrclk-strength: + description: | + The LRCLK pad strength. Possible values are: 0, 1, 2 and 3 as per the + table below: + + VDDIO 1.8V 2.5V 3.3V + 0 = Disable + 1 = 1.66 mA 2.87 mA 4.02 mA + 2 = 3.33 mA 5.74 mA 8.03 mA + 3 = 4.99 mA 8.61 mA 12.05 mA + $ref: "/schemas/types.yaml#/definitions/uint32" + enum: [ 0, 1, 2, 3 ] + + sclk-strength: + description: | + The SCLK pad strength. Possible values are: 0, 1, 2 and 3 as per the + table below: + + VDDIO 1.8V 2.5V 3.3V + 0 = Disable + 1 = 1.66 mA 2.87 mA 4.02 mA + 2 = 3.33 mA 5.74 mA 8.03 mA + 3 = 4.99 mA 8.61 mA 12.05 mA + $ref: "/schemas/types.yaml#/definitions/uint32" + enum: [ 0, 1, 2, 3 ] + +required: + - compatible + - reg + - "#sound-dai-cells" + - clocks + - VDDA-supply + - VDDIO-supply + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + codec@a { + compatible = "fsl,sgtl5000"; + reg = <0x0a>; + #sound-dai-cells = <0>; + clocks = <&clks 150>; + micbias-resistor-k-ohms = <2>; + micbias-voltage-m-volts = <2250>; + VDDA-supply = <®_3p3v>; + VDDIO-supply = <®_3p3v>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/sound/simple-card.yaml b/Documentation/devicetree/bindings/sound/simple-card.yaml index 8132d0c0f00a..35e669020296 100644 --- a/Documentation/devicetree/bindings/sound/simple-card.yaml +++ b/Documentation/devicetree/bindings/sound/simple-card.yaml @@ -378,6 +378,8 @@ examples: - | sound { compatible = "simple-audio-card"; + #address-cells = <1>; + #size-cells = <0>; simple-audio-card,name = "rsnd-ak4643"; simple-audio-card,format = "left_j"; @@ -391,10 +393,12 @@ examples: "ak4642 Playback", "DAI1 Playback"; dpcmcpu: simple-audio-card,cpu@0 { + reg = <0>; sound-dai = <&rcar_sound 0>; }; simple-audio-card,cpu@1 { + reg = <1>; sound-dai = <&rcar_sound 1>; }; @@ -418,6 +422,8 @@ examples: - | sound { compatible = "simple-audio-card"; + #address-cells = <1>; + #size-cells = <0>; simple-audio-card,routing = "pcm3168a Playback", "DAI1 Playback", @@ -426,6 +432,7 @@ examples: "pcm3168a Playback", "DAI4 Playback"; simple-audio-card,dai-link@0 { + reg = <0>; format = "left_j"; bitclock-master = <&sndcpu0>; frame-master = <&sndcpu0>; @@ -439,22 +446,23 @@ examples: }; simple-audio-card,dai-link@1 { + reg = <1>; format = "i2s"; bitclock-master = <&sndcpu1>; frame-master = <&sndcpu1>; convert-channels = <8>; /* TDM Split */ - sndcpu1: cpu@0 { + sndcpu1: cpu0 { sound-dai = <&rcar_sound 1>; }; - cpu@1 { + cpu1 { sound-dai = <&rcar_sound 2>; }; - cpu@2 { + cpu2 { sound-dai = <&rcar_sound 3>; }; - cpu@3 { + cpu3 { sound-dai = <&rcar_sound 4>; }; codec { @@ -466,6 +474,7 @@ examples: }; simple-audio-card,dai-link@2 { + reg = <2>; format = "i2s"; bitclock-master = <&sndcpu2>; frame-master = <&sndcpu2>; diff --git a/Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml b/Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml new file mode 100644 index 000000000000..4987eb91f2ab --- /dev/null +++ b/Documentation/devicetree/bindings/sound/socionext,uniphier-aio.yaml @@ -0,0 +1,81 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/socionext,uniphier-aio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: UniPhier AIO audio system + +maintainers: + - <alsa-devel@alsa-project.org> + +properties: + compatible: + enum: + - socionext,uniphier-ld11-aio + - socionext,uniphier-ld20-aio + - socionext,uniphier-pxs2-aio + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clock-names: + const: aio + + clocks: + maxItems: 1 + + reset-names: + const: aio + + resets: + maxItems: 1 + + socionext,syscon: + description: | + Specifies a phandle to soc-glue, which is used for changing mode of S/PDIF + signal pin to output from Hi-Z. This property is optional if you use I2S + signal pins only. + $ref: "/schemas/types.yaml#/definitions/phandle" + + "#sound-dai-cells": + const: 1 + +patternProperties: + "^port@[0-9]$": + type: object + properties: + endpoint: true + required: + - endpoint + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + - clock-names + - clocks + - reset-names + - resets + - "#sound-dai-cells" + +examples: + - | + audio@56000000 { + compatible = "socionext,uniphier-ld20-aio"; + reg = <0x56000000 0x80000>; + interrupts = <0 144 4>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_aout>; + clock-names = "aio"; + clocks = <&sys_clk 40>; + reset-names = "aio"; + resets = <&sys_rst 40>; + #sound-dai-cells = <1>; + socionext,syscon = <&soc_glue>; + }; diff --git a/Documentation/devicetree/bindings/sound/socionext,uniphier-evea.yaml b/Documentation/devicetree/bindings/sound/socionext,uniphier-evea.yaml new file mode 100644 index 000000000000..228168f685cf --- /dev/null +++ b/Documentation/devicetree/bindings/sound/socionext,uniphier-evea.yaml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/socionext,uniphier-evea.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: UniPhier EVEA SoC-internal sound codec + +maintainers: + - <alsa-devel@alsa-project.org> + +properties: + compatible: + const: socionext,uniphier-evea + + reg: + maxItems: 1 + + clock-names: + items: + - const: evea + - const: exiv + + clocks: + minItems: 2 + maxItems: 2 + + reset-names: + items: + - const: evea + - const: exiv + - const: adamv + + resets: + minItems: 3 + maxItems: 3 + + "#sound-dai-cells": + const: 1 + +patternProperties: + "^port@[0-9]$": + type: object + properties: + endpoint: true + required: + - endpoint + +additionalProperties: false + +required: + - compatible + - reg + - clock-names + - clocks + - reset-names + - resets + - "#sound-dai-cells" + +examples: + - | + codec@57900000 { + compatible = "socionext,uniphier-evea"; + reg = <0x57900000 0x1000>; + clock-names = "evea", "exiv"; + clocks = <&sys_clk 41>, <&sys_clk 42>; + reset-names = "evea", "exiv", "adamv"; + resets = <&sys_rst 41>, <&sys_rst 42>, <&adamv_rst 0>; + #sound-dai-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt b/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt index 4d51f3f5ea98..a6ffcdec6f6a 100644 --- a/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt +++ b/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt @@ -5,7 +5,7 @@ codec or external codecs. sti sound drivers allows to expose sti SoC audio interface through the generic ASoC simple card. For details about sound card declaration please refer to -Documentation/devicetree/bindings/sound/simple-card.txt. +Documentation/devicetree/bindings/sound/simple-card.yaml. 1) sti-uniperiph-dai: audio dai device. --------------------------------------- diff --git a/Documentation/devicetree/bindings/sound/tas2552.txt b/Documentation/devicetree/bindings/sound/tas2552.txt index 2d71eb05c1d3..a7eecad83db1 100644 --- a/Documentation/devicetree/bindings/sound/tas2552.txt +++ b/Documentation/devicetree/bindings/sound/tas2552.txt @@ -33,4 +33,4 @@ tas2552: tas2552@41 { }; For more product information please see the link below: -http://www.ti.com/product/TAS2552 +https://www.ti.com/product/TAS2552 diff --git a/Documentation/devicetree/bindings/sound/tas2562.txt b/Documentation/devicetree/bindings/sound/tas2562.txt index 94796b547184..dc6d7362ded7 100644 --- a/Documentation/devicetree/bindings/sound/tas2562.txt +++ b/Documentation/devicetree/bindings/sound/tas2562.txt @@ -11,12 +11,14 @@ Required properties: - compatible: - Should contain "ti,tas2562", "ti,tas2563". - reg: - The i2c address. Should be 0x4c, 0x4d, 0x4e or 0x4f. - ti,imon-slot-no:- TDM TX current sense time slot. + - ti,vmon-slot-no:- TDM TX voltage sense time slot. This slot must always be + greater then ti,imon-slot-no. Optional properties: - interrupt-parent: phandle to the interrupt controller which provides the interrupt. - interrupts: (GPIO) interrupt to which the chip is connected. -- shut-down: GPIO used to control the state of the device. +- shut-down-gpio: GPIO used to control the state of the device. Examples: tas2562@4c { @@ -28,7 +30,8 @@ tas2562@4c { interrupt-parent = <&gpio1>; interrupts = <14>; - shut-down = <&gpio1 15 0>; + shut-down-gpio = <&gpio1 15 0>; ti,imon-slot-no = <0>; + ti,vmon-slot-no = <1>; }; diff --git a/Documentation/devicetree/bindings/sound/tas2562.yaml b/Documentation/devicetree/bindings/sound/tas2562.yaml new file mode 100644 index 000000000000..8d75a798740b --- /dev/null +++ b/Documentation/devicetree/bindings/sound/tas2562.yaml @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2019 Texas Instruments Incorporated +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/sound/tas2562.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Texas Instruments TAS2562 Smart PA + +maintainers: + - Dan Murphy <dmurphy@ti.com> + +description: | + The TAS2562 is a mono, digital input Class-D audio amplifier optimized for + efficiently driving high peak power into small loudspeakers. + Integrated speaker voltage and current sense provides for + real time monitoring of loudspeaker behavior. + +properties: + compatible: + enum: + - ti,tas2562 + - ti,tas2563 + + reg: + maxItems: 1 + description: | + I2C address of the device can be one of these 0x4c, 0x4d, 0x4e or 0x4f + + shut-down-gpios: + description: GPIO used to control the state of the device. + deprecated: true + + shutdown-gpios: + description: GPIO used to control the state of the device. + + interrupts: + maxItems: 1 + + ti,imon-slot-no: + $ref: /schemas/types.yaml#/definitions/uint32 + description: TDM TX current sense time slot. + + '#sound-dai-cells': + const: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + codec: codec@4c { + compatible = "ti,tas2562"; + reg = <0x4c>; + #sound-dai-cells = <1>; + interrupt-parent = <&gpio1>; + interrupts = <14>; + shutdown-gpios = <&gpio1 15 0>; + ti,imon-slot-no = <0>; + }; + }; + diff --git a/Documentation/devicetree/bindings/sound/tas2770.txt b/Documentation/devicetree/bindings/sound/tas2770.txt deleted file mode 100644 index ede6bb3d9637..000000000000 --- a/Documentation/devicetree/bindings/sound/tas2770.txt +++ /dev/null @@ -1,37 +0,0 @@ -Texas Instruments TAS2770 Smart PA - -The TAS2770 is a mono, digital input Class-D audio amplifier optimized for -efficiently driving high peak power into small loudspeakers. -Integrated speaker voltage and current sense provides for -real time monitoring of loudspeaker behavior. - -Required properties: - - - compatible: - Should contain "ti,tas2770". - - reg: - The i2c address. Should contain <0x4c>, <0x4d>,<0x4e>, or <0x4f>. - - #address-cells - Should be <1>. - - #size-cells - Should be <0>. - - ti,asi-format: - Sets TDM RX capture edge. 0->Rising; 1->Falling. - - ti,imon-slot-no:- TDM TX current sense time slot. - - ti,vmon-slot-no:- TDM TX voltage sense time slot. - -Optional properties: - -- interrupt-parent: the phandle to the interrupt controller which provides - the interrupt. -- interrupts: interrupt specification for data-ready. - -Examples: - - tas2770@4c { - compatible = "ti,tas2770"; - reg = <0x4c>; - #address-cells = <1>; - #size-cells = <0>; - interrupt-parent = <&msm_gpio>; - interrupts = <97 0>; - ti,asi-format = <0>; - ti,imon-slot-no = <0>; - ti,vmon-slot-no = <2>; - }; - diff --git a/Documentation/devicetree/bindings/sound/tas2770.yaml b/Documentation/devicetree/bindings/sound/tas2770.yaml new file mode 100644 index 000000000000..8192450d72dc --- /dev/null +++ b/Documentation/devicetree/bindings/sound/tas2770.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2019-20 Texas Instruments Incorporated +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/sound/tas2770.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Texas Instruments TAS2770 Smart PA + +maintainers: + - Shi Fu <shifu0704@thundersoft.com> + +description: | + The TAS2770 is a mono, digital input Class-D audio amplifier optimized for + efficiently driving high peak power into small loudspeakers. + Integrated speaker voltage and current sense provides for + real time monitoring of loudspeaker behavior. + +properties: + compatible: + enum: + - ti,tas2770 + + reg: + maxItems: 1 + description: | + I2C address of the device can be one of these 0x4c, 0x4d, 0x4e or 0x4f + + reset-gpio: + description: GPIO used to reset the device. + + interrupts: + maxItems: 1 + + ti,imon-slot-no: + $ref: /schemas/types.yaml#/definitions/uint32 + description: TDM TX current sense time slot. + + ti,vmon-slot-no: + $ref: /schemas/types.yaml#/definitions/uint32 + description: TDM TX voltage sense time slot. + + ti,asi-format: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Sets TDM RX capture edge. + enum: + - 0 # Rising edge + - 1 # Falling edge + + '#sound-dai-cells': + const: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + codec: codec@4c { + compatible = "ti,tas2770"; + reg = <0x4c>; + #sound-dai-cells = <1>; + interrupt-parent = <&gpio1>; + interrupts = <14>; + reset-gpio = <&gpio1 15 0>; + ti,imon-slot-no = <0>; + ti,vmon-slot-no = <2>; + }; + }; + diff --git a/Documentation/devicetree/bindings/sound/tas5720.txt b/Documentation/devicetree/bindings/sound/tas5720.txt index 7481653fe8e3..df99ca9451b0 100644 --- a/Documentation/devicetree/bindings/sound/tas5720.txt +++ b/Documentation/devicetree/bindings/sound/tas5720.txt @@ -4,9 +4,9 @@ The TAS5720 serial control bus communicates through the I2C protocol only. The serial bus is also used for periodic codec fault checking/reporting during audio playback. For more product information please see the links below: -http://www.ti.com/product/TAS5720L -http://www.ti.com/product/TAS5720M -http://www.ti.com/product/TAS5722L +https://www.ti.com/product/TAS5720L +https://www.ti.com/product/TAS5720M +https://www.ti.com/product/TAS5722L Required properties: diff --git a/Documentation/devicetree/bindings/sound/ti,j721e-cpb-audio.yaml b/Documentation/devicetree/bindings/sound/ti,j721e-cpb-audio.yaml new file mode 100644 index 000000000000..6f2be6503401 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ti,j721e-cpb-audio.yaml @@ -0,0 +1,95 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/ti,j721e-cpb-audio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments J721e Common Processor Board Audio Support + +maintainers: + - Peter Ujfalusi <peter.ujfalusi@ti.com> + +description: | + The audio support on the board is using pcm3168a codec connected to McASP10 + serializers in parallel setup. + The pcm3168a SCKI clock is sourced from j721e AUDIO_REFCLK2 pin. + In order to support 48KHz and 44.1KHz family of sampling rates the parent + clock for AUDIO_REFCLK2 needs to be changed between PLL4 (for 48KHz) and + PLL15 (for 44.1KHz). The same PLLs are used for McASP10's AUXCLK clock via + different HSDIVIDER. + + Clocking setup for 48KHz family: + PLL4 ---> PLL4_HSDIV0 ---> MCASP10_AUXCLK ---> McASP10.auxclk + |-> PLL4_HSDIV2 ---> AUDIO_REFCLK2 ---> pcm3168a.SCKI + + Clocking setup for 44.1KHz family: + PLL15 ---> PLL15_HSDIV0 ---> MCASP10_AUXCLK ---> McASP10.auxclk + |-> PLL15_HSDIV2 ---> AUDIO_REFCLK2 ---> pcm3168a.SCKI + +properties: + compatible: + items: + - const: ti,j721e-cpb-audio + + model: + $ref: /schemas/types.yaml#/definitions/string + description: User specified audio sound card name + + ti,cpb-mcasp: + description: phandle to McASP used on CPB + allOf: + - $ref: /schemas/types.yaml#/definitions/phandle + + ti,cpb-codec: + description: phandle to the pcm3168a codec used on the CPB + allOf: + - $ref: /schemas/types.yaml#/definitions/phandle + + clocks: + items: + - description: AUXCLK clock for McASP used by CPB audio + - description: Parent for CPB_McASP auxclk (for 48KHz) + - description: Parent for CPB_McASP auxclk (for 44.1KHz) + - description: SCKI clock for the pcm3168a codec on CPB + - description: Parent for CPB_SCKI clock (for 48KHz) + - description: Parent for CPB_SCKI clock (for 44.1KHz) + + clock-names: + items: + - const: cpb-mcasp-auxclk + - const: cpb-mcasp-auxclk-48000 + - const: cpb-mcasp-auxclk-44100 + - const: cpb-codec-scki + - const: cpb-codec-scki-48000 + - const: cpb-codec-scki-44100 + +required: + - compatible + - model + - ti,cpb-mcasp + - ti,cpb-codec + - clocks + - clock-names + +additionalProperties: false + +examples: + - |+ + sound { + compatible = "ti,j721e-cpb-audio"; + model = "j721e-cpb"; + + status = "okay"; + + ti,cpb-mcasp = <&mcasp10>; + ti,cpb-codec = <&pcm3168a_1>; + + clocks = <&k3_clks 184 1>, + <&k3_clks 184 2>, <&k3_clks 184 4>, + <&k3_clks 157 371>, + <&k3_clks 157 400>, <&k3_clks 157 401>; + clock-names = "cpb-mcasp-auxclk", + "cpb-mcasp-auxclk-48000", "cpb-mcasp-auxclk-44100", + "cpb-codec-scki", + "cpb-codec-scki-48000", "cpb-codec-scki-44100"; + }; diff --git a/Documentation/devicetree/bindings/sound/ti,j721e-cpb-ivi-audio.yaml b/Documentation/devicetree/bindings/sound/ti,j721e-cpb-ivi-audio.yaml new file mode 100644 index 000000000000..e0b88470a502 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ti,j721e-cpb-ivi-audio.yaml @@ -0,0 +1,150 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/ti,j721e-cpb-ivi-audio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments J721e Common Processor Board Audio Support + +maintainers: + - Peter Ujfalusi <peter.ujfalusi@ti.com> + +description: | + The Infotainment board plugs into the Common Processor Board, the support of the + extension board is extending the CPB audio support, decribed in: + sound/ti,j721e-cpb-audio.txt + + The audio support on the Infotainment Expansion Board consists of McASP0 + connected to two pcm3168a codecs with dedicated set of serializers to each. + The SCKI for pcm3168a is sourced from j721e AUDIO_REFCLK0 pin. + + In order to support 48KHz and 44.1KHz family of sampling rates the parent clock + for AUDIO_REFCLK0 needs to be changed between PLL4 (for 48KHz) and PLL15 (for + 44.1KHz). The same PLLs are used for McASP0's AUXCLK clock via different + HSDIVIDER. + + Note: the same PLL4 and PLL15 is used by the audio support on the CPB! + + Clocking setup for 48KHz family: + PLL4 ---> PLL4_HSDIV0 ---> MCASP10_AUXCLK ---> McASP10.auxclk + | |-> MCASP0_AUXCLK ---> McASP0.auxclk + | + |-> PLL4_HSDIV2 ---> AUDIO_REFCLK2 ---> pcm3168a.SCKI + |-> AUDIO_REFCLK0 ---> pcm3168a_a/b.SCKI + + Clocking setup for 44.1KHz family: + PLL15 ---> PLL15_HSDIV0 ---> MCASP10_AUXCLK ---> McASP10.auxclk + | |-> MCASP0_AUXCLK ---> McASP0.auxclk + | + |-> PLL15_HSDIV2 ---> AUDIO_REFCLK2 ---> pcm3168a.SCKI + |-> AUDIO_REFCLK0 ---> pcm3168a_a/b.SCKI + +properties: + compatible: + items: + - const: ti,j721e-cpb-ivi-audio + + model: + $ref: /schemas/types.yaml#/definitions/string + description: User specified audio sound card name + + ti,cpb-mcasp: + description: phandle to McASP used on CPB + allOf: + - $ref: /schemas/types.yaml#/definitions/phandle + + ti,cpb-codec: + description: phandle to the pcm3168a codec used on the CPB + allOf: + - $ref: /schemas/types.yaml#/definitions/phandle + + ti,ivi-mcasp: + description: phandle to McASP used on IVI + allOf: + - $ref: /schemas/types.yaml#/definitions/phandle + + ti,ivi-codec-a: + description: phandle to the pcm3168a-A codec on the expansion board + allOf: + - $ref: /schemas/types.yaml#/definitions/phandle + + ti,ivi-codec-b: + description: phandle to the pcm3168a-B codec on the expansion board + allOf: + - $ref: /schemas/types.yaml#/definitions/phandle + + clocks: + items: + - description: AUXCLK clock for McASP used by CPB audio + - description: Parent for CPB_McASP auxclk (for 48KHz) + - description: Parent for CPB_McASP auxclk (for 44.1KHz) + - description: SCKI clock for the pcm3168a codec on CPB + - description: Parent for CPB_SCKI clock (for 48KHz) + - description: Parent for CPB_SCKI clock (for 44.1KHz) + - description: AUXCLK clock for McASP used by IVI audio + - description: Parent for IVI_McASP auxclk (for 48KHz) + - description: Parent for IVI_McASP auxclk (for 44.1KHz) + - description: SCKI clock for the pcm3168a codec on IVI + - description: Parent for IVI_SCKI clock (for 48KHz) + - description: Parent for IVI_SCKI clock (for 44.1KHz) + + clock-names: + items: + - const: cpb-mcasp-auxclk + - const: cpb-mcasp-auxclk-48000 + - const: cpb-mcasp-auxclk-44100 + - const: cpb-codec-scki + - const: cpb-codec-scki-48000 + - const: cpb-codec-scki-44100 + - const: ivi-mcasp-auxclk + - const: ivi-mcasp-auxclk-48000 + - const: ivi-mcasp-auxclk-44100 + - const: ivi-codec-scki + - const: ivi-codec-scki-48000 + - const: ivi-codec-scki-44100 + +required: + - compatible + - model + - ti,cpb-mcasp + - ti,cpb-codec + - ti,ivi-mcasp + - ti,ivi-codec-a + - ti,ivi-codec-b + - clocks + - clock-names + +additionalProperties: false + +examples: + - |+ + sound { + compatible = "ti,j721e-cpb-ivi-audio"; + model = "j721e-cpb-ivi"; + + status = "okay"; + + ti,cpb-mcasp = <&mcasp10>; + ti,cpb-codec = <&pcm3168a_1>; + + ti,ivi-mcasp = <&mcasp0>; + ti,ivi-codec-a = <&pcm3168a_a>; + ti,ivi-codec-b = <&pcm3168a_b>; + + clocks = <&k3_clks 184 1>, + <&k3_clks 184 2>, <&k3_clks 184 4>, + <&k3_clks 157 371>, + <&k3_clks 157 400>, <&k3_clks 157 401>, + <&k3_clks 174 1>, + <&k3_clks 174 2>, <&k3_clks 174 4>, + <&k3_clks 157 301>, + <&k3_clks 157 330>, <&k3_clks 157 331>; + clock-names = "cpb-mcasp-auxclk", + "cpb-mcasp-auxclk-48000", "cpb-mcasp-auxclk-44100", + "cpb-codec-scki", + "cpb-codec-scki-48000", "cpb-codec-scki-44100", + "ivi-mcasp-auxclk", + "ivi-mcasp-auxclk-48000", "ivi-mcasp-auxclk-44100", + "ivi-codec-scki", + "ivi-codec-scki-48000", "ivi-codec-scki-44100"; + }; diff --git a/Documentation/devicetree/bindings/sound/ti,tas6424.txt b/Documentation/devicetree/bindings/sound/ti,tas6424.txt index eacb54f34188..00940c489299 100644 --- a/Documentation/devicetree/bindings/sound/ti,tas6424.txt +++ b/Documentation/devicetree/bindings/sound/ti,tas6424.txt @@ -19,4 +19,4 @@ tas6424: tas6424@6a { }; For more product information please see the link below: -http://www.ti.com/product/TAS6424-Q1 +https://www.ti.com/product/TAS6424-Q1 diff --git a/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml b/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml index 2e6ac5d2ee96..e84d4a20c633 100644 --- a/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml +++ b/Documentation/devicetree/bindings/sound/tlv320adcx140.yaml @@ -18,9 +18,9 @@ description: | microphone bias or supply voltage generation. Specifications can be found at: - http://www.ti.com/lit/ds/symlink/tlv320adc3140.pdf - http://www.ti.com/lit/ds/symlink/tlv320adc5140.pdf - http://www.ti.com/lit/ds/symlink/tlv320adc6140.pdf + https://www.ti.com/lit/ds/symlink/tlv320adc3140.pdf + https://www.ti.com/lit/ds/symlink/tlv320adc5140.pdf + https://www.ti.com/lit/ds/symlink/tlv320adc6140.pdf properties: compatible: @@ -108,6 +108,32 @@ properties: maximum: 7 default: [0, 0, 0, 0] +patternProperties: + '^ti,gpo-config-[1-4]$': + $ref: /schemas/types.yaml#/definitions/uint32-array + description: | + Defines the configuration and output driver for the general purpose + output pins (GPO). These values are pairs, the first value is for the + configuration type and the second value is for the output drive type. + The array is defined as <GPO_CFG GPO_DRV> + + GPO output configuration can be one of the following: + + 0 - (default) disabled + 1 - GPOX is configured as a general-purpose output (GPO) + 2 - GPOX is configured as a device interrupt output (IRQ) + 3 - GPOX is configured as a secondary ASI output (SDOUT2) + 4 - GPOX is configured as a PDM clock output (PDMCLK) + + GPO output drive configuration for the GPO pins can be one of the following: + + 0d - (default) Hi-Z output + 1d - Drive active low and active high + 2d - Drive active low and weak high + 3d - Drive active low and Hi-Z + 4d - Drive weak low and active high + 5d - Drive Hi-Z and active high + required: - compatible - reg @@ -124,6 +150,8 @@ examples: ti,mic-bias-source = <6>; ti,pdm-edge-select = <0 1 0 1>; ti,gpi-config = <4 5 6 7>; + ti,gpo-config-1 = <0 0>; + ti,gpo-config-2 = <0 0>; reset-gpios = <&gpio0 14 GPIO_ACTIVE_HIGH>; }; }; diff --git a/Documentation/devicetree/bindings/sound/uniphier,aio.txt b/Documentation/devicetree/bindings/sound/uniphier,aio.txt deleted file mode 100644 index 4ce68ed6f2f2..000000000000 --- a/Documentation/devicetree/bindings/sound/uniphier,aio.txt +++ /dev/null @@ -1,45 +0,0 @@ -Socionext UniPhier SoC audio driver - -The Socionext UniPhier audio subsystem consists of I2S and S/PDIF blocks in -the same register space. - -Required properties: -- compatible : should be one of the following: - "socionext,uniphier-ld11-aio" - "socionext,uniphier-ld20-aio" - "socionext,uniphier-pxs2-aio" -- reg : offset and length of the register set for the device. -- interrupts : should contain I2S or S/PDIF interrupt. -- pinctrl-names : should be "default". -- pinctrl-0 : defined I2S signal pins for an external codec chip. -- clock-names : should include following entries: - "aio" -- clocks : a list of phandle, should contain an entry for each - entry in clock-names. -- reset-names : should include following entries: - "aio" -- resets : a list of phandle, should contain an entry for each - entry in reset-names. -- #sound-dai-cells: should be 1. - -Optional properties: -- socionext,syscon: a phandle, should contain soc-glue. - The soc-glue is used for changing mode of S/PDIF signal pin - to Output from Hi-Z. This property is optional if you use - I2S signal pins only. - -Example: - audio { - compatible = "socionext,uniphier-ld20-aio"; - reg = <0x56000000 0x80000>; - interrupts = <0 144 4>; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_aout>; - clock-names = "aio"; - clocks = <&sys_clk 40>; - reset-names = "aio"; - resets = <&sys_rst 40>; - #sound-dai-cells = <1>; - - socionext,syscon = <&sg>; - }; diff --git a/Documentation/devicetree/bindings/sound/uniphier,evea.txt b/Documentation/devicetree/bindings/sound/uniphier,evea.txt deleted file mode 100644 index 3f31b235f18b..000000000000 --- a/Documentation/devicetree/bindings/sound/uniphier,evea.txt +++ /dev/null @@ -1,26 +0,0 @@ -Socionext EVEA - UniPhier SoC internal codec driver - -Required properties: -- compatible : should be "socionext,uniphier-evea". -- reg : offset and length of the register set for the device. -- clock-names : should include following entries: - "evea", "exiv" -- clocks : a list of phandle, should contain an entry for each - entries in clock-names. -- reset-names : should include following entries: - "evea", "exiv", "adamv" -- resets : a list of phandle, should contain reset entries of - reset-names. -- #sound-dai-cells: should be 1. - -Example: - - codec { - compatible = "socionext,uniphier-evea"; - reg = <0x57900000 0x1000>; - clock-names = "evea", "exiv"; - clocks = <&sys_clk 41>, <&sys_clk 42>; - reset-names = "evea", "exiv", "adamv"; - resets = <&sys_rst 41>, <&sys_rst 42>, <&adamv_rst 0>; - #sound-dai-cells = <1>; - }; diff --git a/Documentation/devicetree/bindings/sound/wm8960.txt b/Documentation/devicetree/bindings/sound/wm8960.txt index 6d29ac3750ee..85d3b287108c 100644 --- a/Documentation/devicetree/bindings/sound/wm8960.txt +++ b/Documentation/devicetree/bindings/sound/wm8960.txt @@ -21,6 +21,17 @@ Optional properties: enabled and disabled together with HP_L and HP_R pins in response to jack detect events. + - wlf,hp-cfg: A list of headphone jack detect configuration register values. + The list must be 3 entries long. + hp-cfg[0]: HPSEL[1:0] of R48 (Additional Control 4). + hp-cfg[1]: {HPSWEN:HPSWPOL} of R24 (Additional Control 2). + hp-cfg[2]: {TOCLKSEL:TOEN} of R23 (Additional Control 1). + + - wlf,gpio-cfg: A list of GPIO configuration register values. + The list must be 2 entries long. + gpio-cfg[0]: ALRCGPIO of R9 (Audio interface) + gpio-cfg[1]: {GPIOPOL:GPIOSEL[2:0]} of R48 (Additional Control 4). + Example: wm8960: codec@1a { diff --git a/Documentation/devicetree/bindings/sound/wm8994.txt b/Documentation/devicetree/bindings/sound/wm8994.txt index 367b58ce1bb9..8fa947509c10 100644 --- a/Documentation/devicetree/bindings/sound/wm8994.txt +++ b/Documentation/devicetree/bindings/sound/wm8994.txt @@ -68,6 +68,29 @@ Optional properties: - wlf,csnaddr-pd : If present enable the internal pull-down resistor on the CS/ADDR pin. +Pins on the device (for linking into audio routes): + + * IN1LN + * IN1LP + * IN2LN + * IN2LP:VXRN + * IN1RN + * IN1RP + * IN2RN + * IN2RP:VXRP + * SPKOUTLP + * SPKOUTLN + * SPKOUTRP + * SPKOUTRN + * HPOUT1L + * HPOUT1R + * HPOUT2P + * HPOUT2N + * LINEOUT1P + * LINEOUT1N + * LINEOUT2P + * LINEOUT2N + Example: wm8994: codec@1a { diff --git a/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml b/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml index 9147df29022a..38efb50081e3 100644 --- a/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml +++ b/Documentation/devicetree/bindings/spi/amlogic,meson-gx-spicc.yaml @@ -34,12 +34,15 @@ properties: maxItems: 1 clocks: - maxItems: 1 + minItems: 1 + maxItems: 2 + items: + - description: controller register bus clock + - description: baud rate generator and delay control clock clock-names: - description: input clock for the baud rate generator - items: - - const: core + minItems: 1 + maxItems: 2 if: properties: @@ -51,17 +54,22 @@ if: then: properties: clocks: - contains: - items: - - description: controller register bus clock - - description: baud rate generator and delay control clock + minItems: 2 clock-names: - minItems: 2 items: - const: core - const: pclk +else: + properties: + clocks: + maxItems: 1 + + clock-names: + items: + - const: core + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/spi/brcm,bcm2835-spi.txt b/Documentation/devicetree/bindings/spi/brcm,bcm2835-spi.txt index f11f295c8450..3d55dd64b1be 100644 --- a/Documentation/devicetree/bindings/spi/brcm,bcm2835-spi.txt +++ b/Documentation/devicetree/bindings/spi/brcm,bcm2835-spi.txt @@ -5,7 +5,8 @@ SPI0, and the other known as the "Universal SPI Master"; part of the auxiliary block. This binding applies to the SPI0 controller. Required properties: -- compatible: Should be "brcm,bcm2835-spi". +- compatible: Should be one of "brcm,bcm2835-spi" for BCM2835/2836/2837 or + "brcm,bcm2711-spi" for BCM2711 or "brcm,bcm7211-spi" for BCM7211. - reg: Should contain register location and length. - interrupts: Should contain interrupt. - clocks: The clock feeding the SPI controller. diff --git a/Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt b/Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt deleted file mode 100644 index 33bc58f4cf4b..000000000000 --- a/Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt +++ /dev/null @@ -1,56 +0,0 @@ -* Freescale (Enhanced) Configurable Serial Peripheral Interface - (CSPI/eCSPI) for i.MX - -Required properties: -- compatible : - - "fsl,imx1-cspi" for SPI compatible with the one integrated on i.MX1 - - "fsl,imx21-cspi" for SPI compatible with the one integrated on i.MX21 - - "fsl,imx27-cspi" for SPI compatible with the one integrated on i.MX27 - - "fsl,imx31-cspi" for SPI compatible with the one integrated on i.MX31 - - "fsl,imx35-cspi" for SPI compatible with the one integrated on i.MX35 - - "fsl,imx51-ecspi" for SPI compatible with the one integrated on i.MX51 - - "fsl,imx53-ecspi" for SPI compatible with the one integrated on i.MX53 and later Soc - - "fsl,imx8mq-ecspi" for SPI compatible with the one integrated on i.MX8MQ - - "fsl,imx8mm-ecspi" for SPI compatible with the one integrated on i.MX8MM - - "fsl,imx8mn-ecspi" for SPI compatible with the one integrated on i.MX8MN - - "fsl,imx8mp-ecspi" for SPI compatible with the one integrated on i.MX8MP -- reg : Offset and length of the register set for the device -- interrupts : Should contain CSPI/eCSPI interrupt -- clocks : Clock specifiers for both ipg and per clocks. -- clock-names : Clock names should include both "ipg" and "per" -See the clock consumer binding, - Documentation/devicetree/bindings/clock/clock-bindings.txt - -Recommended properties: -- cs-gpios : GPIOs to use as chip selects, see spi-bus.txt. While the native chip -select lines can be used, they appear to always generate a pulse between each -word of a transfer. Most use cases will require GPIO based chip selects to -generate a valid transaction. - -Optional properties: -- num-cs : Number of total chip selects, see spi-bus.txt. -- dmas: DMA specifiers for tx and rx dma. See the DMA client binding, -Documentation/devicetree/bindings/dma/dma.txt. -- dma-names: DMA request names, if present, should include "tx" and "rx". -- fsl,spi-rdy-drctl: Integer, representing the value of DRCTL, the register -controlling the SPI_READY handling. Note that to enable the DRCTL consideration, -the SPI_READY mode-flag needs to be set too. -Valid values are: 0 (disabled), 1 (edge-triggered burst) and 2 (level-triggered burst). - -Obsolete properties: -- fsl,spi-num-chipselects : Contains the number of the chipselect - -Example: - -ecspi@70010000 { - #address-cells = <1>; - #size-cells = <0>; - compatible = "fsl,imx51-ecspi"; - reg = <0x70010000 0x4000>; - interrupts = <36>; - cs-gpios = <&gpio3 24 0>, /* GPIO3_24 */ - <&gpio3 25 0>; /* GPIO3_25 */ - dmas = <&sdma 3 7 1>, <&sdma 4 7 2>; - dma-names = "rx", "tx"; - fsl,spi-rdy-drctl = <1>; -}; diff --git a/Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml b/Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml new file mode 100644 index 000000000000..6e44c9c2aeba --- /dev/null +++ b/Documentation/devicetree/bindings/spi/fsl-imx-cspi.yaml @@ -0,0 +1,97 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/fsl-imx-cspi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale (Enhanced) Configurable Serial Peripheral Interface (CSPI/eCSPI) for i.MX + +maintainers: + - Shawn Guo <shawn.guo@linaro.org> + +allOf: + - $ref: "/schemas/spi/spi-controller.yaml#" + +properties: + compatible: + oneOf: + - const: fsl,imx1-cspi + - const: fsl,imx21-cspi + - const: fsl,imx27-cspi + - const: fsl,imx31-cspi + - const: fsl,imx35-cspi + - const: fsl,imx51-ecspi + - const: fsl,imx53-ecspi + - items: + - enum: + - fsl,imx50-ecspi + - fsl,imx6q-ecspi + - fsl,imx6sx-ecspi + - fsl,imx6sl-ecspi + - fsl,imx6sll-ecspi + - fsl,imx6ul-ecspi + - fsl,imx7d-ecspi + - fsl,imx8mq-ecspi + - fsl,imx8mm-ecspi + - fsl,imx8mn-ecspi + - fsl,imx8mp-ecspi + - const: fsl,imx51-ecspi + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: SoC SPI ipg clock + - description: SoC SPI per clock + + clock-names: + items: + - const: ipg + - const: per + + dmas: + items: + - description: DMA controller phandle and request line for RX + - description: DMA controller phandle and request line for TX + + dma-names: + items: + - const: rx + - const: tx + + fsl,spi-rdy-drctl: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Integer, representing the value of DRCTL, the register controlling + the SPI_READY handling. Note that to enable the DRCTL consideration, + the SPI_READY mode-flag needs to be set too. + Valid values are: 0 (disabled), 1 (edge-triggered burst) and 2 (level-triggered burst). + enum: [0, 1, 2] + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/imx5-clock.h> + + spi@70010000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "fsl,imx51-ecspi"; + reg = <0x70010000 0x4000>; + interrupts = <36>; + clocks = <&clks IMX5_CLK_ECSPI1_IPG_GATE>, + <&clks IMX5_CLK_ECSPI1_PER_GATE>; + clock-names = "ipg", "per"; + }; diff --git a/Documentation/devicetree/bindings/spi/mxs-spi.txt b/Documentation/devicetree/bindings/spi/mxs-spi.txt deleted file mode 100644 index 3499b73293c2..000000000000 --- a/Documentation/devicetree/bindings/spi/mxs-spi.txt +++ /dev/null @@ -1,26 +0,0 @@ -* Freescale MX233/MX28 SSP/SPI - -Required properties: -- compatible: Should be "fsl,<soc>-spi", where soc is "imx23" or "imx28" -- reg: Offset and length of the register set for the device -- interrupts: Should contain SSP ERROR interrupt -- dmas: DMA specifier, consisting of a phandle to DMA controller node - and SSP DMA channel ID. - Refer to dma.txt and fsl-mxs-dma.txt for details. -- dma-names: Must be "rx-tx". - -Optional properties: -- clock-frequency : Input clock frequency to the SPI block in Hz. - Default is 160000000 Hz. - -Example: - -ssp0: ssp@80010000 { - #address-cells = <1>; - #size-cells = <0>; - compatible = "fsl,imx28-spi"; - reg = <0x80010000 0x2000>; - interrupts = <96>; - dmas = <&dma_apbh 0>; - dma-names = "rx-tx"; -}; diff --git a/Documentation/devicetree/bindings/spi/mxs-spi.yaml b/Documentation/devicetree/bindings/spi/mxs-spi.yaml new file mode 100644 index 000000000000..51f8c664323e --- /dev/null +++ b/Documentation/devicetree/bindings/spi/mxs-spi.yaml @@ -0,0 +1,56 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/mxs-spi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale MX233/MX28 SSP/SPI + +maintainers: + - Marek Vasut <marex@denx.de> + +allOf: + - $ref: "/schemas/spi/spi-controller.yaml#" + +properties: + compatible: + enum: + - fsl,imx23-spi + - fsl,imx28-spi + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + dmas: + maxItems: 1 + + dma-names: + const: rx-tx + + clock-frequency: + description: input clock frequency to the SPI block in Hz. + default: 160000000 + +required: + - compatible + - reg + - interrupts + - dmas + - dma-names + +unevaluatedProperties: false + +examples: + - | + spi@80010000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "fsl,imx28-spi"; + reg = <0x80010000 0x2000>; + interrupts = <96>; + dmas = <&dma_apbh 0>; + dma-names = "rx-tx"; + }; diff --git a/Documentation/devicetree/bindings/spi/qcom,spi-geni-qcom.txt b/Documentation/devicetree/bindings/spi/qcom,spi-geni-qcom.txt index 790311a42bf1..c8c1e913f4e7 100644 --- a/Documentation/devicetree/bindings/spi/qcom,spi-geni-qcom.txt +++ b/Documentation/devicetree/bindings/spi/qcom,spi-geni-qcom.txt @@ -19,7 +19,7 @@ Required properties: SPI Controller nodes must be child of GENI based Qualcomm Universal Peripharal. Please refer GENI based QUP wrapper controller node bindings -described in Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.txt. +described in Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml. SPI slave nodes must be children of the SPI master node and conform to SPI bus binding as described in Documentation/devicetree/bindings/spi/spi-bus.txt. diff --git a/Documentation/devicetree/bindings/spi/renesas,sh-msiof.yaml b/Documentation/devicetree/bindings/spi/renesas,sh-msiof.yaml index e84edcf8b332..9f7b118adcaf 100644 --- a/Documentation/devicetree/bindings/spi/renesas,sh-msiof.yaml +++ b/Documentation/devicetree/bindings/spi/renesas,sh-msiof.yaml @@ -21,6 +21,7 @@ properties: # device - items: - enum: + - renesas,msiof-r8a7742 # RZ/G1H - renesas,msiof-r8a7743 # RZ/G1M - renesas,msiof-r8a7744 # RZ/G1N - renesas,msiof-r8a7745 # RZ/G1E @@ -37,6 +38,7 @@ properties: - renesas,msiof-r8a774a1 # RZ/G2M - renesas,msiof-r8a774b1 # RZ/G2N - renesas,msiof-r8a774c0 # RZ/G2E + - renesas,msiof-r8a774e1 # RZ/G2H - renesas,msiof-r8a7795 # R-Car H3 - renesas,msiof-r8a7796 # R-Car M3-W - renesas,msiof-r8a77965 # R-Car M3-N diff --git a/Documentation/devicetree/bindings/spi/spi-davinci.txt b/Documentation/devicetree/bindings/spi/spi-davinci.txt index 9f5b4c7c0c08..e2198a389484 100644 --- a/Documentation/devicetree/bindings/spi/spi-davinci.txt +++ b/Documentation/devicetree/bindings/spi/spi-davinci.txt @@ -1,8 +1,8 @@ Davinci SPI controller device bindings Links on DM: -Keystone 2 - http://www.ti.com/lit/ug/sprugp2a/sprugp2a.pdf -dm644x - http://www.ti.com/lit/ug/sprue32a/sprue32a.pdf +Keystone 2 - https://www.ti.com/lit/ug/sprugp2a/sprugp2a.pdf +dm644x - https://www.ti.com/lit/ug/sprue32a/sprue32a.pdf OMAP-L138/da830 - http://www.ti.com/lit/ug/spruh77a/spruh77a.pdf Required properties: diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.txt b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.txt deleted file mode 100644 index e71b81a41ac0..000000000000 --- a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.txt +++ /dev/null @@ -1,29 +0,0 @@ -* Freescale Low Power SPI (LPSPI) for i.MX - -Required properties: -- compatible : - - "fsl,imx7ulp-spi" for LPSPI compatible with the one integrated on i.MX7ULP soc - - "fsl,imx8qxp-spi" for LPSPI compatible with the one integrated on i.MX8QXP soc -- reg : address and length of the lpspi master registers -- interrupt-parent : core interrupt controller -- interrupts : lpspi interrupt -- clocks : lpspi clock specifier. Its number and order need to correspond to the - value in clock-names. -- clock-names : Corresponding to per clock and ipg clock in "clocks" - respectively. In i.MX7ULP, it only has per clk, so use CLK_DUMMY - to fill the "ipg" blank. -- spi-slave : spi slave mode support. In slave mode, add this attribute without - value. In master mode, remove it. - -Examples: - -lpspi2: lpspi@40290000 { - compatible = "fsl,imx7ulp-spi"; - reg = <0x40290000 0x10000>; - interrupt-parent = <&intc>; - interrupts = <GIC_SPI 28 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clks IMX7ULP_CLK_LPSPI2>, - <&clks IMX7ULP_CLK_DUMMY>; - clock-names = "per", "ipg"; - spi-slave; -}; diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml new file mode 100644 index 000000000000..22882e769e26 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/spi-fsl-lpspi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale Low Power SPI (LPSPI) for i.MX + +maintainers: + - Anson Huang <Anson.Huang@nxp.com> + +allOf: + - $ref: "/schemas/spi/spi-controller.yaml#" + +properties: + compatible: + enum: + - fsl,imx7ulp-spi + - fsl,imx8qxp-spi + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: SoC SPI per clock + - description: SoC SPI ipg clock + + clock-names: + items: + - const: per + - const: ipg + + fsl,spi-only-use-cs1-sel: + description: + spi common code does not support use of CS signals discontinuously. + i.MX8DXL-EVK board only uses CS1 without using CS0. Therefore, add + this property to re-config the chipselect value in the LPSPI driver. + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/imx7ulp-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + spi@40290000 { + compatible = "fsl,imx7ulp-spi"; + reg = <0x40290000 0x10000>; + interrupt-parent = <&intc>; + interrupts = <GIC_SPI 28 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clks IMX7ULP_CLK_LPSPI2>, + <&clks IMX7ULP_CLK_DUMMY>; + clock-names = "per", "ipg"; + spi-slave; + fsl,spi-only-use-cs1-sel; + }; diff --git a/Documentation/devicetree/bindings/spi/spi-lantiq-ssc.txt b/Documentation/devicetree/bindings/spi/spi-lantiq-ssc.txt index ce3230c8e28d..76a3dd35f796 100644 --- a/Documentation/devicetree/bindings/spi/spi-lantiq-ssc.txt +++ b/Documentation/devicetree/bindings/spi/spi-lantiq-ssc.txt @@ -1,11 +1,17 @@ Lantiq Synchronous Serial Controller (SSC) SPI master driver Required properties: -- compatible: "lantiq,ase-spi", "lantiq,falcon-spi", "lantiq,xrx100-spi" +- compatible: "lantiq,ase-spi", "lantiq,falcon-spi", "lantiq,xrx100-spi", + "intel,lgm-spi" - #address-cells: see spi-bus.txt - #size-cells: see spi-bus.txt - reg: address and length of the spi master registers -- interrupts: should contain the "spi_rx", "spi_tx" and "spi_err" interrupt. +- interrupts: + For compatible "intel,lgm-ssc" - the common interrupt number for + all of tx rx & err interrupts. + or + For rest of the compatibles, should contain the "spi_rx", "spi_tx" and + "spi_err" interrupt. Optional properties: @@ -27,3 +33,14 @@ spi: spi@e100800 { num-cs = <6>; base-cs = <1>; }; + +ssc0: spi@e0800000 { + compatible = "intel,lgm-spi"; + reg = <0xe0800000 0x400>; + interrupt-parent = <&ioapic1>; + interrupts = <35 1>; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&cgu0 LGM_CLK_NGI>, <&cgu0 LGM_GCLK_SSC0>; + clock-names = "freq", "gate"; +}; diff --git a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt index 3a8079eb18c8..9e43721fa7d6 100644 --- a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt +++ b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt @@ -11,6 +11,7 @@ Required properties: - mediatek,mt8135-spi: for mt8135 platforms - mediatek,mt8173-spi: for mt8173 platforms - mediatek,mt8183-spi: for mt8183 platforms + - "mediatek,mt8192-spi", "mediatek,mt6765-spi": for mt8192 platforms - "mediatek,mt8516-spi", "mediatek,mt2712-spi": for mt8516 platforms - #address-cells: should be 1. diff --git a/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml b/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml index 87369264feb9..44ba6765697d 100644 --- a/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml +++ b/Documentation/devicetree/bindings/thermal/allwinner,sun8i-a83t-ths.yaml @@ -50,7 +50,7 @@ properties: nvmem-cell-names: const: calibration - # See ./thermal.txt for details + # See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for details "#thermal-sensor-cells": enum: - 0 diff --git a/Documentation/devicetree/bindings/thermal/amazon,al-thermal.txt b/Documentation/devicetree/bindings/thermal/amazon,al-thermal.txt index 703979dbd577..12fc4ef04837 100644 --- a/Documentation/devicetree/bindings/thermal/amazon,al-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/amazon,al-thermal.txt @@ -6,7 +6,7 @@ transaction. Required properties: - compatible: "amazon,al-thermal". - reg: The physical base address and length of the sensor's registers. -- #thermal-sensor-cells: Must be 1. See ./thermal.txt for a description. +- #thermal-sensor-cells: Must be 1. See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for a description. Example: thermal: thermal { diff --git a/Documentation/devicetree/bindings/thermal/brcm,avs-ro-thermal.yaml b/Documentation/devicetree/bindings/thermal/brcm,avs-ro-thermal.yaml index f3e68ed03abf..1ab5070c751d 100644 --- a/Documentation/devicetree/bindings/thermal/brcm,avs-ro-thermal.yaml +++ b/Documentation/devicetree/bindings/thermal/brcm,avs-ro-thermal.yaml @@ -23,7 +23,7 @@ properties: compatible: const: brcm,bcm2711-thermal - # See ./thermal.txt for details + # See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for details "#thermal-sensor-cells": const: 0 diff --git a/Documentation/devicetree/bindings/thermal/brcm,bcm2835-thermal.txt b/Documentation/devicetree/bindings/thermal/brcm,bcm2835-thermal.txt index da8c5b73ad10..a3e9ec5dc7ac 100644 --- a/Documentation/devicetree/bindings/thermal/brcm,bcm2835-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/brcm,bcm2835-thermal.txt @@ -7,7 +7,7 @@ compatible: should be one of: "brcm,bcm2835-thermal", "brcm,bcm2836-thermal" or "brcm,bcm2837-thermal" reg: Address range of the thermal registers. clocks: Phandle of the clock used by the thermal sensor. -#thermal-sensor-cells: should be 0 (see thermal.txt) +#thermal-sensor-cells: should be 0 (see Documentation/devicetree/bindings/thermal/thermal-sensor.yaml) Example: diff --git a/Documentation/devicetree/bindings/thermal/hisilicon-thermal.txt b/Documentation/devicetree/bindings/thermal/hisilicon-thermal.txt index cef716a236f1..4b19d80e6558 100644 --- a/Documentation/devicetree/bindings/thermal/hisilicon-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/hisilicon-thermal.txt @@ -9,7 +9,7 @@ by /SOCTHERM/tsensor. - clock-names: Input clock name, should be 'thermal_clk'. - clocks: phandles for clock specified in "clock-names" property. -- #thermal-sensor-cells: Should be 1. See ./thermal.txt for a description. +- #thermal-sensor-cells: Should be 1. See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for a description. Example : diff --git a/Documentation/devicetree/bindings/thermal/max77620_thermal.txt b/Documentation/devicetree/bindings/thermal/max77620_thermal.txt index 323a3b3822aa..82ed5d487966 100644 --- a/Documentation/devicetree/bindings/thermal/max77620_thermal.txt +++ b/Documentation/devicetree/bindings/thermal/max77620_thermal.txt @@ -8,12 +8,12 @@ below threshold level. Required properties: ------------------- -#thermal-sensor-cells: Please refer <devicetree/bindings/thermal/thermal.txt> - for more details. +#thermal-sensor-cells: For more details, please refer to + <devicetree/bindings/thermal/thermal-sensor.yaml> The value must be 0. For more details, please refer generic thermal DT binding document -<devicetree/bindings/thermal/thermal.txt>. +<devicetree/bindings/thermal/thermal*.yaml>. Please refer <devicetree/bindings/mfd/max77620.txt> for mfd DT binding document for the MAX77620. diff --git a/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt b/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt index f8d7831f3974..1e249c42fae0 100644 --- a/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt @@ -23,7 +23,7 @@ Required properties: - resets: Reference to the reset controller controlling the thermal controller. - mediatek,auxadc: A phandle to the AUXADC which the thermal controller uses - mediatek,apmixedsys: A phandle to the APMIXEDSYS controller. -- #thermal-sensor-cells : Should be 0. See ./thermal.txt for a description. +- #thermal-sensor-cells : Should be 0. See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for a description. Optional properties: - nvmem-cells: A phandle to the calibration data provided by a nvmem device. If diff --git a/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.txt b/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.txt index f02f38527a6b..db880e7ed713 100644 --- a/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.txt +++ b/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.txt @@ -28,9 +28,10 @@ Required properties : See ../reset/reset.txt for details. - reset-names : Must include the following entries: - soctherm -- #thermal-sensor-cells : Should be 1. See ./thermal.txt for a description - of this property. See <dt-bindings/thermal/tegra124-soctherm.h> for a - list of valid values when referring to thermal sensors. +- #thermal-sensor-cells : Should be 1. For a description of this property, see + Documentation/devicetree/bindings/thermal/thermal-sensor.yaml. + See <dt-bindings/thermal/tegra124-soctherm.h> for a list of valid values + when referring to thermal sensors. - throttle-cfgs: A sub-node which is a container of configuration for each hardware throttle events. These events can be set as cooling devices. * throttle events: Sub-nodes must be named as "light" or "heavy". @@ -62,7 +63,8 @@ Required properties : TEGRA_SOCTHERM_THROT_LEVEL_MED (75%), TEGRA_SOCTHERM_THROT_LEVEL_HIGH (85%). - #cooling-cells: Should be 1. This cooling device only support on/off state. - See ./thermal.txt for a description of this property. + For a description of this property see: + Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml Optional properties: The following properties are T210 specific and valid only for OCx throttle events. diff --git a/Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.txt b/Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.txt index e17c07be270b..fc87f6aa1b8f 100644 --- a/Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.txt @@ -8,7 +8,7 @@ exposed by BPMP. The BPMP thermal node must be located directly inside the main BPMP node. See ../firmware/nvidia,tegra186-bpmp.txt for details of the BPMP binding. -This node represents a thermal sensor. See thermal.txt for details of the +This node represents a thermal sensor. See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for details of the core thermal binding. Required properties: diff --git a/Documentation/devicetree/bindings/thermal/qcom-spmi-temp-alarm.txt b/Documentation/devicetree/bindings/thermal/qcom-spmi-temp-alarm.txt index 0273a92a2a84..2d5b2ad03314 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-spmi-temp-alarm.txt +++ b/Documentation/devicetree/bindings/thermal/qcom-spmi-temp-alarm.txt @@ -8,7 +8,7 @@ Required properties: - compatible: Should contain "qcom,spmi-temp-alarm". - reg: Specifies the SPMI address. - interrupts: PMIC temperature alarm interrupt. -- #thermal-sensor-cells: Should be 0. See thermal.txt for a description. +- #thermal-sensor-cells: Should be 0. See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for a description. Optional properties: - io-channels: Should contain IIO channel specifier for the ADC channel, diff --git a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml index d7be931b42d2..95462e071ab4 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml +++ b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml @@ -8,7 +8,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: QCOM SoC Temperature Sensor (TSENS) maintainers: - - Amit Kucheria <amit.kucheria@linaro.org> + - Amit Kucheria <amitk@kernel.org> description: | QCOM SoCs have TSENS IP to allow temperature measurement. There are currently @@ -23,6 +23,7 @@ properties: items: - enum: - qcom,msm8916-tsens + - qcom,msm8939-tsens - qcom,msm8974-tsens - const: qcom,tsens-v0_1 @@ -40,6 +41,8 @@ properties: - qcom,msm8998-tsens - qcom,sc7180-tsens - qcom,sdm845-tsens + - qcom,sm8150-tsens + - qcom,sm8250-tsens - const: qcom,tsens-v2 reg: diff --git a/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt b/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt deleted file mode 100644 index 28f2cbaf1702..000000000000 --- a/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt +++ /dev/null @@ -1,71 +0,0 @@ -* Thermal Monitoring Unit (TMU) on Freescale QorIQ SoCs - -Required properties: -- compatible : Must include "fsl,qoriq-tmu" or "fsl,imx8mq-tmu". The - version of the device is determined by the TMU IP Block Revision - Register (IPBRR0) at offset 0x0BF8. - Table of correspondences between IPBRR0 values and example chips: - Value Device - ---------- ----- - 0x01900102 T1040 -- reg : Address range of TMU registers. -- interrupts : Contains the interrupt for TMU. -- fsl,tmu-range : The values to be programmed into TTRnCR, as specified by - the SoC reference manual. The first cell is TTR0CR, the second is - TTR1CR, etc. -- fsl,tmu-calibration : A list of cell pairs containing temperature - calibration data, as specified by the SoC reference manual. - The first cell of each pair is the value to be written to TTCFGR, - and the second is the value to be written to TSCFGR. -- #thermal-sensor-cells : Must be 1. The sensor specifier is the monitoring - site ID, and represents the "n" in TRITSRn and TRATSRn. - -Optional property: -- little-endian : If present, the TMU registers are little endian. If absent, - the default is big endian. -- clocks : the clock for clocking the TMU silicon. - -Example: - -tmu@f0000 { - compatible = "fsl,qoriq-tmu"; - reg = <0xf0000 0x1000>; - interrupts = <18 2 0 0>; - fsl,tmu-range = <0x000a0000 0x00090026 0x0008004a 0x0001006a>; - fsl,tmu-calibration = <0x00000000 0x00000025 - 0x00000001 0x00000028 - 0x00000002 0x0000002d - 0x00000003 0x00000031 - 0x00000004 0x00000036 - 0x00000005 0x0000003a - 0x00000006 0x00000040 - 0x00000007 0x00000044 - 0x00000008 0x0000004a - 0x00000009 0x0000004f - 0x0000000a 0x00000054 - - 0x00010000 0x0000000d - 0x00010001 0x00000013 - 0x00010002 0x00000019 - 0x00010003 0x0000001f - 0x00010004 0x00000025 - 0x00010005 0x0000002d - 0x00010006 0x00000033 - 0x00010007 0x00000043 - 0x00010008 0x0000004b - 0x00010009 0x00000053 - - 0x00020000 0x00000010 - 0x00020001 0x00000017 - 0x00020002 0x0000001f - 0x00020003 0x00000029 - 0x00020004 0x00000031 - 0x00020005 0x0000003c - 0x00020006 0x00000042 - 0x00020007 0x0000004d - 0x00020008 0x00000056 - - 0x00030000 0x00000012 - 0x00030001 0x0000001d>; - #thermal-sensor-cells = <1>; -}; diff --git a/Documentation/devicetree/bindings/thermal/qoriq-thermal.yaml b/Documentation/devicetree/bindings/thermal/qoriq-thermal.yaml new file mode 100644 index 000000000000..f09e8723ca2b --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/qoriq-thermal.yaml @@ -0,0 +1,114 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/thermal/qoriq-thermal.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Thermal Monitoring Unit (TMU) on Freescale QorIQ SoCs + +maintainers: + - Anson Huang <Anson.Huang@nxp.com> + +properties: + compatible: + description: | + The version of the device is determined by the TMU IP Block Revision + Register (IPBRR0) at offset 0x0BF8. + Table of correspondences between IPBRR0 values and example chips: + Value Device + ---------- ----- + 0x01900102 T1040 + enum: + - fsl,qoriq-tmu + - fsl,imx8mq-tmu + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + fsl,tmu-range: + $ref: '/schemas/types.yaml#/definitions/uint32-array' + description: | + The values to be programmed into TTRnCR, as specified by the SoC + reference manual. The first cell is TTR0CR, the second is TTR1CR, etc. + maxItems: 4 + + fsl,tmu-calibration: + $ref: '/schemas/types.yaml#/definitions/uint32-matrix' + description: | + A list of cell pairs containing temperature calibration data, as + specified by the SoC reference manual. The first cell of each pair + is the value to be written to TTCFGR, and the second is the value + to be written to TSCFGR. + items: + items: + - description: value for TTCFGR + - description: value for TSCFGR + minItems: 1 + maxItems: 64 + + little-endian: + description: | + boolean, if present, the TMU registers are little endian. If absent, + the default is big endian. + type: boolean + + clocks: + maxItems: 1 + + "#thermal-sensor-cells": + const: 1 + +required: + - compatible + - reg + - interrupts + - fsl,tmu-range + - fsl,tmu-calibration + - '#thermal-sensor-cells' + +additionalProperties: false + +examples: + - | + tmu@f0000 { + compatible = "fsl,qoriq-tmu"; + reg = <0xf0000 0x1000>; + interrupts = <18 2 0 0>; + fsl,tmu-range = <0x000a0000 0x00090026 0x0008004a 0x0001006a>; + fsl,tmu-calibration = <0x00000000 0x00000025>, + <0x00000001 0x00000028>, + <0x00000002 0x0000002d>, + <0x00000003 0x00000031>, + <0x00000004 0x00000036>, + <0x00000005 0x0000003a>, + <0x00000006 0x00000040>, + <0x00000007 0x00000044>, + <0x00000008 0x0000004a>, + <0x00000009 0x0000004f>, + <0x0000000a 0x00000054>, + <0x00010000 0x0000000d>, + <0x00010001 0x00000013>, + <0x00010002 0x00000019>, + <0x00010003 0x0000001f>, + <0x00010004 0x00000025>, + <0x00010005 0x0000002d>, + <0x00010006 0x00000033>, + <0x00010007 0x00000043>, + <0x00010008 0x0000004b>, + <0x00010009 0x00000053>, + <0x00020000 0x00000010>, + <0x00020001 0x00000017>, + <0x00020002 0x0000001f>, + <0x00020003 0x00000029>, + <0x00020004 0x00000031>, + <0x00020005 0x0000003c>, + <0x00020006 0x00000042>, + <0x00020007 0x0000004d>, + <0x00020008 0x00000056>, + <0x00030000 0x00000012>, + <0x00030001 0x0000001d>; + #thermal-sensor-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/thermal/rockchip-thermal.txt b/Documentation/devicetree/bindings/thermal/rockchip-thermal.txt index c6aac9bcacf1..7f94669e9ebe 100644 --- a/Documentation/devicetree/bindings/thermal/rockchip-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/rockchip-thermal.txt @@ -24,7 +24,7 @@ Required properties: - pinctrl-1 : The "default" pinctrl state, it will be set after reset the TSADC controller. - pinctrl-2 : The "sleep" pinctrl state, it will be in for suspend. -- #thermal-sensor-cells : Should be 1. See ./thermal.txt for a description. +- #thermal-sensor-cells : Should be 1. See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for a description. Optional properties: - rockchip,hw-tshut-temp : The hardware-controlled shutdown temperature value. diff --git a/Documentation/devicetree/bindings/thermal/tango-thermal.txt b/Documentation/devicetree/bindings/thermal/tango-thermal.txt index 212198d4b937..2c918d742867 100644 --- a/Documentation/devicetree/bindings/thermal/tango-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/tango-thermal.txt @@ -4,7 +4,7 @@ The SMP8758 SoC includes 3 instances of this temperature sensor (in the CPU, video decoder, and PCIe controller). Required properties: -- #thermal-sensor-cells: Should be 0 (see thermal.txt) +- #thermal-sensor-cells: Should be 0 (see Documentation/devicetree/bindings/thermal/thermal-sensor.yaml) - compatible: "sigma,smp8758-thermal" - reg: Address range of the thermal registers diff --git a/Documentation/devicetree/bindings/thermal/thermal-generic-adc.txt b/Documentation/devicetree/bindings/thermal/thermal-generic-adc.txt index 691a09db2fef..e136946a2f4f 100644 --- a/Documentation/devicetree/bindings/thermal/thermal-generic-adc.txt +++ b/Documentation/devicetree/bindings/thermal/thermal-generic-adc.txt @@ -8,7 +8,7 @@ temperature using voltage-temperature lookup table. Required properties: =================== - compatible: Must be "generic-adc-thermal". -- #thermal-sensor-cells: Should be 1. See ./thermal.txt for a description +- #thermal-sensor-cells: Should be 1. See Documentation/devicetree/bindings/thermal/thermal-sensor.yaml for a description of this property. Optional properties: =================== diff --git a/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml b/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml index fcd25a0af38c..727d04550324 100644 --- a/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml +++ b/Documentation/devicetree/bindings/thermal/thermal-sensor.yaml @@ -41,7 +41,7 @@ examples: #include <dt-bindings/interrupt-controller/arm-gic.h> // Example 1: SDM845 TSENS - soc: soc@0 { + soc: soc { #address-cells = <2>; #size-cells = <2>; diff --git a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml index b8515d3eeaa2..3ec9cc87ec50 100644 --- a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml +++ b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml @@ -224,7 +224,7 @@ examples: #include <dt-bindings/thermal/thermal.h> // Example 1: SDM845 TSENS - soc: soc@0 { + soc { #address-cells = <2>; #size-cells = <2>; diff --git a/Documentation/devicetree/bindings/thermal/thermal.txt b/Documentation/devicetree/bindings/thermal/thermal.txt deleted file mode 100644 index f78bec19ca35..000000000000 --- a/Documentation/devicetree/bindings/thermal/thermal.txt +++ /dev/null @@ -1,586 +0,0 @@ -* Thermal Framework Device Tree descriptor - -This file describes a generic binding to provide a way of -defining hardware thermal structure using device tree. -A thermal structure includes thermal zones and their components, -such as trip points, polling intervals, sensors and cooling devices -binding descriptors. - -The target of device tree thermal descriptors is to describe only -the hardware thermal aspects. The thermal device tree bindings are -not about how the system must control or which algorithm or policy -must be taken in place. - -There are five types of nodes involved to describe thermal bindings: -- thermal sensors: devices which may be used to take temperature - measurements. -- cooling devices: devices which may be used to dissipate heat. -- trip points: describe key temperatures at which cooling is recommended. The - set of points should be chosen based on hardware limits. -- cooling maps: used to describe links between trip points and cooling devices; -- thermal zones: used to describe thermal data within the hardware; - -The following is a description of each of these node types. - -* Thermal sensor devices - -Thermal sensor devices are nodes providing temperature sensing capabilities on -thermal zones. Typical devices are I2C ADC converters and bandgaps. These are -nodes providing temperature data to thermal zones. Thermal sensor devices may -control one or more internal sensors. - -Required property: -- #thermal-sensor-cells: Used to provide sensor device specific information - Type: unsigned while referring to it. Typically 0 on thermal sensor - Size: one cell nodes with only one sensor, and at least 1 on nodes - with several internal sensors, in order - to identify uniquely the sensor instances within - the IC. See thermal zone binding for more details - on how consumers refer to sensor devices. - -* Cooling device nodes - -Cooling devices are nodes providing control on power dissipation. There -are essentially two ways to provide control on power dissipation. First -is by means of regulating device performance, which is known as passive -cooling. A typical passive cooling is a CPU that has dynamic voltage and -frequency scaling (DVFS), and uses lower frequencies as cooling states. -Second is by means of activating devices in order to remove -the dissipated heat, which is known as active cooling, e.g. regulating -fan speeds. In both cases, cooling devices shall have a way to determine -the state of cooling in which the device is. - -Any cooling device has a range of cooling states (i.e. different levels -of heat dissipation). For example a fan's cooling states correspond to -the different fan speeds possible. Cooling states are referred to by -single unsigned integers, where larger numbers mean greater heat -dissipation. The precise set of cooling states associated with a device -should be defined in a particular device's binding. -For more examples of cooling devices, refer to the example sections below. - -Required properties: -- #cooling-cells: Used to provide cooling device specific information - Type: unsigned while referring to it. Must be at least 2, in order - Size: one cell to specify minimum and maximum cooling state used - in the reference. The first cell is the minimum - cooling state requested and the second cell is - the maximum cooling state requested in the reference. - See Cooling device maps section below for more details - on how consumers refer to cooling devices. - -* Trip points - -The trip node is a node to describe a point in the temperature domain -in which the system takes an action. This node describes just the point, -not the action. - -Required properties: -- temperature: An integer indicating the trip temperature level, - Type: signed in millicelsius. - Size: one cell - -- hysteresis: A low hysteresis value on temperature property (above). - Type: unsigned This is a relative value, in millicelsius. - Size: one cell - -- type: a string containing the trip type. Expected values are: - "active": A trip point to enable active cooling - "passive": A trip point to enable passive cooling - "hot": A trip point to notify emergency - "critical": Hardware not reliable. - Type: string - -* Cooling device maps - -The cooling device maps node is a node to describe how cooling devices -get assigned to trip points of the zone. The cooling devices are expected -to be loaded in the target system. - -Required properties: -- cooling-device: A list of phandles of cooling devices with their specifiers, - Type: phandle + referring to which cooling devices are used in this - cooling specifier binding. In the cooling specifier, the first cell - is the minimum cooling state and the second cell - is the maximum cooling state used in this map. -- trip: A phandle of a trip point node within the same thermal - Type: phandle of zone. - trip point node - -Optional property: -- contribution: The cooling contribution to the thermal zone of the - Type: unsigned referred cooling device at the referred trip point. - Size: one cell The contribution is a ratio of the sum - of all cooling contributions within a thermal zone. - -Note: Using the THERMAL_NO_LIMIT (-1UL) constant in the cooling-device phandle -limit specifier means: -(i) - minimum state allowed for minimum cooling state used in the reference. -(ii) - maximum state allowed for maximum cooling state used in the reference. -Refer to include/dt-bindings/thermal/thermal.h for definition of this constant. - -* Thermal zone nodes - -The thermal zone node is the node containing all the required info -for describing a thermal zone, including its cooling device bindings. The -thermal zone node must contain, apart from its own properties, one sub-node -containing trip nodes and one sub-node containing all the zone cooling maps. - -Required properties: -- polling-delay: The maximum number of milliseconds to wait between polls - Type: unsigned when checking this thermal zone. - Size: one cell - -- polling-delay-passive: The maximum number of milliseconds to wait - Type: unsigned between polls when performing passive cooling. - Size: one cell - -- thermal-sensors: A list of thermal sensor phandles and sensor specifier - Type: list of used while monitoring the thermal zone. - phandles + sensor - specifier - -- trips: A sub-node which is a container of only trip point nodes - Type: sub-node required to describe the thermal zone. - -Optional property: -- cooling-maps: A sub-node which is a container of only cooling device - Type: sub-node map nodes, used to describe the relation between trips - and cooling devices. - -- coefficients: An array of integers (one signed cell) containing - Type: array coefficients to compose a linear relation between - Elem size: one cell the sensors listed in the thermal-sensors property. - Elem type: signed Coefficients defaults to 1, in case this property - is not specified. A simple linear polynomial is used: - Z = c0 * x0 + c1 * x1 + ... + c(n-1) * x(n-1) + cn. - - The coefficients are ordered and they match with sensors - by means of sensor ID. Additional coefficients are - interpreted as constant offset. - -- sustainable-power: An estimate of the sustainable power (in mW) that the - Type: unsigned thermal zone can dissipate at the desired - Size: one cell control temperature. For reference, the - sustainable power of a 4'' phone is typically - 2000mW, while on a 10'' tablet is around - 4500mW. - -Note: The delay properties are bound to the maximum dT/dt (temperature -derivative over time) in two situations for a thermal zone: -(i) - when passive cooling is activated (polling-delay-passive); and -(ii) - when the zone just needs to be monitored (polling-delay) or -when active cooling is activated. - -The maximum dT/dt is highly bound to hardware power consumption and dissipation -capability. The delays should be chosen to account for said max dT/dt, -such that a device does not cross several trip boundaries unexpectedly -between polls. Choosing the right polling delays shall avoid having the -device in temperature ranges that may damage the silicon structures and -reduce silicon lifetime. - -* The thermal-zones node - -The "thermal-zones" node is a container for all thermal zone nodes. It shall -contain only sub-nodes describing thermal zones as in the section -"Thermal zone nodes". The "thermal-zones" node appears under "/". - -* Examples - -Below are several examples on how to use thermal data descriptors -using device tree bindings: - -(a) - CPU thermal zone - -The CPU thermal zone example below describes how to setup one thermal zone -using one single sensor as temperature source and many cooling devices and -power dissipation control sources. - -#include <dt-bindings/thermal/thermal.h> - -cpus { - /* - * Here is an example of describing a cooling device for a DVFS - * capable CPU. The CPU node describes its four OPPs. - * The cooling states possible are 0..3, and they are - * used as OPP indexes. The minimum cooling state is 0, which means - * all four OPPs can be available to the system. The maximum - * cooling state is 3, which means only the lowest OPPs (198MHz@0.85V) - * can be available in the system. - */ - cpu0: cpu@0 { - ... - operating-points = < - /* kHz uV */ - 970000 1200000 - 792000 1100000 - 396000 950000 - 198000 850000 - >; - #cooling-cells = <2>; /* min followed by max */ - }; - ... -}; - -&i2c1 { - ... - /* - * A simple fan controller which supports 10 speeds of operation - * (represented as 0-9). - */ - fan0: fan@48 { - ... - #cooling-cells = <2>; /* min followed by max */ - }; -}; - -ocp { - ... - /* - * A simple IC with a single bandgap temperature sensor. - */ - bandgap0: bandgap@0000ed00 { - ... - #thermal-sensor-cells = <0>; - }; -}; - -thermal-zones { - cpu_thermal: cpu-thermal { - polling-delay-passive = <250>; /* milliseconds */ - polling-delay = <1000>; /* milliseconds */ - - thermal-sensors = <&bandgap0>; - - trips { - cpu_alert0: cpu-alert0 { - temperature = <90000>; /* millicelsius */ - hysteresis = <2000>; /* millicelsius */ - type = "active"; - }; - cpu_alert1: cpu-alert1 { - temperature = <100000>; /* millicelsius */ - hysteresis = <2000>; /* millicelsius */ - type = "passive"; - }; - cpu_crit: cpu-crit { - temperature = <125000>; /* millicelsius */ - hysteresis = <2000>; /* millicelsius */ - type = "critical"; - }; - }; - - cooling-maps { - map0 { - trip = <&cpu_alert0>; - cooling-device = <&fan0 THERMAL_NO_LIMIT 4>; - }; - map1 { - trip = <&cpu_alert1>; - cooling-device = <&fan0 5 THERMAL_NO_LIMIT>, <&cpu0 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>; - }; - }; - }; -}; - -In the example above, the ADC sensor (bandgap0) at address 0x0000ED00 is -used to monitor the zone 'cpu-thermal' using its sole sensor. A fan -device (fan0) is controlled via I2C bus 1, at address 0x48, and has ten -different cooling states 0-9. It is used to remove the heat out of -the thermal zone 'cpu-thermal' using its cooling states -from its minimum to 4, when it reaches trip point 'cpu_alert0' -at 90C, as an example of active cooling. The same cooling device is used at -'cpu_alert1', but from 5 to its maximum state. The cpu@0 device is also -linked to the same thermal zone, 'cpu-thermal', as a passive cooling device, -using all its cooling states at trip point 'cpu_alert1', -which is a trip point at 100C. On the thermal zone 'cpu-thermal', at the -temperature of 125C, represented by the trip point 'cpu_crit', the silicon -is not reliable anymore. - -(b) - IC with several internal sensors - -The example below describes how to deploy several thermal zones based off a -single sensor IC, assuming it has several internal sensors. This is a common -case on SoC designs with several internal IPs that may need different thermal -requirements, and thus may have their own sensor to monitor or detect internal -hotspots in their silicon. - -#include <dt-bindings/thermal/thermal.h> - -ocp { - ... - /* - * A simple IC with several bandgap temperature sensors. - */ - bandgap0: bandgap@0000ed00 { - ... - #thermal-sensor-cells = <1>; - }; -}; - -thermal-zones { - cpu_thermal: cpu-thermal { - polling-delay-passive = <250>; /* milliseconds */ - polling-delay = <1000>; /* milliseconds */ - - /* sensor ID */ - thermal-sensors = <&bandgap0 0>; - - trips { - /* each zone within the SoC may have its own trips */ - cpu_alert: cpu-alert { - temperature = <100000>; /* millicelsius */ - hysteresis = <2000>; /* millicelsius */ - type = "passive"; - }; - cpu_crit: cpu-crit { - temperature = <125000>; /* millicelsius */ - hysteresis = <2000>; /* millicelsius */ - type = "critical"; - }; - }; - - cooling-maps { - /* each zone within the SoC may have its own cooling */ - ... - }; - }; - - gpu_thermal: gpu-thermal { - polling-delay-passive = <120>; /* milliseconds */ - polling-delay = <1000>; /* milliseconds */ - - /* sensor ID */ - thermal-sensors = <&bandgap0 1>; - - trips { - /* each zone within the SoC may have its own trips */ - gpu_alert: gpu-alert { - temperature = <90000>; /* millicelsius */ - hysteresis = <2000>; /* millicelsius */ - type = "passive"; - }; - gpu_crit: gpu-crit { - temperature = <105000>; /* millicelsius */ - hysteresis = <2000>; /* millicelsius */ - type = "critical"; - }; - }; - - cooling-maps { - /* each zone within the SoC may have its own cooling */ - ... - }; - }; - - dsp_thermal: dsp-thermal { - polling-delay-passive = <50>; /* milliseconds */ - polling-delay = <1000>; /* milliseconds */ - - /* sensor ID */ - thermal-sensors = <&bandgap0 2>; - - trips { - /* each zone within the SoC may have its own trips */ - dsp_alert: dsp-alert { - temperature = <90000>; /* millicelsius */ - hysteresis = <2000>; /* millicelsius */ - type = "passive"; - }; - dsp_crit: gpu-crit { - temperature = <135000>; /* millicelsius */ - hysteresis = <2000>; /* millicelsius */ - type = "critical"; - }; - }; - - cooling-maps { - /* each zone within the SoC may have its own cooling */ - ... - }; - }; -}; - -In the example above, there is one bandgap IC which has the capability to -monitor three sensors. The hardware has been designed so that sensors are -placed on different places in the DIE to monitor different temperature -hotspots: one for CPU thermal zone, one for GPU thermal zone and the -other to monitor a DSP thermal zone. - -Thus, there is a need to assign each sensor provided by the bandgap IC -to different thermal zones. This is achieved by means of using the -#thermal-sensor-cells property and using the first cell of the sensor -specifier as sensor ID. In the example, then, <bandgap 0> is used to -monitor CPU thermal zone, <bandgap 1> is used to monitor GPU thermal -zone and <bandgap 2> is used to monitor DSP thermal zone. Each zone -may be uncorrelated, having its own dT/dt requirements, trips -and cooling maps. - - -(c) - Several sensors within one single thermal zone - -The example below illustrates how to use more than one sensor within -one thermal zone. - -#include <dt-bindings/thermal/thermal.h> - -&i2c1 { - ... - /* - * A simple IC with a single temperature sensor. - */ - adc: sensor@49 { - ... - #thermal-sensor-cells = <0>; - }; -}; - -ocp { - ... - /* - * A simple IC with a single bandgap temperature sensor. - */ - bandgap0: bandgap@0000ed00 { - ... - #thermal-sensor-cells = <0>; - }; -}; - -thermal-zones { - cpu_thermal: cpu-thermal { - polling-delay-passive = <250>; /* milliseconds */ - polling-delay = <1000>; /* milliseconds */ - - thermal-sensors = <&bandgap0>, /* cpu */ - <&adc>; /* pcb north */ - - /* hotspot = 100 * bandgap - 120 * adc + 484 */ - coefficients = <100 -120 484>; - - trips { - ... - }; - - cooling-maps { - ... - }; - }; -}; - -In some cases, there is a need to use more than one sensor to extrapolate -a thermal hotspot in the silicon. The above example illustrates this situation. -For instance, it may be the case that a sensor external to CPU IP may be placed -close to CPU hotspot and together with internal CPU sensor, it is used -to determine the hotspot. Assuming this is the case for the above example, -the hypothetical extrapolation rule would be: - hotspot = 100 * bandgap - 120 * adc + 484 - -In other context, the same idea can be used to add fixed offset. For instance, -consider the hotspot extrapolation rule below: - hotspot = 1 * adc + 6000 - -In the above equation, the hotspot is always 6C higher than what is read -from the ADC sensor. The binding would be then: - thermal-sensors = <&adc>; - - /* hotspot = 1 * adc + 6000 */ - coefficients = <1 6000>; - -(d) - Board thermal - -The board thermal example below illustrates how to setup one thermal zone -with many sensors and many cooling devices. - -#include <dt-bindings/thermal/thermal.h> - -&i2c1 { - ... - /* - * An IC with several temperature sensor. - */ - adc_dummy: sensor@50 { - ... - #thermal-sensor-cells = <1>; /* sensor internal ID */ - }; -}; - -thermal-zones { - batt-thermal { - polling-delay-passive = <500>; /* milliseconds */ - polling-delay = <2500>; /* milliseconds */ - - /* sensor ID */ - thermal-sensors = <&adc_dummy 4>; - - trips { - ... - }; - - cooling-maps { - ... - }; - }; - - board_thermal: board-thermal { - polling-delay-passive = <1000>; /* milliseconds */ - polling-delay = <2500>; /* milliseconds */ - - /* sensor ID */ - thermal-sensors = <&adc_dummy 0>, /* pcb top edge */ - <&adc_dummy 1>, /* lcd */ - <&adc_dummy 2>; /* back cover */ - /* - * An array of coefficients describing the sensor - * linear relation. E.g.: - * z = c1*x1 + c2*x2 + c3*x3 - */ - coefficients = <1200 -345 890>; - - sustainable-power = <2500>; - - trips { - /* Trips are based on resulting linear equation */ - cpu_trip: cpu-trip { - temperature = <60000>; /* millicelsius */ - hysteresis = <2000>; /* millicelsius */ - type = "passive"; - }; - gpu_trip: gpu-trip { - temperature = <55000>; /* millicelsius */ - hysteresis = <2000>; /* millicelsius */ - type = "passive"; - } - lcd_trip: lcp-trip { - temperature = <53000>; /* millicelsius */ - hysteresis = <2000>; /* millicelsius */ - type = "passive"; - }; - crit_trip: crit-trip { - temperature = <68000>; /* millicelsius */ - hysteresis = <2000>; /* millicelsius */ - type = "critical"; - }; - }; - - cooling-maps { - map0 { - trip = <&cpu_trip>; - cooling-device = <&cpu0 0 2>; - contribution = <55>; - }; - map1 { - trip = <&gpu_trip>; - cooling-device = <&gpu0 0 2>; - contribution = <20>; - }; - map2 { - trip = <&lcd_trip>; - cooling-device = <&lcd0 5 10>; - contribution = <15>; - }; - }; - }; -}; - -The above example is a mix of previous examples, a sensor IP with several internal -sensors used to monitor different zones, one of them is composed by several sensors and -with different cooling devices. diff --git a/Documentation/devicetree/bindings/thermal/ti,am654-thermal.yaml b/Documentation/devicetree/bindings/thermal/ti,am654-thermal.yaml index 25b9209c2e5d..ea14de80ec75 100644 --- a/Documentation/devicetree/bindings/thermal/ti,am654-thermal.yaml +++ b/Documentation/devicetree/bindings/thermal/ti,am654-thermal.yaml @@ -35,7 +35,7 @@ examples: #include <dt-bindings/soc/ti,sci_pm_domain.h> vtm: thermal@42050000 { compatible = "ti,am654-vtm"; - reg = <0x0 0x42050000 0x0 0x25c>; + reg = <0x42050000 0x25c>; power-domains = <&k3_pds 80 TI_SCI_PD_EXCLUSIVE>; #thermal-sensor-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/timer/csky,mptimer.txt b/Documentation/devicetree/bindings/timer/csky,mptimer.txt index 15cfec08fbb8..f5c7e99cf52b 100644 --- a/Documentation/devicetree/bindings/timer/csky,mptimer.txt +++ b/Documentation/devicetree/bindings/timer/csky,mptimer.txt @@ -8,7 +8,7 @@ regs is accessed by cpu co-processor 4 registers with mtcr/mfcr. - PTIM_CTLR "cr<0, 14>" Control reg to start reset timer. - PTIM_TSR "cr<1, 14>" Interrupt cleanup status reg. - PTIM_CCVR "cr<3, 14>" Current counter value reg. - - PTIM_LVR "cr<6, 14>" Window value reg to triger next event. + - PTIM_LVR "cr<6, 14>" Window value reg to trigger next event. ============================== timer node bindings definition diff --git a/Documentation/devicetree/bindings/timer/ingenic,sysost.yaml b/Documentation/devicetree/bindings/timer/ingenic,sysost.yaml new file mode 100644 index 000000000000..df3eb76045e0 --- /dev/null +++ b/Documentation/devicetree/bindings/timer/ingenic,sysost.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/ingenic,sysost.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Bindings for SYSOST in Ingenic XBurst family SoCs + +maintainers: + - 周ç°æ° (Zhou Yanjie) <zhouyanjie@wanyeetech.com> + +description: + The SYSOST in an Ingenic SoC provides one 64bit timer for clocksource + and one or more 32bit timers for clockevent. + +properties: + "#clock-cells": + const: 1 + + compatible: + enum: + - ingenic,x1000-ost + - ingenic,x2000-ost + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + const: ost + + interrupts: + maxItems: 1 + +required: + - "#clock-cells" + - compatible + - reg + - clocks + - clock-names + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/x1000-cgu.h> + + ost: timer@12000000 { + compatible = "ingenic,x1000-ost"; + reg = <0x12000000 0x3c>; + + #clock-cells = <1>; + + clocks = <&cgu X1000_CLK_OST>; + clock-names = "ost"; + + interrupt-parent = <&cpuintc>; + interrupts = <3>; + }; +... diff --git a/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml b/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml index 03893e6a2f57..371fb02a4351 100644 --- a/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml +++ b/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml @@ -116,7 +116,9 @@ patternProperties: - ingenic,jz4740-watchdog - ingenic,jz4780-watchdog - items: - - const: ingenic,jz4770-watchdog + - enum: + - ingenic,jz4770-watchdog + - ingenic,jz4725b-watchdog - const: ingenic,jz4740-watchdog reg: @@ -142,6 +144,7 @@ patternProperties: oneOf: - enum: - ingenic,jz4740-pwm + - ingenic,jz4725b-pwm - items: - enum: - ingenic,jz4770-pwm diff --git a/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.txt b/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.txt deleted file mode 100644 index b8f02c663521..000000000000 --- a/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.txt +++ /dev/null @@ -1,17 +0,0 @@ -* Marvell MMP Timer controller - -Required properties: -- compatible : Should be "mrvl,mmp-timer". -- reg : Address and length of the register set of timer controller. -- interrupts : Should be the interrupt number. - -Optional properties: -- clocks : Should contain a single entry describing the clock input. - -Example: - timer0: timer@d4014000 { - compatible = "mrvl,mmp-timer"; - reg = <0xd4014000 0x100>; - interrupts = <13>; - clocks = <&coreclk 2>; - }; diff --git a/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.yaml b/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.yaml new file mode 100644 index 000000000000..1fbc260a0cbd --- /dev/null +++ b/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/mrvl,mmp-timer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell MMP Timer bindings + +maintainers: + - Daniel Lezcano <daniel.lezcano@linaro.org> + - Thomas Gleixner <tglx@linutronix.de> + - Rob Herring <robh+dt@kernel.org> + +properties: + $nodename: + pattern: '^timer@[a-f0-9]+$' + + compatible: + const: mrvl,mmp-timer + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + timer@d4014000 { + compatible = "mrvl,mmp-timer"; + reg = <0xd4014000 0x100>; + interrupts = <13>; + clocks = <&coreclk 2>; + }; + +... diff --git a/Documentation/devicetree/bindings/timer/ti,keystone-timer.txt b/Documentation/devicetree/bindings/timer/ti,keystone-timer.txt index 5fbe361252b4..d3905a5412b8 100644 --- a/Documentation/devicetree/bindings/timer/ti,keystone-timer.txt +++ b/Documentation/devicetree/bindings/timer/ti,keystone-timer.txt @@ -10,7 +10,7 @@ It is global timer is a free running up-counter and can generate interrupt when the counter reaches preset counter values. Documentation: -http://www.ti.com/lit/ug/sprugv5a/sprugv5a.pdf +https://www.ti.com/lit/ug/sprugv5a/sprugv5a.pdf Required properties: diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml index 4165352a590a..b7e94fe8643f 100644 --- a/Documentation/devicetree/bindings/trivial-devices.yaml +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -80,8 +80,6 @@ properties: - fsl,mpl3115 # MPR121: Proximity Capacitive Touch Sensor Controller - fsl,mpr121 - # SGTL5000: Ultra Low-Power Audio Codec - - fsl,sgtl5000 # G751: Digital Temperature Sensor and Thermal Watchdog with Two-Wire Interface - gmt,g751 # Infineon IR38064 Voltage Regulator diff --git a/Documentation/devicetree/bindings/usb/aspeed,usb-vhub.yaml b/Documentation/devicetree/bindings/usb/aspeed,usb-vhub.yaml index e4e83d3971ac..8b019ac05bbe 100644 --- a/Documentation/devicetree/bindings/usb/aspeed,usb-vhub.yaml +++ b/Documentation/devicetree/bindings/usb/aspeed,usb-vhub.yaml @@ -127,8 +127,8 @@ examples: #address-cells = <1>; #size-cells = <0>; - string@0409 { - reg = <0x0409>; + string@409 { + reg = <0x409>; manufacturer = "ASPEED"; product = "USB Virtual Hub"; serial-number = "0000"; diff --git a/Documentation/devicetree/bindings/usb/brcm,bdc.txt b/Documentation/devicetree/bindings/usb/brcm,bdc.txt index 63e63af3bf59..c9f52b97cef1 100644 --- a/Documentation/devicetree/bindings/usb/brcm,bdc.txt +++ b/Documentation/devicetree/bindings/usb/brcm,bdc.txt @@ -4,7 +4,7 @@ Broadcom USB Device Controller (BDC) Required properties: - compatible: must be one of: - "brcm,bdc-v0.16" + "brcm,bdc-udc-v2" "brcm,bdc" - reg: the base register address and length - interrupts: the interrupt line for this controller @@ -21,7 +21,7 @@ On Broadcom STB platforms, these properties are required: Example: bdc@f0b02000 { - compatible = "brcm,bdc-v0.16"; + compatible = "brcm,bdc-udc-v2"; reg = <0xf0b02000 0xfc4>; interrupts = <0x0 0x60 0x0>; phys = <&usbphy_0 0x0>; diff --git a/Documentation/devicetree/bindings/usb/dwc2.yaml b/Documentation/devicetree/bindings/usb/dwc2.yaml index 9352a8ef60a6..4ff632d82858 100644 --- a/Documentation/devicetree/bindings/usb/dwc2.yaml +++ b/Documentation/devicetree/bindings/usb/dwc2.yaml @@ -44,7 +44,9 @@ properties: - const: st,stm32f4x9-hsotg - const: st,stm32f7-hsotg - const: st,stm32mp15-fsotg - - const: st,stm32mp15-hsotg + - items: + - const: st,stm32mp15-hsotg + - const: snps,dwc2 - const: samsung,s3c6400-hsotg reg: @@ -93,7 +95,7 @@ properties: vusb_a-supply: description: phandle to voltage regulator of analog section. - vusb33d-supply: + usb33d-supply: description: reference to the VBUS and ID sensing comparators supply, in order to perform OTG operation, used on STM32MP15 SoCs. diff --git a/Documentation/devicetree/bindings/usb/ingenic,jz4770-phy.yaml b/Documentation/devicetree/bindings/usb/ingenic,jz4770-phy.yaml index a81b0b1a2226..2d61166ea5cf 100644 --- a/Documentation/devicetree/bindings/usb/ingenic,jz4770-phy.yaml +++ b/Documentation/devicetree/bindings/usb/ingenic,jz4770-phy.yaml @@ -4,10 +4,11 @@ $id: http://devicetree.org/schemas/usb/ingenic,jz4770-phy.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Ingenic JZ4770 USB PHY devicetree bindings +title: Ingenic SoCs USB PHY devicetree bindings maintainers: - Paul Cercueil <paul@crapouillou.net> + - 周ç°æ° (Zhou Yanjie) <zhouyanjie@wanyeetech.com> properties: $nodename: @@ -16,6 +17,9 @@ properties: compatible: enum: - ingenic,jz4770-phy + - ingenic,jz4780-phy + - ingenic,x1000-phy + - ingenic,x1830-phy reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/usb/renesas,usb-xhci.yaml b/Documentation/devicetree/bindings/usb/renesas,usb-xhci.yaml new file mode 100644 index 000000000000..add9f7b66da0 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/renesas,usb-xhci.yaml @@ -0,0 +1,86 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/renesas,usb-xhci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas USB xHCI controllers + +maintainers: + - Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com> + - Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com> + +allOf: + - $ref: "usb-hcd.yaml" + +properties: + compatible: + oneOf: + - items: + - enum: + - renesas,xhci-r8a7742 # RZ/G1H + - renesas,xhci-r8a7743 # RZ/G1M + - renesas,xhci-r8a7744 # RZ/G1N + - renesas,xhci-r8a7790 # R-Car H2 + - renesas,xhci-r8a7791 # R-Car M2-W + - renesas,xhci-r8a7793 # R-Car M2-N + - const: renesas,rcar-gen2-xhci # R-Car Gen2 and RZ/G1 + - items: + - enum: + - renesas,xhci-r8a774a1 # RZ/G2M + - renesas,xhci-r8a774b1 # RZ/G2N + - renesas,xhci-r8a774c0 # RZ/G2E + - renesas,xhci-r8a7795 # R-Car H3 + - renesas,xhci-r8a7796 # R-Car M3-W + - renesas,xhci-r8a77961 # R-Car M3-W+ + - renesas,xhci-r8a77965 # R-Car M3-N + - renesas,xhci-r8a77990 # R-Car E3 + - const: renesas,rcar-gen3-xhci # R-Car Gen3 and RZ/G2 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + phys: + maxItems: 1 + + phy-names: + maxItems: 1 + items: + - const: usb + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + - power-domains + - resets + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a7795-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a7795-sysc.h> + + xhci0: usb@ee000000 { + compatible = "renesas,xhci-r8a7795", "renesas,rcar-gen3-xhci"; + reg = <0xee000000 0xc00>; + interrupts = <GIC_SPI 102 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 328>; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + resets = <&cpg 328>; + }; diff --git a/Documentation/devicetree/bindings/usb/ti,keystone-dwc3.yaml b/Documentation/devicetree/bindings/usb/ti,keystone-dwc3.yaml index f127535feb0b..804b9b4f6654 100644 --- a/Documentation/devicetree/bindings/usb/ti,keystone-dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/ti,keystone-dwc3.yaml @@ -11,22 +11,36 @@ maintainers: properties: compatible: - oneOf: - - const: "ti,keystone-dwc3" - - const: "ti,am654-dwc3" + items: + - enum: + - ti,keystone-dwc3 + - ti,am654-dwc3 reg: maxItems: 1 - description: Address and length of the register set for the USB subsystem on - the SOC. + + '#address-cells': + const: 1 + + '#size-cells': + const: 1 + + ranges: true interrupts: maxItems: 1 - description: The irq number of this device that is used to interrupt the MPU. - clocks: - description: Clock ID for USB functional clock. + minItems: 1 + maxItems: 2 + + assigned-clocks: + minItems: 1 + maxItems: 2 + + assigned-clock-parents: + minItems: 1 + maxItems: 2 power-domains: description: Should contain a phandle to a PM domain provider node @@ -42,33 +56,42 @@ properties: phy-names: items: - - const: "usb3-phy" + - const: usb3-phy + + dma-coherent: true - dwc3: + dma-ranges: true + +patternProperties: + "usb@[a-f0-9]+$": + type: object description: This is the node representing the DWC3 controller instance Documentation/devicetree/bindings/usb/dwc3.txt required: - compatible - reg + - "#address-cells" + - "#size-cells" + - ranges - interrupts - - clocks + +additionalProperties: false examples: - | #include <dt-bindings/interrupt-controller/arm-gic.h> - usb: usb@2680000 { + dwc3@2680000 { compatible = "ti,keystone-dwc3"; #address-cells = <1>; #size-cells = <1>; reg = <0x2680000 0x10000>; clocks = <&clkusb>; - clock-names = "usb"; interrupts = <GIC_SPI 393 IRQ_TYPE_EDGE_RISING>; ranges; - dwc3@2690000 { + usb@2690000 { compatible = "synopsys,dwc3"; reg = <0x2690000 0x70000>; interrupts = <GIC_SPI 393 IRQ_TYPE_EDGE_RISING>; diff --git a/Documentation/devicetree/bindings/usb/usb-xhci.txt b/Documentation/devicetree/bindings/usb/usb-xhci.txt index b120dd6612a2..0c5cff84a969 100644 --- a/Documentation/devicetree/bindings/usb/usb-xhci.txt +++ b/Documentation/devicetree/bindings/usb/usb-xhci.txt @@ -7,24 +7,6 @@ Required properties: - "marvell,armada3700-xhci" for Armada 37xx SoCs - "marvell,armada-375-xhci" for Armada 375 SoCs - "marvell,armada-380-xhci" for Armada 38x SoCs - - "renesas,xhci-r8a7742" for r8a7742 SoC - - "renesas,xhci-r8a7743" for r8a7743 SoC - - "renesas,xhci-r8a7744" for r8a7744 SoC - - "renesas,xhci-r8a774a1" for r8a774a1 SoC - - "renesas,xhci-r8a774b1" for r8a774b1 SoC - - "renesas,xhci-r8a774c0" for r8a774c0 SoC - - "renesas,xhci-r8a7790" for r8a7790 SoC - - "renesas,xhci-r8a7791" for r8a7791 SoC - - "renesas,xhci-r8a7793" for r8a7793 SoC - - "renesas,xhci-r8a7795" for r8a7795 SoC - - "renesas,xhci-r8a7796" for r8a77960 SoC - - "renesas,xhci-r8a77961" for r8a77961 SoC - - "renesas,xhci-r8a77965" for r8a77965 SoC - - "renesas,xhci-r8a77990" for r8a77990 SoC - - "renesas,rcar-gen2-xhci" for a generic R-Car Gen2 or RZ/G1 compatible - device - - "renesas,rcar-gen3-xhci" for a generic R-Car Gen3 or RZ/G2 compatible - device - "brcm,bcm7445-xhci" for Broadcom STB SoCs with XHCI - "xhci-platform" (deprecated) diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index 9aeab66be85f..f3d847832fdc 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -20,13 +20,17 @@ patternProperties: "^(keypad|m25p|max8952|max8997|max8998|mpmc),.*": true "^(pinctrl-single|#pinctrl-single|PowerPC),.*": true "^(pl022|pxa-mmc|rcar_sound|rotary-encoder|s5m8767|sdhci),.*": true - "^(simple-audio-card|simple-graph-card|st-plgpio|st-spics|ts),.*": true + "^(simple-audio-card|st-plgpio|st-spics|ts),.*": true # Keep list in alphabetical order. + "^70mai,.*": + description: 70mai Co., Ltd. "^abilis,.*": description: Abilis Systems "^abracon,.*": description: Abracon Corporation + "^acer,.*": + description: Acer Inc. "^acme,.*": description: Acme Systems srl "^actions,.*": @@ -469,6 +473,8 @@ patternProperties: description: ILI Technology Corporation (ILITEK) "^img,.*": description: Imagination Technologies Ltd. + "^imi,.*": + description: Integrated Micro-Electronics Inc. "^incircuit,.*": description: In-Circuit GmbH "^inet-tek,.*": @@ -680,6 +686,8 @@ patternProperties: description: Microsemi Corporation "^msi,.*": description: Micro-Star International Co. Ltd. + "^mstar,.*": + description: MStar Semiconductor, Inc. (acquired by MediaTek Inc.) "^mti,.*": description: Imagination Technologies Ltd. (formerly MIPS Technologies Inc.) "^multi-inno,.*": @@ -984,6 +992,8 @@ patternProperties: description: Spreadtrum Communications Inc. "^sst,.*": description: Silicon Storage Technology, Inc. + "^sstar,.*": + description: Xiamen Xingchen(SigmaStar) Technology Co., Ltd. (formerly part of MStar Semiconductor, Inc.) "^st,.*": description: STMicroelectronics "^starry,.*": @@ -1032,6 +1042,8 @@ patternProperties: description: Three Five Corp "^thine,.*": description: THine Electronics, Inc. + "^thingyjp,.*": + description: thingy.jp "^ti,.*": description: Texas Instruments "^tianma,.*": @@ -1157,6 +1169,8 @@ patternProperties: description: Xiaomi Technology Co., Ltd. "^xillybus,.*": description: Xillybus Ltd. + "^xingbangda,.*": + description: Shenzhen Xingbangda Display Technology Co., Ltd "^xinpeng,.*": description: Shenzhen Xinpeng Technology Co., Ltd "^xlnx,.*": @@ -1167,6 +1181,8 @@ patternProperties: description: Shenzhen Xunlong Software CO.,Limited "^xylon,.*": description: Xylon + "^ylm,.*": + description: Shenzhen Yangliming Electronic Technology Co., Ltd. "^yna,.*": description: YSH & ATIL "^yones-toptech,.*": diff --git a/Documentation/devicetree/bindings/virtio/mmio.txt b/Documentation/devicetree/bindings/virtio/mmio.txt index 21af30fbb81f..0a575f329f6e 100644 --- a/Documentation/devicetree/bindings/virtio/mmio.txt +++ b/Documentation/devicetree/bindings/virtio/mmio.txt @@ -1,6 +1,6 @@ * virtio memory mapped device -See http://ozlabs.org/~rusty/virtio-spec/ for more details. +See https://ozlabs.org/~rusty/virtio-spec/ for more details. Required properties: diff --git a/Documentation/devicetree/booting-without-of.txt b/Documentation/devicetree/booting-without-of.rst index 4660ccee35a3..e9433350a20f 100644 --- a/Documentation/devicetree/booting-without-of.txt +++ b/Documentation/devicetree/booting-without-of.rst @@ -1,15 +1,19 @@ - Booting the Linux/ppc kernel without Open Firmware - -------------------------------------------------- +.. SPDX-License-Identifier: GPL-2.0 -(c) 2005 Benjamin Herrenschmidt <benh at kernel.crashing.org>, - IBM Corp. -(c) 2005 Becky Bruce <becky.bruce at freescale.com>, - Freescale Semiconductor, FSL SOC and 32-bit additions -(c) 2006 MontaVista Software, Inc. - Flash chip node definition +================================================== +Booting the Linux/ppc kernel without Open Firmware +================================================== -Table of Contents -================= +Copyright (c) 2005 Benjamin Herrenschmidt <benh at kernel.crashing.org>, +IBM Corp. + +Copyright (c) 2005 Becky Bruce <becky.bruce at freescale.com>, +Freescale Semiconductor, FSL SOC and 32-bit additions + +Copyright (c) 2006 MontaVista Software, Inc. +Flash chip node definition + +.. Table of Contents I - Introduction 1) Entry point for arch/arm @@ -61,15 +65,18 @@ Table of Contents Revision Information ==================== - May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet. + May 18, 2005: Rev 0.1 + - Initial draft, no chapter III yet. - May 19, 2005: Rev 0.2 - Add chapter III and bits & pieces here or + May 19, 2005: Rev 0.2 + - Add chapter III and bits & pieces here or clarifies the fact that a lot of things are optional, the kernel only requires a very small device tree, though it is encouraged to provide an as complete one as possible. - May 24, 2005: Rev 0.3 - Precise that DT block has to be in RAM + May 24, 2005: Rev 0.3 + - Precise that DT block has to be in RAM - Misc fixes - Define version 3 and new format version 16 for the DT block (version 16 needs kernel @@ -82,7 +89,8 @@ Revision Information "name" property is now automatically deduced from the unit name - June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and + June 1, 2005: Rev 0.4 + - Correct confusion between OF_DT_END and OF_DT_END_NODE in structure definition. - Change version 16 format to always align property data to 4 bytes. Since tokens are @@ -115,7 +123,7 @@ Revision Information - Compare FSL SOC use of PCI to standard and make sure no new node definition required. - Add more information about node definitions for SOC devices - that currently have no standard, like the FSL CPM. + that currently have no standard, like the FSL CPM. I - Introduction @@ -260,7 +268,7 @@ it with special cases. b) create your main platform file as "arch/powerpc/platforms/myplatform/myboard_setup.c" and add it - to the Makefile under the condition of your CONFIG_ + to the Makefile under the condition of your ``CONFIG_`` option. This file will define a structure of type "ppc_md" containing the various callbacks that the generic code will use to get to your platform specific code @@ -271,7 +279,7 @@ it with special cases. with classic Powerpc architectures. 3) Entry point for arch/x86 -------------------------------- +--------------------------- There is one single 32bit entry point to the kernel at code32_start, the decompressor (the real mode entry point goes to the same 32bit @@ -280,9 +288,9 @@ it with special cases. Documentation/x86/boot.rst The physical pointer to the device-tree block (defined in chapter II) is passed via setup_data which requires at least boot protocol 2.09. - The type filed is defined as + The type filed is defined as:: - #define SETUP_DTB 2 + #define SETUP_DTB 2 This device-tree is used as an extension to the "boot page". As such it does not parse / consider data which is already covered by the boot @@ -354,9 +362,9 @@ the block to RAM before passing it to the kernel. The kernel is passed the physical address pointing to an area of memory that is roughly described in include/linux/of_fdt.h by the structure - boot_param_header: + boot_param_header::: -struct boot_param_header { + struct boot_param_header { u32 magic; /* magic word OF_DT_HEADER */ u32 totalsize; /* total size of DT block */ u32 off_dt_struct; /* offset to structure */ @@ -374,19 +382,19 @@ struct boot_param_header { /* version 17 fields below */ u32 size_dt_struct; /* size of the DT structure block */ -}; + }; - Along with the constants: + Along with the constants:: -/* Definitions used by the flattened device tree */ -#define OF_DT_HEADER 0xd00dfeed /* 4: version, - 4: total size */ -#define OF_DT_BEGIN_NODE 0x1 /* Start node: full name - */ -#define OF_DT_END_NODE 0x2 /* End node */ -#define OF_DT_PROP 0x3 /* Property: name off, - size, content */ -#define OF_DT_END 0x9 + /* Definitions used by the flattened device tree */ + #define OF_DT_HEADER 0xd00dfeed /* 4: version, + 4: total size */ + #define OF_DT_BEGIN_NODE 0x1 /* Start node: full name + */ + #define OF_DT_END_NODE 0x2 /* End node */ + #define OF_DT_PROP 0x3 /* Property: name off, + size, content */ + #define OF_DT_END 0x9 All values in this header are in big endian format, the various fields in this header are defined more precisely below. All @@ -430,7 +438,7 @@ struct boot_param_header { way to avoid overriding critical things like, on Open Firmware capable machines, the RTAS instance, or on some pSeries, the TCE tables used for the iommu. Typically, the reserve map should - contain _at least_ this DT block itself (header,total_size). If + contain **at least** this DT block itself (header,total_size). If you are passing an initrd to the kernel, you should reserve it as well. You do not need to reserve the kernel image itself. The map should be 64-bit aligned. @@ -485,7 +493,7 @@ struct boot_param_header { So the typical layout of a DT block (though the various parts don't need to be in that order) looks like this (addresses go from top to - bottom): + bottom):: ------------------------------ @@ -511,9 +519,9 @@ struct boot_param_header { | --- (base + totalsize) - (*) The alignment gaps are not necessarily present; their presence - and size are dependent on the various alignment requirements of - the individual data blocks. + (*) The alignment gaps are not necessarily present; their presence + and size are dependent on the various alignment requirements of + the individual data blocks. 2) Device tree generalities @@ -600,7 +608,7 @@ discussed in a later chapter. At this point, it is only meant to give you a idea of what a device-tree looks like. I have purposefully kept the "name" and "linux,phandle" properties which aren't necessary in order to give you a better idea of what the tree looks like in -practice. +practice:: / o device-tree |- name = "device-tree" @@ -650,6 +658,7 @@ properties and their content. 3) Device tree "structure" block +-------------------------------- The structure of the device tree is a linearized tree structure. The "OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE" @@ -666,12 +675,14 @@ Here's the basic structure of a single node: root node) * [align gap to next 4 bytes boundary] * for each property: + * token OF_DT_PROP (that is 0x00000003) * 32-bit value of property value size in bytes (or 0 if no value) * 32-bit value of offset in string block of property name * property value data if any * [align gap to next 4 bytes boundary] + * [child nodes if any] * token OF_DT_END_NODE (that is 0x00000002) @@ -688,6 +699,7 @@ manipulating a flattened tree must take care to preserve this constraint. 4) Device tree "strings" block +------------------------------ In order to save space, property names, which are generally redundant, are stored separately in the "strings" block. This block is simply the @@ -700,15 +712,17 @@ strings block. III - Required content of the device tree ========================================= -WARNING: All "linux,*" properties defined in this document apply only -to a flattened device-tree. If your platform uses a real -implementation of Open Firmware or an implementation compatible with -the Open Firmware client interface, those properties will be created -by the trampoline code in the kernel's prom_init() file. For example, -that's where you'll have to add code to detect your board model and -set the platform number. However, when using the flattened device-tree -entry point, there is no prom_init() pass, and thus you have to -provide those properties yourself. +.. Warning:: + + All ``linux,*`` properties defined in this document apply only + to a flattened device-tree. If your platform uses a real + implementation of Open Firmware or an implementation compatible with + the Open Firmware client interface, those properties will be created + by the trampoline code in the kernel's prom_init() file. For example, + that's where you'll have to add code to detect your board model and + set the platform number. However, when using the flattened device-tree + entry point, there is no prom_init() pass, and thus you have to + provide those properties yourself. 1) Note about cells and address representation @@ -769,7 +783,7 @@ addresses), all buses must contain a "ranges" property. If the "ranges" property is missing at a given level, it's assumed that translation isn't possible, i.e., the registers are not visible on the parent bus. The format of the "ranges" property for a bus is a list -of: +of:: bus address, parent bus address, size @@ -877,7 +891,7 @@ address which can extend beyond that limit. This node is the parent of all individual CPU nodes. It doesn't have any specific requirements, though it's generally good practice - to have at least: + to have at least:: #address-cells = <00000001> #size-cells = <00000000> @@ -887,7 +901,7 @@ address which can extend beyond that limit. that format when reading the "reg" properties of a CPU node, see below - c) The /cpus/* nodes + c) The ``/cpus/*`` nodes So under /cpus, you are supposed to create a node for every CPU on the machine. There is no specific restriction on the name of the @@ -903,21 +917,23 @@ address which can extend beyond that limit. - reg : This is the physical CPU number, it's a single 32-bit cell and is also used as-is as the unit number for constructing the unit name in the full path. For example, with 2 CPUs, you would - have the full path: + have the full path:: + /cpus/PowerPC,970FX@0 /cpus/PowerPC,970FX@1 + (unit addresses do not require leading zeroes) - - d-cache-block-size : one cell, L1 data cache block size in bytes (*) + - d-cache-block-size : one cell, L1 data cache block size in bytes [#]_ - i-cache-block-size : one cell, L1 instruction cache block size in bytes - d-cache-size : one cell, size of L1 data cache in bytes - i-cache-size : one cell, size of L1 instruction cache in bytes -(*) The cache "block" size is the size on which the cache management -instructions operate. Historically, this document used the cache -"line" size here which is incorrect. The kernel will prefer the cache -block size and will fallback to cache line size for backward -compatibility. + .. [#] The cache "block" size is the size on which the cache management + instructions operate. Historically, this document used the cache + "line" size here which is incorrect. The kernel will prefer the cache + block size and will fallback to cache line size for backward + compatibility. Recommended properties: @@ -963,10 +979,10 @@ compatibility. #address-cells and #size-cells of the root node. For example, with both of these properties being 2 like in the example given earlier, a 970 based machine with 6Gb of RAM could typically - have a "reg" property here that looks like: + have a "reg" property here that looks like:: - 00000000 00000000 00000000 80000000 - 00000001 00000000 00000001 00000000 + 00000000 00000000 00000000 80000000 + 00000001 00000000 00000001 00000000 That is a range starting at 0 of 0x80000000 bytes and a range starting at 0x100000000 and of 0x100000000 bytes. You can see @@ -1047,18 +1063,18 @@ compatibility. See 1) above for more details on defining #address-cells. - #size-cells : Size representation for "soc" devices - #interrupt-cells : Defines the width of cells used to represent - interrupts. Typically this value is <2>, which includes a - 32-bit number that represents the interrupt number, and a - 32-bit number that represents the interrupt sense and level. - This field is only needed if the SOC contains an interrupt - controller. + interrupts. Typically this value is <2>, which includes a + 32-bit number that represents the interrupt number, and a + 32-bit number that represents the interrupt sense and level. + This field is only needed if the SOC contains an interrupt + controller. The SOC node may contain child nodes for each SOC device that the platform uses. Nodes should not be created for devices which exist on the SOC but are not used by a particular platform. See chapter VI for more information on how to specify devices that are part of a SOC. - Example SOC node for the MPC8540: + Example SOC node for the MPC8540:: soc8540@e0000000 { #address-cells = <1>; @@ -1079,31 +1095,33 @@ IV - "dtc", the device tree compiler dtc source code can be found at <http://git.jdl.com/gitweb/?p=dtc.git> -WARNING: This version is still in early development stage; the -resulting device-tree "blobs" have not yet been validated with the -kernel. The current generated block lacks a useful reserve map (it will -be fixed to generate an empty one, it's up to the bootloader to fill -it up) among others. The error handling needs work, bugs are lurking, -etc... +.. Warning:: + + This version is still in early development stage; the + resulting device-tree "blobs" have not yet been validated with the + kernel. The current generated block lacks a useful reserve map (it will + be fixed to generate an empty one, it's up to the bootloader to fill + it up) among others. The error handling needs work, bugs are lurking, + etc... dtc basically takes a device-tree in a given format and outputs a device-tree in another format. The currently supported formats are: - Input formats: - ------------- +Input formats +------------- - "dtb": "blob" format, that is a flattened device-tree block with - header all in a binary blob. + header all in a binary blob. - "dts": "source" format. This is a text file containing a "source" for a device-tree. The format is defined later in this - chapter. + chapter. - "fs" format. This is a representation equivalent to the - output of /proc/device-tree, that is nodes are directories and - properties are files + output of /proc/device-tree, that is nodes are directories and + properties are files - Output formats: - --------------- +Output formats +-------------- - "dtb": "blob" format - "dts": "source" format @@ -1113,7 +1131,7 @@ device-tree in another format. The currently supported formats are: assembly file exports some symbols that can be used. -The syntax of the dtc tool is +The syntax of the dtc tool is:: dtc [-I <input-format>] [-O <output-format>] [-o output-filename] [-V output_version] input_filename @@ -1127,43 +1145,45 @@ Additionally, dtc performs various sanity checks on the tree, like the uniqueness of linux, phandle properties, validity of strings, etc... The format of the .dts "source" file is "C" like, supports C and C++ -style comments. +style comments:: -/ { -} + / { + } The above is the "device-tree" definition. It's the only statement supported currently at the toplevel. -/ { - property1 = "string_value"; /* define a property containing a 0 - * terminated string - */ - - property2 = <0x1234abcd>; /* define a property containing a - * numerical 32-bit value (hexadecimal) - */ - - property3 = <0x12345678 0x12345678 0xdeadbeef>; - /* define a property containing 3 - * numerical 32-bit values (cells) in - * hexadecimal - */ - property4 = [0x0a 0x0b 0x0c 0x0d 0xde 0xea 0xad 0xbe 0xef]; - /* define a property whose content is - * an arbitrary array of bytes - */ - - childnode@address { /* define a child node named "childnode" - * whose unit name is "childnode at - * address" - */ - - childprop = "hello\n"; /* define a property "childprop" of - * childnode (in this case, a string) - */ - }; -}; +:: + + / { + property1 = "string_value"; /* define a property containing a 0 + * terminated string + */ + + property2 = <0x1234abcd>; /* define a property containing a + * numerical 32-bit value (hexadecimal) + */ + + property3 = <0x12345678 0x12345678 0xdeadbeef>; + /* define a property containing 3 + * numerical 32-bit values (cells) in + * hexadecimal + */ + property4 = [0x0a 0x0b 0x0c 0x0d 0xde 0xea 0xad 0xbe 0xef]; + /* define a property whose content is + * an arbitrary array of bytes + */ + + childnode@address { /* define a child node named "childnode" + * whose unit name is "childnode at + * address" + */ + + childprop = "hello\n"; /* define a property "childprop" of + * childnode (in this case, a string) + */ + }; + }; Nodes can contain other nodes etc... thus defining the hierarchical structure of the tree. @@ -1322,7 +1342,7 @@ phandle of the parent node. If the interrupt-parent property is not defined for a node, its interrupt parent is assumed to be an ancestor in the node's -_device tree_ hierarchy. +*device tree* hierarchy. 3) OpenPIC Interrupt Controllers -------------------------------- @@ -1334,10 +1354,12 @@ information. Sense and level information should be encoded as follows: - 0 = low to high edge sensitive type enabled - 1 = active low level sensitive type enabled - 2 = active high level sensitive type enabled - 3 = high to low edge sensitive type enabled + == ======================================== + 0 low to high edge sensitive type enabled + 1 active low level sensitive type enabled + 2 active high level sensitive type enabled + 3 high to low edge sensitive type enabled + == ======================================== 4) ISA Interrupt Controllers ---------------------------- @@ -1350,13 +1372,15 @@ information. ISA PIC interrupt controllers should adhere to the ISA PIC encodings listed below: - 0 = active low level sensitive type enabled - 1 = active high level sensitive type enabled - 2 = high to low edge sensitive type enabled - 3 = low to high edge sensitive type enabled + == ======================================== + 0 active low level sensitive type enabled + 1 active high level sensitive type enabled + 2 high to low edge sensitive type enabled + 3 low to high edge sensitive type enabled + == ======================================== VIII - Specifying Device Power Management Information (sleep property) -=================================================================== +====================================================================== Devices on SOCs often have mechanisms for placing devices into low-power states that are decoupled from the devices' own register blocks. Sometimes, @@ -1387,6 +1411,7 @@ reasonably grouped in this manner, then create a virtual sleep controller sleep-map should wait until its necessity is demonstrated). IX - Specifying dma bus information +=================================== Some devices may have DMA memory range shifted relatively to the beginning of RAM, or even placed outside of kernel RAM. For example, the Keystone 2 SoC @@ -1404,25 +1429,30 @@ coherent DMA operations. The "dma-coherent" property is intended to be used for identifying devices supported coherent DMA operations in DT. * DMA Bus master + Optional property: + - dma-ranges: <prop-encoded-array> encoded as arbitrary number of triplets of - (child-bus-address, parent-bus-address, length). Each triplet specified - describes a contiguous DMA address range. - The dma-ranges property is used to describe the direct memory access (DMA) - structure of a memory-mapped bus whose device tree parent can be accessed - from DMA operations originating from the bus. It provides a means of - defining a mapping or translation between the physical address space of - the bus and the physical address space of the parent of the bus. - (for more information see the Devicetree Specification) + (child-bus-address, parent-bus-address, length). Each triplet specified + describes a contiguous DMA address range. + The dma-ranges property is used to describe the direct memory access (DMA) + structure of a memory-mapped bus whose device tree parent can be accessed + from DMA operations originating from the bus. It provides a means of + defining a mapping or translation between the physical address space of + the bus and the physical address space of the parent of the bus. + (for more information see the Devicetree Specification) * DMA Bus child + Optional property: + - dma-ranges: <empty> value. if present - It means that DMA addresses - translation has to be enabled for this device. + translation has to be enabled for this device. - dma-coherent: Present if dma operations are coherent -Example: -soc { +Example:: + + soc { compatible = "ti,keystone","simple-bus"; ranges = <0x0 0x0 0x0 0xc0000000>; dma-ranges = <0x80000000 0x8 0x00000000 0x80000000>; @@ -1435,11 +1465,13 @@ soc { [...] dma-coherent; }; -}; + }; Appendix A - Sample SOC node for MPC8540 ======================================== +:: + soc@e0000000 { #address-cells = <1>; #size-cells = <1>; diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index 54026763916d..d2a96e1af23e 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -15,3 +15,4 @@ Open Firmware and Device Tree overlay-notes bindings/index + booting-without-of diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/writing-schema.rst index 220cf464ed77..8c74a99f95e2 100644 --- a/Documentation/devicetree/writing-schema.rst +++ b/Documentation/devicetree/writing-schema.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 Writing DeviceTree Bindings in json-schema ========================================== @@ -124,9 +124,12 @@ dtc must also be built with YAML output support enabled. This requires that libyaml and its headers be installed on the host system. For some distributions that involves installing the development package, such as: -Debian: +Debian:: + apt-get install libyaml-dev -Fedora: + +Fedora:: + dnf -y install libyaml-devel Running checks diff --git a/Documentation/dontdiff b/Documentation/dontdiff index ef9519c32c55..e361fc95ca29 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff @@ -55,6 +55,7 @@ *.ver *.xml *.xz +*.zst *_MODULES *_vga16.c *~ diff --git a/Documentation/driver-api/connector.rst b/Documentation/driver-api/connector.rst index c100c7482289..23d068191fb1 100644 --- a/Documentation/driver-api/connector.rst +++ b/Documentation/driver-api/connector.rst @@ -26,7 +26,7 @@ netlink based networking for inter-process communication in a significantly easier way:: int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *)); - void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask); + void cn_netlink_send_mult(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask); void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask); struct cb_id @@ -48,7 +48,8 @@ be dereferenced to `struct cn_msg *`:: __u32 seq; __u32 ack; - __u32 len; /* Length of the following data */ + __u16 len; /* Length of the following data */ + __u16 flags; __u8 data[0]; }; diff --git a/Documentation/driver-api/device-io.rst b/Documentation/driver-api/device-io.rst index 0e389378f71d..764963876d08 100644 --- a/Documentation/driver-api/device-io.rst +++ b/Documentation/driver-api/device-io.rst @@ -36,14 +36,14 @@ are starting with one. Physical addresses are of type unsigned long. This address should not be used directly. Instead, to get an address suitable for passing to the accessor functions described below, you -should call :c:func:`ioremap()`. An address suitable for accessing +should call ioremap(). An address suitable for accessing the device will be returned to you. After you've finished using the device (say, in your module's exit -routine), call :c:func:`iounmap()` in order to return the address +routine), call iounmap() in order to return the address space to the kernel. Most architectures allocate new address space each -time you call :c:func:`ioremap()`, and they can run out unless you -call :c:func:`iounmap()`. +time you call ioremap(), and they can run out unless you +call iounmap(). Accessing the device -------------------- @@ -60,8 +60,8 @@ readb_relaxed(), readw_relaxed(), readl_relaxed(), readq_relaxed(), writeb(), writew(), writel() and writeq(). Some devices (such as framebuffers) would like to use larger transfers than -8 bytes at a time. For these devices, the :c:func:`memcpy_toio()`, -:c:func:`memcpy_fromio()` and :c:func:`memset_io()` functions are +8 bytes at a time. For these devices, the memcpy_toio(), +memcpy_fromio() and memset_io() functions are provided. Do not use memset or memcpy on IO addresses; they are not guaranteed to copy data in order. @@ -135,15 +135,15 @@ Accessing Port Space Accesses to this space are provided through a set of functions which allow 8-bit, 16-bit and 32-bit accesses; also known as byte, word and -long. These functions are :c:func:`inb()`, :c:func:`inw()`, -:c:func:`inl()`, :c:func:`outb()`, :c:func:`outw()` and -:c:func:`outl()`. +long. These functions are inb(), inw(), +inl(), outb(), outw() and +outl(). Some variants are provided for these functions. Some devices require that accesses to their ports are slowed down. This functionality is provided by appending a ``_p`` to the end of the function. -There are also equivalents to memcpy. The :c:func:`ins()` and -:c:func:`outs()` functions copy bytes, words or longs to the given +There are also equivalents to memcpy. The ins() and +outs() functions copy bytes, words or longs to the given port. Public Functions Provided diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index 63dec76d1d8d..100bfd227265 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -100,11 +100,11 @@ CPU Access to DMA Buffer Objects .. kernel-doc:: drivers/dma-buf/dma-buf.c :doc: cpu access -Fence Poll Support -~~~~~~~~~~~~~~~~~~ +Implicit Fence Poll Support +~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. kernel-doc:: drivers/dma-buf/dma-buf.c - :doc: fence polling + :doc: implicit fence polling Kernel Functions and Structures Reference ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -133,6 +133,18 @@ DMA Fences .. kernel-doc:: drivers/dma-buf/dma-fence.c :doc: DMA fences overview +DMA Fence Cross-Driver Contract +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/dma-buf/dma-fence.c + :doc: fence cross-driver contract + +DMA Fence Signalling Annotations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/dma-buf/dma-fence.c + :doc: fence signalling annotation + DMA Fences Functions Reference ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -166,3 +178,73 @@ DMA Fence uABI/Sync File .. kernel-doc:: include/linux/sync_file.h :internal: +Indefinite DMA Fences +~~~~~~~~~~~~~~~~~~~~ + +At various times &dma_fence with an indefinite time until dma_fence_wait() +finishes have been proposed. Examples include: + +* Future fences, used in HWC1 to signal when a buffer isn't used by the display + any longer, and created with the screen update that makes the buffer visible. + The time this fence completes is entirely under userspace's control. + +* Proxy fences, proposed to handle &drm_syncobj for which the fence has not yet + been set. Used to asynchronously delay command submission. + +* Userspace fences or gpu futexes, fine-grained locking within a command buffer + that userspace uses for synchronization across engines or with the CPU, which + are then imported as a DMA fence for integration into existing winsys + protocols. + +* Long-running compute command buffers, while still using traditional end of + batch DMA fences for memory management instead of context preemption DMA + fences which get reattached when the compute job is rescheduled. + +Common to all these schemes is that userspace controls the dependencies of these +fences and controls when they fire. Mixing indefinite fences with normal +in-kernel DMA fences does not work, even when a fallback timeout is included to +protect against malicious userspace: + +* Only the kernel knows about all DMA fence dependencies, userspace is not aware + of dependencies injected due to memory management or scheduler decisions. + +* Only userspace knows about all dependencies in indefinite fences and when + exactly they will complete, the kernel has no visibility. + +Furthermore the kernel has to be able to hold up userspace command submission +for memory management needs, which means we must support indefinite fences being +dependent upon DMA fences. If the kernel also support indefinite fences in the +kernel like a DMA fence, like any of the above proposal would, there is the +potential for deadlocks. + +.. kernel-render:: DOT + :alt: Indefinite Fencing Dependency Cycle + :caption: Indefinite Fencing Dependency Cycle + + digraph "Fencing Cycle" { + node [shape=box bgcolor=grey style=filled] + kernel [label="Kernel DMA Fences"] + userspace [label="userspace controlled fences"] + kernel -> userspace [label="memory management"] + userspace -> kernel [label="Future fence, fence proxy, ..."] + + { rank=same; kernel userspace } + } + +This means that the kernel might accidentally create deadlocks +through memory management dependencies which userspace is unaware of, which +randomly hangs workloads until the timeout kicks in. Workloads, which from +userspace's perspective, do not contain a deadlock. In such a mixed fencing +architecture there is no single entity with knowledge of all dependencies. +Thefore preventing such deadlocks from within the kernel is not possible. + +The only solution to avoid dependencies loops is by not allowing indefinite +fences in the kernel. This means: + +* No future fences, proxy fences or userspace fences imported as DMA fences, + with or without a timeout. + +* No DMA fences that signal end of batchbuffer for command submission where + userspace is allowed to use userspace fencing or long running compute + workloads. This also means no implicit fencing for shared buffers in these + cases. diff --git a/Documentation/driver-api/dmaengine/client.rst b/Documentation/driver-api/dmaengine/client.rst index 2104830a99ae..09a3f66dcd26 100644 --- a/Documentation/driver-api/dmaengine/client.rst +++ b/Documentation/driver-api/dmaengine/client.rst @@ -5,7 +5,7 @@ DMA Engine API Guide Vinod Koul <vinod dot koul at intel.com> .. note:: For DMA Engine usage in async_tx please see: - ``Documentation/crypto/async-tx-api.txt`` + ``Documentation/crypto/async-tx-api.rst`` Below is a guide to device driver writers on how to use the Slave-DMA API of the @@ -86,7 +86,9 @@ The details of these operations are: - interleaved_dma: This is common to Slave as well as M2M clients. For slave address of devices' fifo could be already known to the driver. Various types of operations could be expressed by setting - appropriate values to the 'dma_interleaved_template' members. + appropriate values to the 'dma_interleaved_template' members. Cyclic + interleaved DMA transfers are also possible if supported by the channel by + setting the DMA_PREP_REPEAT transfer flag. A non-NULL return of this transfer API represents a "descriptor" for the given transaction. diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst index 56e5833e8a07..ddb0a81a796c 100644 --- a/Documentation/driver-api/dmaengine/provider.rst +++ b/Documentation/driver-api/dmaengine/provider.rst @@ -95,7 +95,7 @@ accommodates that API in some cases, and made some design choices to ensure that it stayed compatible. For more information on the Async TX API, please look the relevant -documentation file in Documentation/crypto/async-tx-api.txt. +documentation file in Documentation/crypto/async-tx-api.rst. DMAEngine APIs ============== @@ -239,6 +239,43 @@ Currently, the types available are: want to transfer a portion of uncompressed data directly to the display to print it +- DMA_COMPLETION_NO_ORDER + + - The device does not support in order completion. + + - The driver should return DMA_OUT_OF_ORDER for device_tx_status if + the device is setting this capability. + + - All cookie tracking and checking API should be treated as invalid if + the device exports this capability. + + - At this point, this is incompatible with polling option for dmatest. + + - If this cap is set, the user is recommended to provide an unique + identifier for each descriptor sent to the DMA device in order to + properly track the completion. + +- DMA_REPEAT + + - The device supports repeated transfers. A repeated transfer, indicated by + the DMA_PREP_REPEAT transfer flag, is similar to a cyclic transfer in that + it gets automatically repeated when it ends, but can additionally be + replaced by the client. + + - This feature is limited to interleaved transfers, this flag should thus not + be set if the DMA_INTERLEAVE flag isn't set. This limitation is based on + the current needs of DMA clients, support for additional transfer types + should be added in the future if and when the need arises. + +- DMA_LOAD_EOT + + - The device supports replacing repeated transfers at end of transfer (EOT) + by queuing a new transfer with the DMA_PREP_LOAD_EOT flag set. + + - Support for replacing a currently running transfer at another point (such + as end of burst instead of end of transfer) will be added in the future + based on DMA clients needs, if and when the need arises. + These various types will also affect how the source and destination addresses change over time. @@ -399,6 +436,9 @@ supported. - In the case of a cyclic transfer, it should only take into account the current period. + - Should return DMA_OUT_OF_ORDER if the device does not support in order + completion and is completing the operation out of order. + - This function can be called in an interrupt context. - device_config @@ -488,7 +528,7 @@ dma_cookie_t DMA_CTRL_ACK - If clear, the descriptor cannot be reused by provider until the - client acknowledges receipt, i.e. has has a chance to establish any + client acknowledges receipt, i.e. has a chance to establish any dependency chains - This can be acked by invoking async_tx_ack() @@ -531,6 +571,34 @@ DMA_CTRL_REUSE writes for which the descriptor should be in different format from normal data descriptors. +- DMA_PREP_REPEAT + + - If set, the transfer will be automatically repeated when it ends until a + new transfer is queued on the same channel with the DMA_PREP_LOAD_EOT flag. + If the next transfer to be queued on the channel does not have the + DMA_PREP_LOAD_EOT flag set, the current transfer will be repeated until the + client terminates all transfers. + + - This flag is only supported if the channel reports the DMA_REPEAT + capability. + +- DMA_PREP_LOAD_EOT + + - If set, the transfer will replace the transfer currently being executed at + the end of the transfer. + + - This is the default behaviour for non-repeated transfers, specifying + DMA_PREP_LOAD_EOT for non-repeated transfers will thus make no difference. + + - When using repeated transfers, DMA clients will usually need to set the + DMA_PREP_LOAD_EOT flag on all transfers, otherwise the channel will keep + repeating the last repeated transfer and ignore the new transfers being + queued. Failure to set DMA_PREP_LOAD_EOT will appear as if the channel was + stuck on the previous transfer. + + - This flag is only supported if the channel reports the DMA_LOAD_EOT + capability. + General Design Notes ==================== diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst index e0b58c392e4f..eaaaafc21134 100644 --- a/Documentation/driver-api/driver-model/devres.rst +++ b/Documentation/driver-api/driver-model/devres.rst @@ -342,7 +342,8 @@ LED MDIO devm_mdiobus_alloc() devm_mdiobus_alloc_size() - devm_mdiobus_free() + devm_mdiobus_register() + devm_of_mdiobus_register() MEM devm_free_pages() diff --git a/Documentation/driver-api/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst index 7d5040f6a3d8..06f818b1d622 100644 --- a/Documentation/driver-api/driver-model/driver.rst +++ b/Documentation/driver-api/driver-model/driver.rst @@ -228,8 +228,6 @@ over management of devices from the bootloader, the usage of sync_state() is not restricted to that. Use it whenever it makes sense to take an action after all the consumers of a device have probed:: -:: - int (*remove) (struct device *dev); remove is called to unbind a driver from a device. This may be diff --git a/Documentation/driver-api/driver-model/platform.rst b/Documentation/driver-api/driver-model/platform.rst index 334dd4071ae4..1fe5c6c6199c 100644 --- a/Documentation/driver-api/driver-model/platform.rst +++ b/Documentation/driver-api/driver-model/platform.rst @@ -108,7 +108,7 @@ field to hold additional information. Embedded systems frequently need one or more clocks for platform devices, which are normally kept off until they're actively needed (to save power). -System setup also associates those clocks with the device, so that that +System setup also associates those clocks with the device, so that calls to clk_get(&pdev->dev, clock_name) return them as needed. diff --git a/Documentation/driver-api/early-userspace/early_userspace_support.rst b/Documentation/driver-api/early-userspace/early_userspace_support.rst index 3deefb34046b..8a58c61932ff 100644 --- a/Documentation/driver-api/early-userspace/early_userspace_support.rst +++ b/Documentation/driver-api/early-userspace/early_userspace_support.rst @@ -92,7 +92,7 @@ You can obtain somewhat infrequent snapshots of klibc from https://www.kernel.org/pub/linux/libs/klibc/ For active users, you are better off using the klibc git -repository, at http://git.kernel.org/?p=libs/klibc/klibc.git +repository, at https://git.kernel.org/?p=libs/klibc/klibc.git The standalone klibc distribution currently provides three components, in addition to the klibc library: @@ -122,7 +122,7 @@ and a number of other utilities, so you can replace kinit and build custom initramfs images that meet your needs exactly. For questions and help, you can sign up for the early userspace -mailing list at http://www.zytor.com/mailman/listinfo/klibc +mailing list at https://www.zytor.com/mailman/listinfo/klibc How does it work? ================= diff --git a/Documentation/driver-api/firmware/built-in-fw.rst b/Documentation/driver-api/firmware/built-in-fw.rst index 396cdf591ac5..bc1c961bace1 100644 --- a/Documentation/driver-api/firmware/built-in-fw.rst +++ b/Documentation/driver-api/firmware/built-in-fw.rst @@ -28,6 +28,6 @@ able to make use of built-in firmware: * Some firmware files may be really large in size. The remote-proc subsystem is an example subsystem which deals with these sorts of firmware * The firmware may need to be scraped out from some device specific location - dynamically, an example is calibration data for for some WiFi chipsets. This + dynamically, an example is calibration data for some WiFi chipsets. This calibration data can be unique per sold device. diff --git a/Documentation/driver-api/firmware/direct-fs-lookup.rst b/Documentation/driver-api/firmware/direct-fs-lookup.rst index 82b4d585a213..e04353d1b06b 100644 --- a/Documentation/driver-api/firmware/direct-fs-lookup.rst +++ b/Documentation/driver-api/firmware/direct-fs-lookup.rst @@ -24,7 +24,7 @@ available. Stuffing the firmware into initramfs resolves this race issue, however note that using initrd does not suffice to address the same race. There are circumstances that justify not wanting to include firmware into -initramfs, such as dealing with large firmware firmware files for the +initramfs, such as dealing with large firmware files for the remote-proc subsystem. For such cases using a userspace fallback mechanism is currently the only viable solution as only userspace can know for sure when the real rootfs is ready and mounted. diff --git a/Documentation/driver-api/firmware/firmware_cache.rst b/Documentation/driver-api/firmware/firmware_cache.rst index c2e69d9c6bf1..417b9e8347f0 100644 --- a/Documentation/driver-api/firmware/firmware_cache.rst +++ b/Documentation/driver-api/firmware/firmware_cache.rst @@ -27,7 +27,7 @@ Some implementation details about the firmware cache setup: uses all synchronous call except :c:func:`request_firmware_into_buf`. * If an asynchronous call is used the firmware cache is only set up for a - device if if the second argument (uevent) to request_firmware_nowait() is + device if the second argument (uevent) to request_firmware_nowait() is true. When uevent is true it requests that a kobject uevent be sent to userspace for the firmware request through the sysfs fallback mechanism if the firmware file is not found. diff --git a/Documentation/driver-api/firmware/request_firmware.rst b/Documentation/driver-api/firmware/request_firmware.rst index cd076462d235..0d6ea0329995 100644 --- a/Documentation/driver-api/firmware/request_firmware.rst +++ b/Documentation/driver-api/firmware/request_firmware.rst @@ -76,5 +76,5 @@ firmware. For example if you used request_firmware() and it returns, the driver has the firmware image accessible in fw_entry->{data,size}. If something went wrong request_firmware() returns non-zero and fw_entry is set to NULL. Once your driver is done with processing the firmware it -can call call release_firmware(fw_entry) to release the firmware image +can call release_firmware(fw_entry) to release the firmware image and any related resource. diff --git a/Documentation/driver-api/generic-counter.rst b/Documentation/driver-api/generic-counter.rst index e622f8f6e56a..b02c52cd69d6 100644 --- a/Documentation/driver-api/generic-counter.rst +++ b/Documentation/driver-api/generic-counter.rst @@ -262,7 +262,7 @@ the system. Counter Counts may be allocated via counter_count structures, and respective Counter Signal associations (Synapses) made via counter_synapse structures. Associated counter_synapse structures are -stored as an array and set to the the synapses array member of the +stored as an array and set to the synapses array member of the respective counter_count structure. These counter_count structures are set to the counts array member of an allocated counter_device structure before the Counter is registered to the system. diff --git a/Documentation/driver-api/gpio/drivers-on-gpio.rst b/Documentation/driver-api/gpio/drivers-on-gpio.rst index 820b403d50f6..41ec3cc72d32 100644 --- a/Documentation/driver-api/gpio/drivers-on-gpio.rst +++ b/Documentation/driver-api/gpio/drivers-on-gpio.rst @@ -89,6 +89,13 @@ hardware descriptions such as device tree or ACPI: Consumer Electronics Control bus using only GPIO. It is used to communicate with devices on the HDMI bus. +- gpio-charger: drivers/power/supply/gpio-charger.c is used if you need to do + battery charging and all you have to go by to check the presence of the + AC charger or more complex tasks such as indicating charging status using + nothing but GPIO lines, this driver provides that and also a clearly defined + way to pass the charging parameters from hardware descriptions such as the + device tree. + Apart from this there are special GPIO drivers in subsystems like MMC/SD to read card detect and write protect GPIO lines, and in the TTY serial subsystem to emulate MCTRL (modem control) signals CTS/RTS by using two GPIO lines. The diff --git a/Documentation/driver-api/i3c/protocol.rst b/Documentation/driver-api/i3c/protocol.rst index dae3b6d32c6b..02653defa011 100644 --- a/Documentation/driver-api/i3c/protocol.rst +++ b/Documentation/driver-api/i3c/protocol.rst @@ -14,7 +14,7 @@ collisions are prevented, ...) please have a look at the I3C specification. This document is just a brief introduction to the I3C protocol and the concepts it brings to the table. If you need more information, please refer to the MIPI I3C specification (can be downloaded here -http://resources.mipi.org/mipi-i3c-v1-download). +https://resources.mipi.org/mipi-i3c-v1-download). Introduction ============ diff --git a/Documentation/driver-api/iio/buffers.rst b/Documentation/driver-api/iio/buffers.rst index e9036ef9f8f4..dd64c9c5fb1e 100644 --- a/Documentation/driver-api/iio/buffers.rst +++ b/Documentation/driver-api/iio/buffers.rst @@ -88,7 +88,7 @@ fields in iio_chan_spec definition:: The driver implementing the accelerometer described above will have the following channel definition:: - struct struct iio_chan_spec accel_channels[] = { + struct iio_chan_spec accel_channels[] = { { .type = IIO_ACCEL, .modified = 1, diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 6567187e7687..902b93b17235 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -48,6 +48,7 @@ available subsections can be seen below. scsi libata target + mailbox mtdnand miscellaneous mei/index @@ -95,6 +96,7 @@ available subsections can be seen below. phy/index pti_intel_mid pwm + pldmfw/index rfkill serial/index sm501 diff --git a/Documentation/driver-api/ipmi.rst b/Documentation/driver-api/ipmi.rst index 5ef1047e2e66..292f587fccdd 100644 --- a/Documentation/driver-api/ipmi.rst +++ b/Documentation/driver-api/ipmi.rst @@ -18,7 +18,7 @@ management software that can use the IPMI system. This document describes how to use the IPMI driver for Linux. If you are not familiar with IPMI itself, see the web site at -http://www.intel.com/design/servers/ipmi/index.htm. IPMI is a big +https://www.intel.com/design/servers/ipmi/index.htm. IPMI is a big subject and I can't cover it all here! Configuration diff --git a/Documentation/mailbox.txt b/Documentation/driver-api/mailbox.rst index 0ed95009cc30..0ed95009cc30 100644 --- a/Documentation/mailbox.txt +++ b/Documentation/driver-api/mailbox.rst diff --git a/Documentation/driver-api/media/drivers/pvrusb2.rst b/Documentation/driver-api/media/drivers/pvrusb2.rst index 83bfaa531ea8..cbd9359c247a 100644 --- a/Documentation/driver-api/media/drivers/pvrusb2.rst +++ b/Documentation/driver-api/media/drivers/pvrusb2.rst @@ -20,7 +20,7 @@ last known snapshot and evolved the driver to the state it is in here. More information on this driver can be found at: -http://www.isely.net/pvrusb2.html +https://www.isely.net/pvrusb2.html This driver has a strong separation of layers. They are very diff --git a/Documentation/driver-api/media/drivers/tuners.rst b/Documentation/driver-api/media/drivers/tuners.rst index 7509be888909..d7924141c544 100644 --- a/Documentation/driver-api/media/drivers/tuners.rst +++ b/Documentation/driver-api/media/drivers/tuners.rst @@ -18,7 +18,7 @@ These differ mainly by the bandswitch byte. Tuner Manufacturers ------------------- -- SAMSUNG Tuner identification: (e.g. TCPM9091PD27) +- Samsung Tuner identification: (e.g. TCPM9091PD27) .. code-block:: none diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst index 6e71f67455bb..bc7e1fc40a9d 100644 --- a/Documentation/driver-api/media/v4l2-subdev.rst +++ b/Documentation/driver-api/media/v4l2-subdev.rst @@ -451,7 +451,7 @@ The bridge driver also has some helper functions it can use: "module_foo", "chipid", 0x36, NULL); This loads the given module (can be ``NULL`` if no module needs to be loaded) -and calls :c:func:`i2c_new_device` with the given ``i2c_adapter`` and +and calls :c:func:`i2c_new_client_device` with the given ``i2c_adapter`` and chip/address arguments. If all goes well, then it registers the subdev with the v4l2_device. diff --git a/Documentation/driver-api/memory-devices/ti-gpmc.rst b/Documentation/driver-api/memory-devices/ti-gpmc.rst index 33efcb81f080..b1bb86871ad7 100644 --- a/Documentation/driver-api/memory-devices/ti-gpmc.rst +++ b/Documentation/driver-api/memory-devices/ti-gpmc.rst @@ -14,7 +14,7 @@ memory devices like * Pseudo-SRAM devices GPMC is found on Texas Instruments SoC's (OMAP based) -IP details: http://www.ti.com/lit/pdf/spruh73 section 7.1 +IP details: https://www.ti.com/lit/pdf/spruh73 section 7.1 GPMC generic timing calculation: diff --git a/Documentation/driver-api/mmc/mmc-tools.rst b/Documentation/driver-api/mmc/mmc-tools.rst index 54406093768b..a231e9644351 100644 --- a/Documentation/driver-api/mmc/mmc-tools.rst +++ b/Documentation/driver-api/mmc/mmc-tools.rst @@ -5,7 +5,7 @@ MMC tools introduction There is one MMC test tools called mmc-utils, which is maintained by Chris Ball, you can find it at the below public git repository: - http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/ + https://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/ Functions ========= diff --git a/Documentation/driver-api/ntb.rst b/Documentation/driver-api/ntb.rst index 87d1372da879..11577c2105c5 100644 --- a/Documentation/driver-api/ntb.rst +++ b/Documentation/driver-api/ntb.rst @@ -9,7 +9,7 @@ registers and memory translation windows, as well as non common features like scratchpad and message registers. Scratchpad registers are read-and-writable registers that are accessible from either side of the device, so that peers can exchange a small amount of information at a fixed address. Message registers can -be utilized for the same purpose. Additionally they are provided with with +be utilized for the same purpose. Additionally they are provided with special status bits to make sure the information isn't rewritten by another peer. Doorbell registers provide a way for peers to send interrupt events. Memory windows allow translated read and write access to the peer memory. diff --git a/Documentation/driver-api/nvdimm/nvdimm.rst b/Documentation/driver-api/nvdimm/nvdimm.rst index 79c0fd39f2af..ef6d59e0978e 100644 --- a/Documentation/driver-api/nvdimm/nvdimm.rst +++ b/Documentation/driver-api/nvdimm/nvdimm.rst @@ -73,7 +73,7 @@ DAX: process address space. DSM: - Device Specific Method: ACPI method to to control specific + Device Specific Method: ACPI method to control specific device - in this case the firmware. DCR: @@ -113,13 +113,13 @@ Supporting Documents -------------------- ACPI 6: - http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf + https://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf NVDIMM Namespace: - http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf + https://pmem.io/documents/NVDIMM_Namespace_Spec.pdf DSM Interface Example: - http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf + https://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf Driver Writer's Guide: - http://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf + https://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf Git Trees --------- @@ -778,7 +778,7 @@ Why the Term "namespace"? 2. The term originated to describe the sub-devices that can be created within a NVME controller (see the nvme specification: - http://www.nvmexpress.org/specifications/), and NFIT namespaces are + https://www.nvmexpress.org/specifications/), and NFIT namespaces are meant to parallel the capabilities and configurability of NVME-namespaces. @@ -786,7 +786,7 @@ Why the Term "namespace"? LIBNVDIMM/LIBNDCTL: Block Translation Table "btt" ------------------------------------------------- -A BTT (design document: http://pmem.io/2014/09/23/btt.html) is a stacked +A BTT (design document: https://pmem.io/2014/09/23/btt.html) is a stacked block device driver that fronts either the whole block device or a partition of a block device emitted by either a PMEM or BLK NAMESPACE. diff --git a/Documentation/driver-api/nvdimm/security.rst b/Documentation/driver-api/nvdimm/security.rst index ad9dea099b34..7aab71524116 100644 --- a/Documentation/driver-api/nvdimm/security.rst +++ b/Documentation/driver-api/nvdimm/security.rst @@ -138,6 +138,6 @@ another encrypted-key. This command is only available when the master security is enabled, indicated by the extended security status. -[1]: http://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf +[1]: https://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf [2]: http://www.t13.org/documents/UploadedDocuments/docs2006/e05179r4-ACS-SecurityClarifications.pdf diff --git a/Documentation/driver-api/pldmfw/driver-ops.rst b/Documentation/driver-api/pldmfw/driver-ops.rst new file mode 100644 index 000000000000..f0654783d3b3 --- /dev/null +++ b/Documentation/driver-api/pldmfw/driver-ops.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +========================= +Driver-specific callbacks +========================= + +The ``pldmfw`` module relies on the device driver for implementing device +specific behavior using the following operations. + +``.match_record`` +----------------- + +The ``.match_record`` operation is used to determine whether a given PLDM +record matches the device being updated. This requires comparing the record +descriptors in the record with information from the device. Many record +descriptors are defined by the PLDM standard, but it is also allowed for +devices to implement their own descriptors. + +The ``.match_record`` operation should return true if a given record matches +the device. + +``.send_package_data`` +---------------------- + +The ``.send_package_data`` operation is used to send the device-specific +package data in a record to the device firmware. If the matching record +provides package data, ``pldmfw`` will call the ``.send_package_data`` +function with a pointer to the package data and with the package data +length. The device driver should send this data to firmware. + +``.send_component_table`` +------------------------- + +The ``.send_component_table`` operation is used to forward component +information to the device. It is called once for each applicable component, +that is, for each component indicated by the matching record. The +device driver should send the component information to the device firmware, +and wait for a response. The provided transfer flag indicates whether this +is the first, last, or a middle component, and is expected to be forwarded +to firmware as part of the component table information. The driver should an +error in the case when the firmware indicates that the component cannot be +updated, or return zero if the component can be updated. + +``.flash_component`` +-------------------- + +The ``.flash_component`` operation is used to inform the device driver to +flash a given component. The driver must perform any steps necessary to send +the component data to the device. + +``.finalize_update`` +-------------------- + +The ``.finalize_update`` operation is used by the ``pldmfw`` library in +order to allow the device driver to perform any remaining device specific +logic needed to finish the update. diff --git a/Documentation/driver-api/pldmfw/file-format.rst b/Documentation/driver-api/pldmfw/file-format.rst new file mode 100644 index 000000000000..b7a9cebe09c6 --- /dev/null +++ b/Documentation/driver-api/pldmfw/file-format.rst @@ -0,0 +1,203 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +================================== +PLDM Firmware file format overview +================================== + +A PLDM firmware package is a binary file which contains a header that +describes the contents of the firmware package. This includes an initial +package header, one or more firmware records, and one or more components +describing the actual flash contents to program. + +This diagram provides an overview of the file format:: + + overall file layout + +----------------------+ + | | + | Package Header | + | | + +----------------------+ + | | + | Device Records | + | | + +----------------------+ + | | + | Component Info | + | | + +----------------------+ + | | + | Package Header CRC | + | | + +----------------------+ + | | + | Component Image 1 | + | | + +----------------------+ + | | + | Component Image 2 | + | | + +----------------------+ + | | + | ... | + | | + +----------------------+ + | | + | Component Image N | + | | + +----------------------+ + +Package Header +============== + +The package header begins with the UUID of the PLDM file format, and +contains information about the version of the format that the file uses. It +also includes the total header size, a release date, the size of the +component bitmap, and an overall package version. + +The following diagram provides an overview of the package header:: + + header layout + +-------------------------+ + | PLDM UUID | + +-------------------------+ + | Format Revision | + +-------------------------+ + | Header Size | + +-------------------------+ + | Release Date | + +-------------------------+ + | Component Bitmap Length | + +-------------------------+ + | Package Version Info | + +-------------------------+ + +Device Records +============== + +The device firmware records area starts with a count indicating the total +number of records in the file, followed by each record. A single device +record describes what device matches this record. All valid PLDM firmware +files must contain at least one record, but optionally may contain more than +one record if they support multiple devices. + +Each record will identify the device it supports via TLVs that describe the +device, such as the PCI device and vendor information. It will also indicate +which set of components that are used by this device. It is possible that +only subset of provided components will be used by a given record. A record +may also optionally contain device-specific package data that will be used +by the device firmware during the update process. + +The following diagram provides an overview of the device record area:: + + area layout + +---------------+ + | | + | Record Count | + | | + +---------------+ + | | + | Record 1 | + | | + +---------------+ + | | + | Record 2 | + | | + +---------------+ + | | + | ... | + | | + +---------------+ + | | + | Record N | + | | + +---------------+ + + record layout + +-----------------------+ + | Record Length | + +-----------------------+ + | Descriptor Count | + +-----------------------+ + | Option Flags | + +-----------------------+ + | Version Settings | + +-----------------------+ + | Package Data Length | + +-----------------------+ + | Applicable Components | + +-----------------------+ + | Version String | + +-----------------------+ + | Descriptor TLVs | + +-----------------------+ + | Package Data | + +-----------------------+ + +Component Info +============== + +The component information area begins with a count of the number of +components. Following this count is a description for each component. The +component information points to the location in the file where the component +data is stored, and includes version data used to identify the version of +the component. + +The following diagram provides an overview of the component area:: + + area layout + +-----------------+ + | | + | Component Count | + | | + +-----------------+ + | | + | Component 1 | + | | + +-----------------+ + | | + | Component 2 | + | | + +-----------------+ + | | + | ... | + | | + +-----------------+ + | | + | Component N | + | | + +-----------------+ + + component layout + +------------------------+ + | Classification | + +------------------------+ + | Component Identifier | + +------------------------+ + | Comparison Stamp | + +------------------------+ + | Component Options | + +------------------------+ + | Activation Method | + +------------------------+ + | Location Offset | + +------------------------+ + | Component Size | + +------------------------+ + | Component Version Info | + +------------------------+ + | Package Data | + +------------------------+ + + +Package Header CRC +================== + +Following the component information is a short 4-byte CRC calculated over +the contents of all of the header information. + +Component Images +================ + +The component images follow the package header information in the PLDM +firmware file. Each of these is simply a binary chunk with its start and +size defined by the matching component structure in the component info area. diff --git a/Documentation/driver-api/pldmfw/index.rst b/Documentation/driver-api/pldmfw/index.rst new file mode 100644 index 000000000000..ad2c33ece30f --- /dev/null +++ b/Documentation/driver-api/pldmfw/index.rst @@ -0,0 +1,72 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +================================== +PLDM Firmware Flash Update Library +================================== + +``pldmfw`` implements functionality for updating the flash on a device using +the PLDM for Firmware Update standard +<https://www.dmtf.org/documents/pmci/pldm-firmware-update-specification-100>. + +.. toctree:: + :maxdepth: 1 + + file-format + driver-ops + +================================== +Overview of the ``pldmfw`` library +================================== + +The ``pldmfw`` library is intended to be used by device drivers for +implementing device flash update based on firmware files following the PLDM +firwmare file format. + +It is implemented using an ops table that allows device drivers to provide +the underlying device specific functionality. + +``pldmfw`` implements logic to parse the packed binary format of the PLDM +firmware file into data structures, and then uses the provided function +operations to determine if the firmware file is a match for the device. If +so, it sends the record and component data to the firmware using the device +specific implementations provided by device drivers. Once the device +firmware indicates that the update may be performed, the firmware data is +sent to the device for programming. + +Parsing the PLDM file +===================== + +The PLDM file format uses packed binary data, with most multi-byte fields +stored in the Little Endian format. Several pieces of data are variable +length, including version strings and the number of records and components. +Due to this, it is not straight forward to index the record, record +descriptors, or components. + +To avoid proliferating access to the packed binary data, the ``pldmfw`` +library parses and extracts this data into simpler structures for ease of +access. + +In order to safely process the firmware file, care is taken to avoid +unaligned access of multi-byte fields, and to properly convert from Little +Endian to CPU host format. Additionally the records, descriptors, and +components are stored in linked lists. + +Performing a flash update +========================= + +To perform a flash update, the ``pldmfw`` module performs the following +steps + +1. Parse the firmware file for record and component information +2. Scan through the records and determine if the device matches any record + in the file. The first matched record will be used. +3. If the matching record provides package data, send this package data to + the device. +4. For each component that the record indicates, send the component data to + the device. For each component, the firmware may respond with an + indication of whether the update is suitable or not. If any component is + not suitable, the update is canceled. +5. For each component, send the binary data to the device firmware for + updating. +6. After all components are programmed, perform any final device-specific + actions to finalize the update. diff --git a/Documentation/driver-api/ptp.rst b/Documentation/driver-api/ptp.rst index a15192e32347..664838ae7776 100644 --- a/Documentation/driver-api/ptp.rst +++ b/Documentation/driver-api/ptp.rst @@ -23,6 +23,7 @@ PTP hardware clock infrastructure for Linux + Ancillary clock features - Time stamp external events - Period output signals configurable from user space + - Low Pass Filter (LPF) access from user space - Synchronization of the Linux system time via the PPS subsystem PTP hardware clock kernel API @@ -94,3 +95,14 @@ Supported hardware - Auxiliary Slave/Master Mode Snapshot (optional interrupt) - Target Time (optional interrupt) + + * Renesas (IDT) ClockMatrixâ„¢ + + - Up to 4 independent PHC channels + - Integrated low pass filter (LPF), access via .adjPhase (compliant to ITU-T G.8273.2) + - Programmable output periodic signals + - Programmable inputs can time stamp external triggers + - Driver and/or hardware configuration through firmware (idtcm.bin) + - LPF settings (bandwidth, phase limiting, automatic holdover, physical layer assist (per ITU-T G.8273.2)) + - Programmable output PTP clocks, any frequency up to 1GHz (to other PHY/MAC time stampers, refclk to ASSPs/SoCs/FPGAs) + - Lock to GNSS input, automatic switching between GNSS and user-space PHC control (optional) diff --git a/Documentation/driver-api/rapidio/rapidio.rst b/Documentation/driver-api/rapidio/rapidio.rst index fb8942d3ba85..74c552ad3eb8 100644 --- a/Documentation/driver-api/rapidio/rapidio.rst +++ b/Documentation/driver-api/rapidio/rapidio.rst @@ -356,7 +356,7 @@ NOTE: http://www.rapidio.org/education/technology_comparisons/ [3] RapidIO support for Linux. - http://lwn.net/Articles/139118/ + https://lwn.net/Articles/139118/ [4] Matt Porter. RapidIO for Linux. Ottawa Linux Symposium, 2005 - http://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf + https://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf diff --git a/Documentation/driver-api/serial/n_gsm.rst b/Documentation/driver-api/serial/n_gsm.rst index 286e7ff4d2d9..87dfcd54a96b 100644 --- a/Documentation/driver-api/serial/n_gsm.rst +++ b/Documentation/driver-api/serial/n_gsm.rst @@ -5,7 +5,7 @@ GSM 0710 tty multiplexor HOWTO This line discipline implements the GSM 07.10 multiplexing protocol detailed in the following 3GPP document: - http://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip + https://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip This document give some hints on how to use this driver with GPRS and 3G modems connected to a physical serial port. diff --git a/Documentation/driver-api/soundwire/stream.rst b/Documentation/driver-api/soundwire/stream.rst index 1b386076402c..8858cea7bfe0 100644 --- a/Documentation/driver-api/soundwire/stream.rst +++ b/Documentation/driver-api/soundwire/stream.rst @@ -293,6 +293,10 @@ per stream. From ASoC DPCM framework, this stream state maybe linked to int sdw_alloc_stream(char * stream_name); +The SoundWire core provides a sdw_startup_stream() helper function, +typically called during a dailink .startup() callback, which performs +stream allocation and sets the stream pointer for all DAIs +connected to a stream. SDW_STREAM_CONFIGURED ~~~~~~~~~~~~~~~~~~~~~ @@ -509,7 +513,12 @@ In .shutdown() the data structure maintaining stream state are freed up. void sdw_release_stream(struct sdw_stream_runtime * stream); -Not Supported +The SoundWire core provides a sdw_shutdown_stream() helper function, +typically called during a dailink .shutdown() callback, which clears +the stream pointer for all DAIS connected to a stream and releases the +memory allocated for the stream. + + Not Supported ============= 1. A single port with multiple channels supported cannot be used between two diff --git a/Documentation/driver-api/thermal/cpu-idle-cooling.rst b/Documentation/driver-api/thermal/cpu-idle-cooling.rst index b9f34ceb2a38..c2a7ca676853 100644 --- a/Documentation/driver-api/thermal/cpu-idle-cooling.rst +++ b/Documentation/driver-api/thermal/cpu-idle-cooling.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ================ CPU Idle Cooling ================ @@ -48,7 +50,7 @@ idle state target residency, we lead to dropping the static and the dynamic leakage for this period (modulo the energy needed to enter this state). So the sustainable power with idle cycles has a linear relation with the OPP’s sustainable power and can be computed with a -coefficient similar to: +coefficient similar to:: Power(IdleCycle) = Coef x Power(OPP) @@ -139,7 +141,7 @@ Power considerations -------------------- When we reach the thermal trip point, we have to sustain a specified -power for a specific temperature but at this time we consume: +power for a specific temperature but at this time we consume:: Power = Capacitance x Voltage^2 x Frequency x Utilisation @@ -148,7 +150,7 @@ wrong in the system setup). The ‘Capacitance’ and ‘Utilisation’ are a fixed value, ‘Voltage’ and the ‘Frequency’ are fixed artificially because we don’t want to change the OPP. We can group the ‘Capacitance’ and the ‘Utilisation’ into a single term which is the -‘Dynamic Power Coefficient (Cdyn)’ Simplifying the above, we have: +‘Dynamic Power Coefficient (Cdyn)’ Simplifying the above, we have:: Pdyn = Cdyn x Voltage^2 x Frequency @@ -157,7 +159,7 @@ in order to target the sustainable power defined in the device tree. So with the idle injection mechanism, we want an average power (Ptarget) resulting in an amount of time running at full power on a specific OPP and idle another amount of time. That could be put in a -equation: +equation:: P(opp)target = ((Trunning x (P(opp)running) + (Tidle x P(opp)idle)) / (Trunning + Tidle) @@ -168,7 +170,7 @@ equation: At this point if we know the running period for the CPU, that gives us the idle injection we need. Alternatively if we have the idle -injection duration, we can compute the running duration with: +injection duration, we can compute the running duration with:: Trunning = Tidle / ((P(opp)running / P(opp)target) - 1) @@ -191,7 +193,7 @@ However, in this demonstration we ignore three aspects: target residency, otherwise we end up consuming more energy and potentially invert the mitigation effect -So the final equation is: +So the final equation is:: Trunning = (Tidle - Twakeup ) x (((P(opp)dyn + P(opp)static ) - P(opp)target) / P(opp)target ) diff --git a/Documentation/driver-api/thermal/nouveau_thermal.rst b/Documentation/driver-api/thermal/nouveau_thermal.rst index 37255fd6735d..79ece266cf6d 100644 --- a/Documentation/driver-api/thermal/nouveau_thermal.rst +++ b/Documentation/driver-api/thermal/nouveau_thermal.rst @@ -93,4 +93,4 @@ Thermal management on Nouveau is new and may not work on all cards. If you have inquiries, please ping mupuf on IRC (#nouveau, freenode). Bug reports should be filled on Freedesktop's bug tracker. Please follow -http://nouveau.freedesktop.org/wiki/Bugs +https://nouveau.freedesktop.org/wiki/Bugs diff --git a/Documentation/driver-api/uio-howto.rst b/Documentation/driver-api/uio-howto.rst index 84091cd25dc4..907ffa3b38f5 100644 --- a/Documentation/driver-api/uio-howto.rst +++ b/Documentation/driver-api/uio-howto.rst @@ -274,7 +274,7 @@ fields of ``struct uio_mem``: region, it will show up in the corresponding sysfs node. - ``int memtype``: Required if the mapping is used. Set this to - ``UIO_MEM_PHYS`` if you you have physical memory on your card to be + ``UIO_MEM_PHYS`` if you have physical memory on your card to be mapped. Use ``UIO_MEM_LOGICAL`` for logical memory (e.g. allocated with :c:func:`__get_free_pages()` but not kmalloc()). There's also ``UIO_MEM_VIRTUAL`` for virtual memory. diff --git a/Documentation/driver-api/usb/URB.rst b/Documentation/driver-api/usb/URB.rst index 61a54da9fce9..1e4abc896a0d 100644 --- a/Documentation/driver-api/usb/URB.rst +++ b/Documentation/driver-api/usb/URB.rst @@ -240,7 +240,7 @@ How to do isochronous (ISO) transfers? ====================================== Besides the fields present on a bulk transfer, for ISO, you also -also have to set ``urb->interval`` to say how often to make transfers; it's +have to set ``urb->interval`` to say how often to make transfers; it's often one per frame (which is once every microframe for highspeed devices). The actual interval used will be a power of two that's no bigger than what you specify. You can use the :c:func:`usb_fill_int_urb` macro to fill diff --git a/Documentation/driver-api/usb/dma.rst b/Documentation/driver-api/usb/dma.rst index 59d5aee89e37..2b3dbd3265b4 100644 --- a/Documentation/driver-api/usb/dma.rst +++ b/Documentation/driver-api/usb/dma.rst @@ -10,7 +10,7 @@ API overview The big picture is that USB drivers can continue to ignore most DMA issues, though they still must provide DMA-ready buffers (see -``Documentation/DMA-API-HOWTO.txt``). That's how they've worked through +:doc:`/core-api/dma-api-howto`). That's how they've worked through the 2.4 (and earlier) kernels, or they can now be DMA-aware. DMA-aware usb drivers: @@ -60,7 +60,7 @@ and effects like cache-trashing can impose subtle penalties. force a consistent memory access ordering by using memory barriers. It's not using a streaming DMA mapping, so it's good for small transfers on systems where the I/O would otherwise thrash an IOMMU mapping. (See - ``Documentation/DMA-API-HOWTO.txt`` for definitions of "coherent" and + :doc:`/core-api/dma-api-howto` for definitions of "coherent" and "streaming" DMA mappings.) Asking for 1/Nth of a page (as well as asking for N pages) is reasonably @@ -91,7 +91,7 @@ Working with existing buffers Existing buffers aren't usable for DMA without first being mapped into the DMA address space of the device. However, most buffers passed to your driver can safely be used with such DMA mapping. (See the first section -of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?") +of :doc:`/core-api/dma-api-howto`, titled "What memory is DMA-able?") - When you're using scatterlists, you can map everything at once. On some systems, this kicks in an IOMMU and turns the scatterlists into single diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst index 0b3d9ff221bb..2176297e5765 100644 --- a/Documentation/driver-api/usb/writing_usb_driver.rst +++ b/Documentation/driver-api/usb/writing_usb_driver.rst @@ -318,6 +318,6 @@ linux-usb Mailing List Archives: https://lore.kernel.org/linux-usb/ Programming Guide for Linux USB Device Drivers: -http://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf +https://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf -USB Home Page: http://www.usb.org +USB Home Page: https://www.usb.org diff --git a/Documentation/driver-api/xillybus.rst b/Documentation/driver-api/xillybus.rst index 2446ee303c09..a3ab832cb22b 100644 --- a/Documentation/driver-api/xillybus.rst +++ b/Documentation/driver-api/xillybus.rst @@ -273,7 +273,7 @@ buffer is full, the FPGA informs the host about that (appending a XILLYMSG_OPCODE_RELEASEBUF message channel 0 and sending an interrupt if necessary). The host responds by making the data available for reading through the character device. When all data has been read, the host writes on the -the FPGA's buffer control register, allowing the buffer's overwriting. Flow +FPGA's buffer control register, allowing the buffer's overwriting. Flow control mechanisms exist on both sides to prevent underflows and overflows. This is not good enough for creating a TCP/IP-like stream: If the data flow diff --git a/Documentation/fault-injection/fault-injection.rst b/Documentation/fault-injection/fault-injection.rst index f51bb21d20e4..f850ad018b70 100644 --- a/Documentation/fault-injection/fault-injection.rst +++ b/Documentation/fault-injection/fault-injection.rst @@ -24,7 +24,7 @@ Available fault injection capabilities injects disk IO errors on devices permitted by setting /sys/block/<device>/make-it-fail or - /sys/block/<device>/<partition>/make-it-fail. (generic_make_request()) + /sys/block/<device>/<partition>/make-it-fail. (submit_bio_noacct()) - fail_mmc_request diff --git a/Documentation/fb/ep93xx-fb.rst b/Documentation/fb/ep93xx-fb.rst index 6f7767926d1a..1dd67f4688c7 100644 --- a/Documentation/fb/ep93xx-fb.rst +++ b/Documentation/fb/ep93xx-fb.rst @@ -127,7 +127,7 @@ At least on the EP9315 there is a silicon bug which causes bit 27 of the VIDSCRNPAGE (framebuffer physical offset) to be tied low. There is an unofficial errata for this bug at:: - http://marc.info/?l=linux-arm-kernel&m=110061245502000&w=2 + https://marc.info/?l=linux-arm-kernel&m=110061245502000&w=2 By default the EP93xx framebuffer driver checks if the allocated physical address has bit 27 set. If it does, then the memory is freed and an diff --git a/Documentation/fb/modedb.rst b/Documentation/fb/modedb.rst index 624d08fd2856..4d2411e32ebb 100644 --- a/Documentation/fb/modedb.rst +++ b/Documentation/fb/modedb.rst @@ -152,7 +152,7 @@ To specify a video mode at bootup, use the following boot options:: video=<driver>:<xres>x<yres>[-<bpp>][@refresh] where <driver> is a name from the table below. Valid default modes can be -found in linux/drivers/video/modedb.c. Check your driver's documentation. +found in drivers/video/fbdev/core/modedb.c. Check your driver's documentation. There may be more modes:: Drivers that support modedb boot options diff --git a/Documentation/features/core/cBPF-JIT/arch-support.txt b/Documentation/features/core/cBPF-JIT/arch-support.txt index 8620c38d4db0..399935616813 100644 --- a/Documentation/features/core/cBPF-JIT/arch-support.txt +++ b/Documentation/features/core/cBPF-JIT/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | ok | | um: | TODO | - | unicore32: | TODO | | x86: | TODO | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/core/eBPF-JIT/arch-support.txt b/Documentation/features/core/eBPF-JIT/arch-support.txt index 9ed964f65224..79409bfe0263 100644 --- a/Documentation/features/core/eBPF-JIT/arch-support.txt +++ b/Documentation/features/core/eBPF-JIT/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | ok | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/core/generic-idle-thread/arch-support.txt b/Documentation/features/core/generic-idle-thread/arch-support.txt index 365df2c2ff0b..9ea60e416efd 100644 --- a/Documentation/features/core/generic-idle-thread/arch-support.txt +++ b/Documentation/features/core/generic-idle-thread/arch-support.txt @@ -28,7 +28,6 @@ | sh: | ok | | sparc: | ok | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | ok | ----------------------- diff --git a/Documentation/features/core/jump-labels/arch-support.txt b/Documentation/features/core/jump-labels/arch-support.txt index 632a1c7aefa2..894d9693b380 100644 --- a/Documentation/features/core/jump-labels/arch-support.txt +++ b/Documentation/features/core/jump-labels/arch-support.txt @@ -23,12 +23,11 @@ | openrisc: | TODO | | parisc: | ok | | powerpc: | ok | - | riscv: | TODO | + | riscv: | ok | | s390: | ok | | sh: | TODO | | sparc: | ok | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | ok | ----------------------- diff --git a/Documentation/features/core/tracehook/arch-support.txt b/Documentation/features/core/tracehook/arch-support.txt index 964667052eda..cd3510e2eedb 100644 --- a/Documentation/features/core/tracehook/arch-support.txt +++ b/Documentation/features/core/tracehook/arch-support.txt @@ -28,7 +28,6 @@ | sh: | ok | | sparc: | ok | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | ok | ----------------------- diff --git a/Documentation/features/debug/KASAN/arch-support.txt b/Documentation/features/debug/KASAN/arch-support.txt index 6ff38548923e..c3fe9b266e7b 100644 --- a/Documentation/features/debug/KASAN/arch-support.txt +++ b/Documentation/features/debug/KASAN/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | TODO | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | ok | ----------------------- diff --git a/Documentation/features/debug/debug-vm-pgtable/arch-support.txt b/Documentation/features/debug/debug-vm-pgtable/arch-support.txt index c527d05c0459..53da483c8326 100644 --- a/Documentation/features/debug/debug-vm-pgtable/arch-support.txt +++ b/Documentation/features/debug/debug-vm-pgtable/arch-support.txt @@ -23,12 +23,11 @@ | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | - | riscv: | TODO | + | riscv: | ok | | s390: | ok | | sh: | TODO | | sparc: | TODO | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/debug/gcov-profile-all/arch-support.txt b/Documentation/features/debug/gcov-profile-all/arch-support.txt index 210256f6a4cf..7563a494ddb8 100644 --- a/Documentation/features/debug/gcov-profile-all/arch-support.txt +++ b/Documentation/features/debug/gcov-profile-all/arch-support.txt @@ -28,7 +28,6 @@ | sh: | ok | | sparc: | TODO | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/debug/kcov/arch-support.txt b/Documentation/features/debug/kcov/arch-support.txt new file mode 100644 index 000000000000..ab0ee1c933c2 --- /dev/null +++ b/Documentation/features/debug/kcov/arch-support.txt @@ -0,0 +1,33 @@ +# +# Feature name: kcov +# Kconfig: ARCH_HAS_KCOV +# description: arch supports kcov for coverage-guided fuzzing +# + ----------------------- + | arch |status| + ----------------------- + | alpha: | TODO | + | arc: | TODO | + | arm: | ok | + | arm64: | ok | + | c6x: | TODO | + | csky: | TODO | + | h8300: | TODO | + | hexagon: | TODO | + | ia64: | TODO | + | m68k: | TODO | + | microblaze: | TODO | + | mips: | ok | + | nds32: | TODO | + | nios2: | TODO | + | openrisc: | TODO | + | parisc: | TODO | + | powerpc: | ok | + | riscv: | ok | + | s390: | ok | + | sh: | TODO | + | sparc: | TODO | + | um: | ok | + | x86: | ok | + | xtensa: | TODO | + ----------------------- diff --git a/Documentation/features/debug/kgdb/arch-support.txt b/Documentation/features/debug/kgdb/arch-support.txt index 38c40cfa0578..bc45bac20442 100644 --- a/Documentation/features/debug/kgdb/arch-support.txt +++ b/Documentation/features/debug/kgdb/arch-support.txt @@ -23,12 +23,11 @@ | openrisc: | TODO | | parisc: | ok | | powerpc: | ok | - | riscv: | TODO | + | riscv: | ok | | s390: | TODO | | sh: | ok | | sparc: | ok | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/debug/kmemleak/arch-support.txt b/Documentation/features/debug/kmemleak/arch-support.txt new file mode 100644 index 000000000000..b7e4f3608838 --- /dev/null +++ b/Documentation/features/debug/kmemleak/arch-support.txt @@ -0,0 +1,33 @@ +# +# Feature name: kmemleak +# Kconfig: HAVE_DEBUG_KMEMLEAK +# description: arch supports the kernel memory leak detector +# + ----------------------- + | arch |status| + ----------------------- + | alpha: | TODO | + | arc: | ok | + | arm: | ok | + | arm64: | ok | + | c6x: | TODO | + | csky: | TODO | + | h8300: | TODO | + | hexagon: | TODO | + | ia64: | TODO | + | m68k: | TODO | + | microblaze: | ok | + | mips: | ok | + | nds32: | ok | + | nios2: | TODO | + | openrisc: | TODO | + | parisc: | TODO | + | powerpc: | ok | + | riscv: | TODO | + | s390: | ok | + | sh: | ok | + | sparc: | ok | + | um: | ok | + | x86: | ok | + | xtensa: | ok | + ----------------------- diff --git a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt index 97cd7aa74905..6225cfe0c5bf 100644 --- a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt +++ b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | TODO | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/debug/kprobes/arch-support.txt b/Documentation/features/debug/kprobes/arch-support.txt index 8b316c6e03d4..371f0ac488f5 100644 --- a/Documentation/features/debug/kprobes/arch-support.txt +++ b/Documentation/features/debug/kprobes/arch-support.txt @@ -28,7 +28,6 @@ | sh: | ok | | sparc: | ok | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/debug/kretprobes/arch-support.txt b/Documentation/features/debug/kretprobes/arch-support.txt index b805aada395e..38e95251deed 100644 --- a/Documentation/features/debug/kretprobes/arch-support.txt +++ b/Documentation/features/debug/kretprobes/arch-support.txt @@ -28,7 +28,6 @@ | sh: | ok | | sparc: | ok | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/debug/optprobes/arch-support.txt b/Documentation/features/debug/optprobes/arch-support.txt index fb297a88f62c..7f4a20e6a12b 100644 --- a/Documentation/features/debug/optprobes/arch-support.txt +++ b/Documentation/features/debug/optprobes/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | TODO | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/debug/stackprotector/arch-support.txt b/Documentation/features/debug/stackprotector/arch-support.txt index 12410f606edc..3db4763aa3f5 100644 --- a/Documentation/features/debug/stackprotector/arch-support.txt +++ b/Documentation/features/debug/stackprotector/arch-support.txt @@ -28,7 +28,6 @@ | sh: | ok | | sparc: | TODO | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | ok | ----------------------- diff --git a/Documentation/features/debug/uprobes/arch-support.txt b/Documentation/features/debug/uprobes/arch-support.txt index be8acbb95b54..43cac6ee0c68 100644 --- a/Documentation/features/debug/uprobes/arch-support.txt +++ b/Documentation/features/debug/uprobes/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | ok | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/debug/user-ret-profiler/arch-support.txt b/Documentation/features/debug/user-ret-profiler/arch-support.txt index 6bfa36b0e017..d636ed0e679f 100644 --- a/Documentation/features/debug/user-ret-profiler/arch-support.txt +++ b/Documentation/features/debug/user-ret-profiler/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | TODO | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/io/dma-contiguous/arch-support.txt b/Documentation/features/io/dma-contiguous/arch-support.txt index 895c3b0f6492..dfc93d074e3d 100644 --- a/Documentation/features/io/dma-contiguous/arch-support.txt +++ b/Documentation/features/io/dma-contiguous/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | TODO | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | ok | ----------------------- diff --git a/Documentation/features/locking/cmpxchg-local/arch-support.txt b/Documentation/features/locking/cmpxchg-local/arch-support.txt index 242ff5a6586e..1815c7fed06d 100644 --- a/Documentation/features/locking/cmpxchg-local/arch-support.txt +++ b/Documentation/features/locking/cmpxchg-local/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | TODO | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/locking/lockdep/arch-support.txt b/Documentation/features/locking/lockdep/arch-support.txt index 98cb9d85c55d..4f844ecd0680 100644 --- a/Documentation/features/locking/lockdep/arch-support.txt +++ b/Documentation/features/locking/lockdep/arch-support.txt @@ -28,7 +28,6 @@ | sh: | ok | | sparc: | ok | | um: | ok | - | unicore32: | ok | | x86: | ok | | xtensa: | ok | ----------------------- diff --git a/Documentation/features/locking/queued-rwlocks/arch-support.txt b/Documentation/features/locking/queued-rwlocks/arch-support.txt index ee922746a64c..5c6bcfcf8e1f 100644 --- a/Documentation/features/locking/queued-rwlocks/arch-support.txt +++ b/Documentation/features/locking/queued-rwlocks/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | ok | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | ok | ----------------------- diff --git a/Documentation/features/locking/queued-spinlocks/arch-support.txt b/Documentation/features/locking/queued-spinlocks/arch-support.txt index c52116c1a049..b55e420a34ea 100644 --- a/Documentation/features/locking/queued-spinlocks/arch-support.txt +++ b/Documentation/features/locking/queued-spinlocks/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | ok | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | ok | ----------------------- diff --git a/Documentation/features/perf/kprobes-event/arch-support.txt b/Documentation/features/perf/kprobes-event/arch-support.txt index 518f352fc727..04c17c2106a4 100644 --- a/Documentation/features/perf/kprobes-event/arch-support.txt +++ b/Documentation/features/perf/kprobes-event/arch-support.txt @@ -28,7 +28,6 @@ | sh: | ok | | sparc: | ok | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/perf/perf-regs/arch-support.txt b/Documentation/features/perf/perf-regs/arch-support.txt index c22cd6f8aa5e..e7450fbb8253 100644 --- a/Documentation/features/perf/perf-regs/arch-support.txt +++ b/Documentation/features/perf/perf-regs/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | TODO | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/perf/perf-stackdump/arch-support.txt b/Documentation/features/perf/perf-stackdump/arch-support.txt index 527fe4d0b074..98e79d128d9b 100644 --- a/Documentation/features/perf/perf-stackdump/arch-support.txt +++ b/Documentation/features/perf/perf-stackdump/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | TODO | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/sched/membarrier-sync-core/arch-support.txt b/Documentation/features/sched/membarrier-sync-core/arch-support.txt index 8a521a622966..47e6903f47a5 100644 --- a/Documentation/features/sched/membarrier-sync-core/arch-support.txt +++ b/Documentation/features/sched/membarrier-sync-core/arch-support.txt @@ -5,7 +5,7 @@ # # Architecture requirements # -# * arm/arm64 +# * arm/arm64/powerpc # # Rely on implicit context synchronization as a result of exception return # when returning from IPI handler, and when returning to user-space. @@ -45,13 +45,12 @@ | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | - | powerpc: | TODO | + | powerpc: | ok | | riscv: | TODO | | s390: | TODO | | sh: | TODO | | sparc: | TODO | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/sched/numa-balancing/arch-support.txt b/Documentation/features/sched/numa-balancing/arch-support.txt index 350823692f28..964457ad26c1 100644 --- a/Documentation/features/sched/numa-balancing/arch-support.txt +++ b/Documentation/features/sched/numa-balancing/arch-support.txt @@ -28,7 +28,6 @@ | sh: | .. | | sparc: | TODO | | um: | .. | - | unicore32: | .. | | x86: | ok | | xtensa: | .. | ----------------------- diff --git a/Documentation/features/seccomp/seccomp-filter/arch-support.txt b/Documentation/features/seccomp/seccomp-filter/arch-support.txt index c7b837f735b1..c688aba22a8d 100644 --- a/Documentation/features/seccomp/seccomp-filter/arch-support.txt +++ b/Documentation/features/seccomp/seccomp-filter/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | TODO | | um: | ok | - | unicore32: | TODO | | x86: | ok | - | xtensa: | TODO | + | xtensa: | ok | ----------------------- diff --git a/Documentation/features/time/arch-tick-broadcast/arch-support.txt b/Documentation/features/time/arch-tick-broadcast/arch-support.txt index 593536f7925b..4d11cbb3c09b 100644 --- a/Documentation/features/time/arch-tick-broadcast/arch-support.txt +++ b/Documentation/features/time/arch-tick-broadcast/arch-support.txt @@ -28,7 +28,6 @@ | sh: | ok | | sparc: | TODO | | um: | TODO | - | unicore32: | TODO | | x86: | TODO | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/time/clockevents/arch-support.txt b/Documentation/features/time/clockevents/arch-support.txt index 7a27157da408..8287b6aa522e 100644 --- a/Documentation/features/time/clockevents/arch-support.txt +++ b/Documentation/features/time/clockevents/arch-support.txt @@ -28,7 +28,6 @@ | sh: | ok | | sparc: | ok | | um: | ok | - | unicore32: | ok | | x86: | ok | | xtensa: | ok | ----------------------- diff --git a/Documentation/features/time/context-tracking/arch-support.txt b/Documentation/features/time/context-tracking/arch-support.txt index 048bfb6d3872..a71f3a945285 100644 --- a/Documentation/features/time/context-tracking/arch-support.txt +++ b/Documentation/features/time/context-tracking/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | ok | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/time/irq-time-acct/arch-support.txt b/Documentation/features/time/irq-time-acct/arch-support.txt index a14bbad8e948..d9082b91f10e 100644 --- a/Documentation/features/time/irq-time-acct/arch-support.txt +++ b/Documentation/features/time/irq-time-acct/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | .. | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | ok | ----------------------- diff --git a/Documentation/features/time/modern-timekeeping/arch-support.txt b/Documentation/features/time/modern-timekeeping/arch-support.txt index 1d46da165b75..a84c3b9d9a94 100644 --- a/Documentation/features/time/modern-timekeeping/arch-support.txt +++ b/Documentation/features/time/modern-timekeeping/arch-support.txt @@ -28,7 +28,6 @@ | sh: | ok | | sparc: | ok | | um: | ok | - | unicore32: | ok | | x86: | ok | | xtensa: | ok | ----------------------- diff --git a/Documentation/features/time/virt-cpuacct/arch-support.txt b/Documentation/features/time/virt-cpuacct/arch-support.txt index fb0d0cab9cab..56b372da6b01 100644 --- a/Documentation/features/time/virt-cpuacct/arch-support.txt +++ b/Documentation/features/time/virt-cpuacct/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | ok | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/vm/ELF-ASLR/arch-support.txt b/Documentation/features/vm/ELF-ASLR/arch-support.txt index adc25878d217..eccda0732474 100644 --- a/Documentation/features/vm/ELF-ASLR/arch-support.txt +++ b/Documentation/features/vm/ELF-ASLR/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | TODO | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/vm/PG_uncached/arch-support.txt b/Documentation/features/vm/PG_uncached/arch-support.txt index f05588f9e4b4..c74e3f8040e1 100644 --- a/Documentation/features/vm/PG_uncached/arch-support.txt +++ b/Documentation/features/vm/PG_uncached/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | TODO | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/vm/THP/arch-support.txt b/Documentation/features/vm/THP/arch-support.txt index cdfe8925f881..1c0b95f2b40d 100644 --- a/Documentation/features/vm/THP/arch-support.txt +++ b/Documentation/features/vm/THP/arch-support.txt @@ -28,7 +28,6 @@ | sh: | .. | | sparc: | ok | | um: | .. | - | unicore32: | .. | | x86: | ok | | xtensa: | .. | ----------------------- diff --git a/Documentation/features/vm/TLB/arch-support.txt b/Documentation/features/vm/TLB/arch-support.txt index 2bdd3b6cee3c..30f75a79ce01 100644 --- a/Documentation/features/vm/TLB/arch-support.txt +++ b/Documentation/features/vm/TLB/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | TODO | | um: | .. | - | unicore32: | .. | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/vm/huge-vmap/arch-support.txt b/Documentation/features/vm/huge-vmap/arch-support.txt index 8525f1981f19..c5ff3a427722 100644 --- a/Documentation/features/vm/huge-vmap/arch-support.txt +++ b/Documentation/features/vm/huge-vmap/arch-support.txt @@ -28,7 +28,6 @@ | sh: | TODO | | sparc: | TODO | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/vm/ioremap_prot/arch-support.txt b/Documentation/features/vm/ioremap_prot/arch-support.txt index 3a6b87de6a19..1cb7406cd858 100644 --- a/Documentation/features/vm/ioremap_prot/arch-support.txt +++ b/Documentation/features/vm/ioremap_prot/arch-support.txt @@ -28,7 +28,6 @@ | sh: | ok | | sparc: | TODO | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/vm/pte_special/arch-support.txt b/Documentation/features/vm/pte_special/arch-support.txt index 2e017387e228..13d0e1e17001 100644 --- a/Documentation/features/vm/pte_special/arch-support.txt +++ b/Documentation/features/vm/pte_special/arch-support.txt @@ -28,7 +28,6 @@ | sh: | ok | | sparc: | ok | | um: | TODO | - | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/filesystems/9p.rst b/Documentation/filesystems/9p.rst index 2995279ddc24..7b5964bc8865 100644 --- a/Documentation/filesystems/9p.rst +++ b/Documentation/filesystems/9p.rst @@ -18,7 +18,7 @@ and Maya Gokhale. Additional development by Greg Watson The best detailed explanation of the Linux implementation and applications of the 9p client is available in the form of a USENIX paper: - http://www.usenix.org/events/usenix05/tech/freenix/hensbergen.html + https://www.usenix.org/events/usenix05/tech/freenix/hensbergen.html Other applications are described in the following papers: diff --git a/Documentation/filesystems/afs.rst b/Documentation/filesystems/afs.rst index cada9464d6bd..0abb155ac666 100644 --- a/Documentation/filesystems/afs.rst +++ b/Documentation/filesystems/afs.rst @@ -190,7 +190,7 @@ Security Secure operations are initiated by acquiring a key using the klog program. A very primitive klog program is available at: - http://people.redhat.com/~dhowells/rxrpc/klog.c + https://people.redhat.com/~dhowells/rxrpc/klog.c This should be compiled by:: diff --git a/Documentation/filesystems/autofs-mount-control.rst b/Documentation/filesystems/autofs-mount-control.rst index 2903aed92316..bf4b511cdbe8 100644 --- a/Documentation/filesystems/autofs-mount-control.rst +++ b/Documentation/filesystems/autofs-mount-control.rst @@ -391,7 +391,7 @@ variation uses the path and optionally in.type field of struct args_ismountpoint set to an autofs mount type. The call returns 1 if this is a mount point and sets out.devid field to the device number of the mount and out.magic field to the relevant super block magic number (described below) or 0 if -it isn't a mountpoint. In both cases the the device number (as returned +it isn't a mountpoint. In both cases the device number (as returned by new_encode_dev()) is returned in out.devid field. If supplied with a file descriptor we're looking for a specific mount, @@ -399,12 +399,12 @@ not necessarily at the top of the mounted stack. In this case the path the descriptor corresponds to is considered a mountpoint if it is itself a mountpoint or contains a mount, such as a multi-mount without a root mount. In this case we return 1 if the descriptor corresponds to a mount -point and and also returns the super magic of the covering mount if there +point and also returns the super magic of the covering mount if there is one or 0 if it isn't a mountpoint. If a path is supplied (and the ioctlfd field is set to -1) then the path is looked up and is checked to see if it is the root of a mount. If a type is also given we are looking for a particular autofs mount and if -a match isn't found a fail is returned. If the the located path is the +a match isn't found a fail is returned. If the located path is the root of a mount 1 is returned along with the super magic of the mount or 0 otherwise. diff --git a/Documentation/filesystems/caching/cachefiles.rst b/Documentation/filesystems/caching/cachefiles.rst index 65d3db476765..e58bc1fd312a 100644 --- a/Documentation/filesystems/caching/cachefiles.rst +++ b/Documentation/filesystems/caching/cachefiles.rst @@ -348,7 +348,7 @@ data cached therein; nor is it permitted to create new files in the cache. There are policy source files available in: - http://people.redhat.com/~dhowells/fscache/cachefilesd-0.8.tar.bz2 + https://people.redhat.com/~dhowells/fscache/cachefilesd-0.8.tar.bz2 and later versions. In that tarball, see the files:: diff --git a/Documentation/filesystems/caching/operations.rst b/Documentation/filesystems/caching/operations.rst index f7ddcc028939..9983e1675447 100644 --- a/Documentation/filesystems/caching/operations.rst +++ b/Documentation/filesystems/caching/operations.rst @@ -27,7 +27,7 @@ data storage and retrieval routines. Its operations are represented by fscache_operation structs, though these are usually embedded into some other structure. -This facility is available to and expected to be be used by the cache backends, +This facility is available to and expected to be used by the cache backends, and FS-Cache will create operations and pass them off to the appropriate cache backend for completion. diff --git a/Documentation/filesystems/coda.rst b/Documentation/filesystems/coda.rst index 84c860c89887..bdde7e4e010b 100644 --- a/Documentation/filesystems/coda.rst +++ b/Documentation/filesystems/coda.rst @@ -524,7 +524,7 @@ kernel support. Description This call is made to determine the ViceFid and filetype of - a directory entry. The directory entry requested carries name name + a directory entry. The directory entry requested carries name 'name' and Venus will search the directory identified by cfs_lookup_in.VFid. The result may indicate that the name does not exist, or that difficulty was encountered in finding it (e.g. due to disconnection). @@ -886,7 +886,7 @@ kernel support. none Description - Remove the directory with name name from the directory + Remove the directory with name 'name' from the directory identified by VFid. .. Note:: The attributes of the parent directory should be returned since diff --git a/Documentation/filesystems/configfs.rst b/Documentation/filesystems/configfs.rst index f8941954c667..1d3d6f4a82a9 100644 --- a/Documentation/filesystems/configfs.rst +++ b/Documentation/filesystems/configfs.rst @@ -226,7 +226,7 @@ filename. configfs_attribute->ca_mode specifies the file permissions. If an attribute is readable and provides a ->show method, that method will be called whenever userspace asks for a read(2) on the attribute. If an attribute is writable and provides a ->store method, that method will be -be called whenever userspace asks for a write(2) on the attribute. +called whenever userspace asks for a write(2) on the attribute. struct configfs_bin_attribute ============================= diff --git a/Documentation/filesystems/dax.txt b/Documentation/filesystems/dax.txt index 8e2670781c9b..8fdb78f3c6c9 100644 --- a/Documentation/filesystems/dax.txt +++ b/Documentation/filesystems/dax.txt @@ -25,7 +25,7 @@ size when creating the filesystem. Currently 3 filesystems support DAX: ext2, ext4 and xfs. Enabling DAX on them is different. -Enabling DAX on ext4 and ext2 +Enabling DAX on ext2 ----------------------------- When mounting the filesystem, use the "-o dax" option on the command line or @@ -33,8 +33,8 @@ add 'dax' to the options in /etc/fstab. This works to enable DAX on all files within the filesystem. It is equivalent to the '-o dax=always' behavior below. -Enabling DAX on xfs -------------------- +Enabling DAX on xfs and ext4 +---------------------------- Summary ------- diff --git a/Documentation/filesystems/debugfs.rst b/Documentation/filesystems/debugfs.rst index 1da7a4b7383d..728ab57a611a 100644 --- a/Documentation/filesystems/debugfs.rst +++ b/Documentation/filesystems/debugfs.rst @@ -185,13 +185,17 @@ byte offsets over a base for the register block. If you want to dump an u32 array in debugfs, you can create file with:: + struct debugfs_u32_array { + u32 *array; + u32 n_elements; + }; + void debugfs_create_u32_array(const char *name, umode_t mode, struct dentry *parent, - u32 *array, u32 elements); + struct debugfs_u32_array *array); -The "array" argument provides data, and the "elements" argument is -the number of elements in the array. Note: Once array is created its -size can not be changed. +The "array" argument wraps a pointer to the array's data and the number +of its elements. Note: Once array is created its size can not be changed. There is a helper function to create device related seq_file:: diff --git a/Documentation/filesystems/directory-locking.rst b/Documentation/filesystems/directory-locking.rst index de12016ee419..504ba940c36c 100644 --- a/Documentation/filesystems/directory-locking.rst +++ b/Documentation/filesystems/directory-locking.rst @@ -28,7 +28,7 @@ RENAME_EXCHANGE in flags argument) lock both. In any case, if the target already exists, lock it. If the source is a non-directory, lock it. If we need to lock both, lock them in inode pointer order. Then call the method. All locks are exclusive. -NB: we might get away with locking the the source (and target in exchange +NB: we might get away with locking the source (and target in exchange case) shared. 5) link creation. Locking rules: @@ -56,7 +56,7 @@ rules: * call the method. All ->i_rwsem are taken exclusive. Again, we might get away with locking -the the source (and target in exchange case) shared. +the source (and target in exchange case) shared. The rules above obviously guarantee that all directories that are going to be read, modified or removed by method will be locked by caller. diff --git a/Documentation/filesystems/dlmfs.rst b/Documentation/filesystems/dlmfs.rst index 68daaa7facf9..28dd41a63be2 100644 --- a/Documentation/filesystems/dlmfs.rst +++ b/Documentation/filesystems/dlmfs.rst @@ -12,7 +12,7 @@ dlmfs is built with OCFS2 as it requires most of its infrastructure. :Project web page: http://ocfs2.wiki.kernel.org :Tools web page: https://github.com/markfasheh/ocfs2-tools -:OCFS2 mailing lists: http://oss.oracle.com/projects/ocfs2/mailman/ +:OCFS2 mailing lists: https://oss.oracle.com/projects/ocfs2/mailman/ All code copyright 2005 Oracle except when otherwise noted. diff --git a/Documentation/filesystems/ext4/verity.rst b/Documentation/filesystems/ext4/verity.rst index 3e4c0ee0e068..e99ff3fd09f7 100644 --- a/Documentation/filesystems/ext4/verity.rst +++ b/Documentation/filesystems/ext4/verity.rst @@ -39,3 +39,6 @@ is encrypted as well as the data itself. Verity files cannot have blocks allocated past the end of the verity metadata. + +Verity and DAX are not compatible and attempts to set both of these flags +on a file will fail. diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst index 099d45ac8d8f..a11d329542f9 100644 --- a/Documentation/filesystems/f2fs.rst +++ b/Documentation/filesystems/f2fs.rst @@ -101,164 +101,170 @@ Mount Options ============= -====================== ============================================================ -background_gc=%s Turn on/off cleaning operations, namely garbage - collection, triggered in background when I/O subsystem is - idle. If background_gc=on, it will turn on the garbage - collection and if background_gc=off, garbage collection - will be turned off. If background_gc=sync, it will turn - on synchronous garbage collection running in background. - Default value for this option is on. So garbage - collection is on by default. -disable_roll_forward Disable the roll-forward recovery routine -norecovery Disable the roll-forward recovery routine, mounted read- - only (i.e., -o ro,disable_roll_forward) -discard/nodiscard Enable/disable real-time discard in f2fs, if discard is - enabled, f2fs will issue discard/TRIM commands when a - segment is cleaned. -no_heap Disable heap-style segment allocation which finds free - segments for data from the beginning of main area, while - for node from the end of main area. -nouser_xattr Disable Extended User Attributes. Note: xattr is enabled - by default if CONFIG_F2FS_FS_XATTR is selected. -noacl Disable POSIX Access Control List. Note: acl is enabled - by default if CONFIG_F2FS_FS_POSIX_ACL is selected. -active_logs=%u Support configuring the number of active logs. In the - current design, f2fs supports only 2, 4, and 6 logs. - Default number is 6. -disable_ext_identify Disable the extension list configured by mkfs, so f2fs - does not aware of cold files such as media files. -inline_xattr Enable the inline xattrs feature. -noinline_xattr Disable the inline xattrs feature. -inline_xattr_size=%u Support configuring inline xattr size, it depends on - flexible inline xattr feature. -inline_data Enable the inline data feature: New created small(<~3.4k) - files can be written into inode block. -inline_dentry Enable the inline dir feature: data in new created - directory entries can be written into inode block. The - space of inode block which is used to store inline - dentries is limited to ~3.4k. -noinline_dentry Disable the inline dentry feature. -flush_merge Merge concurrent cache_flush commands as much as possible - to eliminate redundant command issues. If the underlying - device handles the cache_flush command relatively slowly, - recommend to enable this option. -nobarrier This option can be used if underlying storage guarantees - its cached data should be written to the novolatile area. - If this option is set, no cache_flush commands are issued - but f2fs still guarantees the write ordering of all the - data writes. -fastboot This option is used when a system wants to reduce mount - time as much as possible, even though normal performance - can be sacrificed. -extent_cache Enable an extent cache based on rb-tree, it can cache - as many as extent which map between contiguous logical - address and physical address per inode, resulting in - increasing the cache hit ratio. Set by default. -noextent_cache Disable an extent cache based on rb-tree explicitly, see - the above extent_cache mount option. -noinline_data Disable the inline data feature, inline data feature is - enabled by default. -data_flush Enable data flushing before checkpoint in order to - persist data of regular and symlink. -reserve_root=%d Support configuring reserved space which is used for - allocation from a privileged user with specified uid or - gid, unit: 4KB, the default limit is 0.2% of user blocks. -resuid=%d The user ID which may use the reserved blocks. -resgid=%d The group ID which may use the reserved blocks. -fault_injection=%d Enable fault injection in all supported types with - specified injection rate. -fault_type=%d Support configuring fault injection type, should be - enabled with fault_injection option, fault type value - is shown below, it supports single or combined type. - - =================== =========== - Type_Name Type_Value - =================== =========== - FAULT_KMALLOC 0x000000001 - FAULT_KVMALLOC 0x000000002 - FAULT_PAGE_ALLOC 0x000000004 - FAULT_PAGE_GET 0x000000008 - FAULT_ALLOC_BIO 0x000000010 - FAULT_ALLOC_NID 0x000000020 - FAULT_ORPHAN 0x000000040 - FAULT_BLOCK 0x000000080 - FAULT_DIR_DEPTH 0x000000100 - FAULT_EVICT_INODE 0x000000200 - FAULT_TRUNCATE 0x000000400 - FAULT_READ_IO 0x000000800 - FAULT_CHECKPOINT 0x000001000 - FAULT_DISCARD 0x000002000 - FAULT_WRITE_IO 0x000004000 - =================== =========== -mode=%s Control block allocation mode which supports "adaptive" - and "lfs". In "lfs" mode, there should be no random - writes towards main area. -io_bits=%u Set the bit size of write IO requests. It should be set - with "mode=lfs". -usrquota Enable plain user disk quota accounting. -grpquota Enable plain group disk quota accounting. -prjquota Enable plain project quota accounting. -usrjquota=<file> Appoint specified file and type during mount, so that quota -grpjquota=<file> information can be properly updated during recovery flow, -prjjquota=<file> <quota file>: must be in root directory; -jqfmt=<quota type> <quota type>: [vfsold,vfsv0,vfsv1]. -offusrjquota Turn off user journelled quota. -offgrpjquota Turn off group journelled quota. -offprjjquota Turn off project journelled quota. -quota Enable plain user disk quota accounting. -noquota Disable all plain disk quota option. -whint_mode=%s Control which write hints are passed down to block - layer. This supports "off", "user-based", and - "fs-based". In "off" mode (default), f2fs does not pass - down hints. In "user-based" mode, f2fs tries to pass - down hints given by users. And in "fs-based" mode, f2fs - passes down hints with its policy. -alloc_mode=%s Adjust block allocation policy, which supports "reuse" - and "default". -fsync_mode=%s Control the policy of fsync. Currently supports "posix", - "strict", and "nobarrier". In "posix" mode, which is - default, fsync will follow POSIX semantics and does a - light operation to improve the filesystem performance. - In "strict" mode, fsync will be heavy and behaves in line - with xfs, ext4 and btrfs, where xfstest generic/342 will - pass, but the performance will regress. "nobarrier" is - based on "posix", but doesn't issue flush command for - non-atomic files likewise "nobarrier" mount option. +======================== ============================================================ +background_gc=%s Turn on/off cleaning operations, namely garbage + collection, triggered in background when I/O subsystem is + idle. If background_gc=on, it will turn on the garbage + collection and if background_gc=off, garbage collection + will be turned off. If background_gc=sync, it will turn + on synchronous garbage collection running in background. + Default value for this option is on. So garbage + collection is on by default. +disable_roll_forward Disable the roll-forward recovery routine +norecovery Disable the roll-forward recovery routine, mounted read- + only (i.e., -o ro,disable_roll_forward) +discard/nodiscard Enable/disable real-time discard in f2fs, if discard is + enabled, f2fs will issue discard/TRIM commands when a + segment is cleaned. +no_heap Disable heap-style segment allocation which finds free + segments for data from the beginning of main area, while + for node from the end of main area. +nouser_xattr Disable Extended User Attributes. Note: xattr is enabled + by default if CONFIG_F2FS_FS_XATTR is selected. +noacl Disable POSIX Access Control List. Note: acl is enabled + by default if CONFIG_F2FS_FS_POSIX_ACL is selected. +active_logs=%u Support configuring the number of active logs. In the + current design, f2fs supports only 2, 4, and 6 logs. + Default number is 6. +disable_ext_identify Disable the extension list configured by mkfs, so f2fs + does not aware of cold files such as media files. +inline_xattr Enable the inline xattrs feature. +noinline_xattr Disable the inline xattrs feature. +inline_xattr_size=%u Support configuring inline xattr size, it depends on + flexible inline xattr feature. +inline_data Enable the inline data feature: New created small(<~3.4k) + files can be written into inode block. +inline_dentry Enable the inline dir feature: data in new created + directory entries can be written into inode block. The + space of inode block which is used to store inline + dentries is limited to ~3.4k. +noinline_dentry Disable the inline dentry feature. +flush_merge Merge concurrent cache_flush commands as much as possible + to eliminate redundant command issues. If the underlying + device handles the cache_flush command relatively slowly, + recommend to enable this option. +nobarrier This option can be used if underlying storage guarantees + its cached data should be written to the novolatile area. + If this option is set, no cache_flush commands are issued + but f2fs still guarantees the write ordering of all the + data writes. +fastboot This option is used when a system wants to reduce mount + time as much as possible, even though normal performance + can be sacrificed. +extent_cache Enable an extent cache based on rb-tree, it can cache + as many as extent which map between contiguous logical + address and physical address per inode, resulting in + increasing the cache hit ratio. Set by default. +noextent_cache Disable an extent cache based on rb-tree explicitly, see + the above extent_cache mount option. +noinline_data Disable the inline data feature, inline data feature is + enabled by default. +data_flush Enable data flushing before checkpoint in order to + persist data of regular and symlink. +reserve_root=%d Support configuring reserved space which is used for + allocation from a privileged user with specified uid or + gid, unit: 4KB, the default limit is 0.2% of user blocks. +resuid=%d The user ID which may use the reserved blocks. +resgid=%d The group ID which may use the reserved blocks. +fault_injection=%d Enable fault injection in all supported types with + specified injection rate. +fault_type=%d Support configuring fault injection type, should be + enabled with fault_injection option, fault type value + is shown below, it supports single or combined type. + + =================== =========== + Type_Name Type_Value + =================== =========== + FAULT_KMALLOC 0x000000001 + FAULT_KVMALLOC 0x000000002 + FAULT_PAGE_ALLOC 0x000000004 + FAULT_PAGE_GET 0x000000008 + FAULT_ALLOC_BIO 0x000000010 + FAULT_ALLOC_NID 0x000000020 + FAULT_ORPHAN 0x000000040 + FAULT_BLOCK 0x000000080 + FAULT_DIR_DEPTH 0x000000100 + FAULT_EVICT_INODE 0x000000200 + FAULT_TRUNCATE 0x000000400 + FAULT_READ_IO 0x000000800 + FAULT_CHECKPOINT 0x000001000 + FAULT_DISCARD 0x000002000 + FAULT_WRITE_IO 0x000004000 + =================== =========== +mode=%s Control block allocation mode which supports "adaptive" + and "lfs". In "lfs" mode, there should be no random + writes towards main area. +io_bits=%u Set the bit size of write IO requests. It should be set + with "mode=lfs". +usrquota Enable plain user disk quota accounting. +grpquota Enable plain group disk quota accounting. +prjquota Enable plain project quota accounting. +usrjquota=<file> Appoint specified file and type during mount, so that quota +grpjquota=<file> information can be properly updated during recovery flow, +prjjquota=<file> <quota file>: must be in root directory; +jqfmt=<quota type> <quota type>: [vfsold,vfsv0,vfsv1]. +offusrjquota Turn off user journelled quota. +offgrpjquota Turn off group journelled quota. +offprjjquota Turn off project journelled quota. +quota Enable plain user disk quota accounting. +noquota Disable all plain disk quota option. +whint_mode=%s Control which write hints are passed down to block + layer. This supports "off", "user-based", and + "fs-based". In "off" mode (default), f2fs does not pass + down hints. In "user-based" mode, f2fs tries to pass + down hints given by users. And in "fs-based" mode, f2fs + passes down hints with its policy. +alloc_mode=%s Adjust block allocation policy, which supports "reuse" + and "default". +fsync_mode=%s Control the policy of fsync. Currently supports "posix", + "strict", and "nobarrier". In "posix" mode, which is + default, fsync will follow POSIX semantics and does a + light operation to improve the filesystem performance. + In "strict" mode, fsync will be heavy and behaves in line + with xfs, ext4 and btrfs, where xfstest generic/342 will + pass, but the performance will regress. "nobarrier" is + based on "posix", but doesn't issue flush command for + non-atomic files likewise "nobarrier" mount option. test_dummy_encryption test_dummy_encryption=%s - Enable dummy encryption, which provides a fake fscrypt - context. The fake fscrypt context is used by xfstests. - The argument may be either "v1" or "v2", in order to - select the corresponding fscrypt policy version. -checkpoint=%s[:%u[%]] Set to "disable" to turn off checkpointing. Set to "enable" - to reenable checkpointing. Is enabled by default. While - disabled, any unmounting or unexpected shutdowns will cause - the filesystem contents to appear as they did when the - filesystem was mounted with that option. - While mounting with checkpoint=disabled, the filesystem must - run garbage collection to ensure that all available space can - be used. If this takes too much time, the mount may return - EAGAIN. You may optionally add a value to indicate how much - of the disk you would be willing to temporarily give up to - avoid additional garbage collection. This can be given as a - number of blocks, or as a percent. For instance, mounting - with checkpoint=disable:100% would always succeed, but it may - hide up to all remaining free space. The actual space that - would be unusable can be viewed at /sys/fs/f2fs/<disk>/unusable - This space is reclaimed once checkpoint=enable. -compress_algorithm=%s Control compress algorithm, currently f2fs supports "lzo", - "lz4", "zstd" and "lzo-rle" algorithm. -compress_log_size=%u Support configuring compress cluster size, the size will - be 4KB * (1 << %u), 16KB is minimum size, also it's - default size. -compress_extension=%s Support adding specified extension, so that f2fs can enable - compression on those corresponding files, e.g. if all files - with '.ext' has high compression rate, we can set the '.ext' - on compression extension list and enable compression on - these file by default rather than to enable it via ioctl. - For other files, we can still enable compression via ioctl. -====================== ============================================================ + Enable dummy encryption, which provides a fake fscrypt + context. The fake fscrypt context is used by xfstests. + The argument may be either "v1" or "v2", in order to + select the corresponding fscrypt policy version. +checkpoint=%s[:%u[%]] Set to "disable" to turn off checkpointing. Set to "enable" + to reenable checkpointing. Is enabled by default. While + disabled, any unmounting or unexpected shutdowns will cause + the filesystem contents to appear as they did when the + filesystem was mounted with that option. + While mounting with checkpoint=disabled, the filesystem must + run garbage collection to ensure that all available space can + be used. If this takes too much time, the mount may return + EAGAIN. You may optionally add a value to indicate how much + of the disk you would be willing to temporarily give up to + avoid additional garbage collection. This can be given as a + number of blocks, or as a percent. For instance, mounting + with checkpoint=disable:100% would always succeed, but it may + hide up to all remaining free space. The actual space that + would be unusable can be viewed at /sys/fs/f2fs/<disk>/unusable + This space is reclaimed once checkpoint=enable. +compress_algorithm=%s Control compress algorithm, currently f2fs supports "lzo", + "lz4", "zstd" and "lzo-rle" algorithm. +compress_log_size=%u Support configuring compress cluster size, the size will + be 4KB * (1 << %u), 16KB is minimum size, also it's + default size. +compress_extension=%s Support adding specified extension, so that f2fs can enable + compression on those corresponding files, e.g. if all files + with '.ext' has high compression rate, we can set the '.ext' + on compression extension list and enable compression on + these file by default rather than to enable it via ioctl. + For other files, we can still enable compression via ioctl. +inlinecrypt When possible, encrypt/decrypt the contents of encrypted + files using the blk-crypto framework rather than + filesystem-layer encryption. This allows the use of + inline encryption hardware. The on-disk format is + unaffected. For more details, see + Documentation/block/inline-encryption.rst. +======================== ============================================================ Debugfs Entries =============== diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index f517af8ec11c..423c5a0daf45 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -1158,7 +1158,7 @@ setxattr() because of the special semantics of the encryption xattr. were to be added to or removed from anything other than an empty directory.) These structs are defined as follows:: - #define FS_KEY_DERIVATION_NONCE_SIZE 16 + #define FSCRYPT_FILE_NONCE_SIZE 16 #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 struct fscrypt_context_v1 { @@ -1167,7 +1167,7 @@ directory.) These structs are defined as follows:: u8 filenames_encryption_mode; u8 flags; u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; - u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE]; + u8 nonce[FSCRYPT_FILE_NONCE_SIZE]; }; #define FSCRYPT_KEY_IDENTIFIER_SIZE 16 @@ -1178,7 +1178,7 @@ directory.) These structs are defined as follows:: u8 flags; u8 __reserved[4]; u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; - u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE]; + u8 nonce[FSCRYPT_FILE_NONCE_SIZE]; }; The context structs contain the same information as the corresponding @@ -1204,6 +1204,18 @@ buffer. Some filesystems, such as UBIFS, already use temporary buffers regardless of encryption. Other filesystems, such as ext4 and F2FS, have to allocate bounce pages specially for encryption. +Fscrypt is also able to use inline encryption hardware instead of the +kernel crypto API for en/decryption of file contents. When possible, +and if directed to do so (by specifying the 'inlinecrypt' mount option +for an ext4/F2FS filesystem), it adds encryption contexts to bios and +uses blk-crypto to perform the en/decryption instead of making use of +the above read/write path changes. Of course, even if directed to +make use of inline encryption, fscrypt will only be able to do so if +either hardware inline encryption support is available for the +selected encryption algorithm or CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK +is selected. If neither is the case, fscrypt will fall back to using +the above mentioned read/write path changes for en/decryption. + Filename hashing and encoding ----------------------------- @@ -1250,11 +1262,14 @@ Tests To test fscrypt, use xfstests, which is Linux's de facto standard filesystem test suite. First, run all the tests in the "encrypt" -group on the relevant filesystem(s). For example, to test ext4 and +group on the relevant filesystem(s). One can also run the tests +with the 'inlinecrypt' mount option to test the implementation for +inline encryption support. For example, to test ext4 and f2fs encryption using `kvm-xfstests <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_:: kvm-xfstests -c ext4,f2fs -g encrypt + kvm-xfstests -c ext4,f2fs -g encrypt -m inlinecrypt UBIFS encryption can also be tested this way, but it should be done in a separate command, and it takes some time for kvm-xfstests to set up @@ -1276,6 +1291,7 @@ This tests the encrypted I/O paths more thoroughly. To do this with kvm-xfstests, use the "encrypt" filesystem configuration:: kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto + kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt Because this runs many more tests than "-g encrypt" does, it takes much longer to run; so also consider using `gce-xfstests @@ -1283,3 +1299,4 @@ much longer to run; so also consider using `gce-xfstests instead of kvm-xfstests:: gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto + gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt diff --git a/Documentation/filesystems/fsverity.rst b/Documentation/filesystems/fsverity.rst index a95536b6443c..6c8944f6f0f7 100644 --- a/Documentation/filesystems/fsverity.rst +++ b/Documentation/filesystems/fsverity.rst @@ -659,7 +659,7 @@ weren't already directly answered in other parts of this document. retrofit existing filesystems with new consistency mechanisms. Data journalling is available on ext4, but is very slow. - - Rebuilding the the Merkle tree after every write, which would be + - Rebuilding the Merkle tree after every write, which would be extremely inefficient. Alternatively, a different authenticated dictionary structure such as an "authenticated skiplist" could be used. However, this would be far more complex. diff --git a/Documentation/filesystems/hfs.rst b/Documentation/filesystems/hfs.rst index ab17a005e9b1..776015c80e3f 100644 --- a/Documentation/filesystems/hfs.rst +++ b/Documentation/filesystems/hfs.rst @@ -76,7 +76,7 @@ Creating HFS filesystems The hfsutils package from Robert Leslie contains a program called hformat that can be used to create HFS filesystem. See -<http://www.mars.org/home/rob/proj/hfs/> for details. +<https://www.mars.org/home/rob/proj/hfs/> for details. Credits diff --git a/Documentation/filesystems/hpfs.rst b/Documentation/filesystems/hpfs.rst index 0db152278572..7e0dd2f4373e 100644 --- a/Documentation/filesystems/hpfs.rst +++ b/Documentation/filesystems/hpfs.rst @@ -7,7 +7,7 @@ Read/Write HPFS 2.09 1998-2004, Mikulas Patocka :email: mikulas@artax.karlin.mff.cuni.cz -:homepage: http://artax.karlin.mff.cuni.cz/~mikulas/vyplody/hpfs/index-e.cgi +:homepage: https://artax.karlin.mff.cuni.cz/~mikulas/vyplody/hpfs/index-e.cgi Credits ======= diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index 318605de83f3..64f94a18d97e 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -433,15 +433,15 @@ prototypes:: locking rules: -========== ============= ================= ========= +====================== ============= ================= ========= ops inode->i_lock blocked_lock_lock may block -========== ============= ================= ========= +====================== ============= ================= ========= lm_notify: yes yes no lm_grant: no no no lm_break: yes no no lm_change yes no no lm_breaker_owns_lease: no no no -========== ============= ================= ========= +====================== ============= ================= ========= buffer_head =========== @@ -467,7 +467,6 @@ prototypes:: int (*compat_ioctl) (struct block_device *, fmode_t, unsigned, unsigned long); int (*direct_access) (struct block_device *, sector_t, void **, unsigned long *); - int (*media_changed) (struct gendisk *); void (*unlock_native_capacity) (struct gendisk *); int (*revalidate_disk) (struct gendisk *); int (*getgeo)(struct block_device *, struct hd_geometry *); @@ -483,14 +482,13 @@ release: yes ioctl: no compat_ioctl: no direct_access: no -media_changed: no unlock_native_capacity: no revalidate_disk: no getgeo: no swap_slot_free_notify: no (see below) ======================= =================== -media_changed, unlock_native_capacity and revalidate_disk are called only from +unlock_native_capacity and revalidate_disk are called only from check_disk_change(). swap_slot_free_notify is called with swap_lock and sometimes the page lock @@ -616,9 +614,9 @@ prototypes:: locking rules: -============= ======== =========================== +============= ========= =========================== ops mmap_lock PageLocked(page) -============= ======== =========================== +============= ========= =========================== open: yes close: yes fault: yes can return with page locked @@ -626,7 +624,7 @@ map_pages: yes page_mkwrite: yes can return with page locked pfn_mkwrite: yes access: yes -============= ======== =========================== +============= ========= =========================== ->fault() is called when a previously not present pte is about to be faulted in. The filesystem must find and return the page associated diff --git a/Documentation/filesystems/mount_api.rst b/Documentation/filesystems/mount_api.rst index dea22d64f060..29c169c68961 100644 --- a/Documentation/filesystems/mount_api.rst +++ b/Documentation/filesystems/mount_api.rst @@ -213,7 +213,7 @@ The filesystem context points to a table of operations:: void (*free)(struct fs_context *fc); int (*dup)(struct fs_context *fc, struct fs_context *src_fc); int (*parse_param)(struct fs_context *fc, - struct struct fs_parameter *param); + struct fs_parameter *param); int (*parse_monolithic)(struct fs_context *fc, void *data); int (*get_tree)(struct fs_context *fc); int (*reconfigure)(struct fs_context *fc); @@ -247,7 +247,7 @@ manage the filesystem context. They are as follows: * :: int (*parse_param)(struct fs_context *fc, - struct struct fs_parameter *param); + struct fs_parameter *param); Called when a parameter is being added to the filesystem context. param points to the key name and maybe a value object. VFS-specific options diff --git a/Documentation/filesystems/nfs/rpc-server-gss.rst b/Documentation/filesystems/nfs/rpc-server-gss.rst index 812754576845..abed4a2b1b82 100644 --- a/Documentation/filesystems/nfs/rpc-server-gss.rst +++ b/Documentation/filesystems/nfs/rpc-server-gss.rst @@ -10,12 +10,12 @@ purposes of authentication.) RPCGSS is specified in a few IETF documents: - - RFC2203 v1: http://tools.ietf.org/rfc/rfc2203.txt - - RFC5403 v2: http://tools.ietf.org/rfc/rfc5403.txt + - RFC2203 v1: https://tools.ietf.org/rfc/rfc2203.txt + - RFC5403 v2: https://tools.ietf.org/rfc/rfc5403.txt and there is a 3rd version being proposed: - - http://tools.ietf.org/id/draft-williams-rpcsecgssv3.txt + - https://tools.ietf.org/id/draft-williams-rpcsecgssv3.txt (At draft n. 02 at the time of writing) Background diff --git a/Documentation/filesystems/ocfs2.rst b/Documentation/filesystems/ocfs2.rst index 412386bc6506..42ca9a3d4c6e 100644 --- a/Documentation/filesystems/ocfs2.rst +++ b/Documentation/filesystems/ocfs2.rst @@ -14,7 +14,7 @@ get "mount.ocfs2" and "ocfs2_hb_ctl". Project web page: http://ocfs2.wiki.kernel.org Tools git tree: https://github.com/markfasheh/ocfs2-tools -OCFS2 mailing lists: http://oss.oracle.com/projects/ocfs2/mailman/ +OCFS2 mailing lists: https://oss.oracle.com/projects/ocfs2/mailman/ All code copyright 2005 Oracle except when otherwise noted. diff --git a/Documentation/filesystems/omfs.rst b/Documentation/filesystems/omfs.rst index 4c8bb3074169..a104c25b7a2f 100644 --- a/Documentation/filesystems/omfs.rst +++ b/Documentation/filesystems/omfs.rst @@ -24,7 +24,7 @@ More information is available at: Various utilities, including mkomfs and omfsck, are included with omfsprogs, available at: - http://bobcopeland.com/karma/ + https://bobcopeland.com/karma/ Instructions are included in its README. diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst index 660dbaf0b9b8..8ea83a51c266 100644 --- a/Documentation/filesystems/overlayfs.rst +++ b/Documentation/filesystems/overlayfs.rst @@ -328,7 +328,7 @@ the time of copy (on-demand vs. up-front). Multiple lower layers --------------------- -Multiple lower layers can now be given using the the colon (":") as a +Multiple lower layers can now be given using the colon (":") as a separator character between the directory names. For example: mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged @@ -560,8 +560,8 @@ When the NFS export feature is enabled, all directory index entries are verified on mount time to check that upper file handles are not stale. This verification may cause significant overhead in some cases. -Note: the mount options index=off,nfs_export=on are conflicting and will -result in an error. +Note: the mount options index=off,nfs_export=on are conflicting for a +read-write mount and will result in an error. Testsuite diff --git a/Documentation/filesystems/path-lookup.rst b/Documentation/filesystems/path-lookup.rst index f46b05e9b96c..c482e1619e77 100644 --- a/Documentation/filesystems/path-lookup.rst +++ b/Documentation/filesystems/path-lookup.rst @@ -43,15 +43,15 @@ characters, and "components" that are sequences of one or more non-"``/``" characters. These form two kinds of paths. Those that start with slashes are "absolute" and start from the filesystem root. The others are "relative" and start from the current directory, or -from some other location specified by a file descriptor given to a -"``XXXat``" system call such as `openat() <openat_>`_. +from some other location specified by a file descriptor given to +"``*at()``" system calls such as `openat() <openat_>`_. .. _execveat: http://man7.org/linux/man-pages/man2/execveat.2.html It is tempting to describe the second kind as starting with a component, but that isn't always accurate: a pathname can lack both slashes and components, it can be empty, in other words. This is -generally forbidden in POSIX, but some of those "xxx``at``" system calls +generally forbidden in POSIX, but some of those "``*at()``" system calls in Linux permit it when the ``AT_EMPTY_PATH`` flag is given. For example, if you have an open file descriptor on an executable file you can execute it by calling `execveat() <execveat_>`_ passing @@ -69,17 +69,17 @@ pathname that is just slashes have a final component. If it does exist, it could be "``.``" or "``..``" which are handled quite differently from other components. -.. _POSIX: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_12 +.. _POSIX: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_12 If a pathname ends with a slash, such as "``/tmp/foo/``" it might be tempting to consider that to have an empty final component. In many ways that would lead to correct results, but not always. In particular, ``mkdir()`` and ``rmdir()`` each create or remove a directory named by the final component, and they are required to work with pathnames -ending in "``/``". According to POSIX_ +ending in "``/``". According to POSIX_: - A pathname that contains at least one non- <slash> character and - that ends with one or more trailing <slash> characters shall not + A pathname that contains at least one non-<slash> character and + that ends with one or more trailing <slash> characters shall not be resolved successfully unless the last pathname component before the trailing <slash> characters names an existing directory or a directory entry that is to be created for a directory immediately @@ -229,7 +229,7 @@ happened to be looking at a dentry that was moved in this way, it might end up continuing the search down the wrong chain, and so miss out on part of the correct chain. -The name-lookup process (``d_lookup()``) does _not_ try to prevent this +The name-lookup process (``d_lookup()``) does *not* try to prevent this from happening, but only to detect when it happens. ``rename_lock`` is a seqlock that is updated whenever any dentry is renamed. If ``d_lookup`` finds that a rename happened while it @@ -376,7 +376,7 @@ table, and the mount point hash table. Bringing it together with ``struct nameidata`` ---------------------------------------------- -.. _First edition Unix: http://minnie.tuhs.org/cgi-bin/utree.pl?file=V1/u2.s +.. _First edition Unix: https://minnie.tuhs.org/cgi-bin/utree.pl?file=V1/u2.s Throughout the process of walking a path, the current status is stored in a ``struct nameidata``, "namei" being the traditional name - dating @@ -398,7 +398,7 @@ held. ``struct qstr last`` ~~~~~~~~~~~~~~~~~~~~ -This is a string together with a length (i.e. _not_ ``nul`` terminated) +This is a string together with a length (i.e. *not* ``nul`` terminated) that is the "next" component in the pathname. ``int last_type`` @@ -655,8 +655,8 @@ This pattern of "try RCU-walk, if that fails try REF-walk" can be clearly seen in functions like ``filename_lookup()``, ``filename_parentat()``, ``filename_mountpoint()``, ``do_filp_open()``, and ``do_file_open_root()``. These five -correspond roughly to the four ``path_``* functions we met earlier, -each of which calls ``link_path_walk()``. The ``path_*`` functions are +correspond roughly to the four ``path_*()`` functions we met earlier, +each of which calls ``link_path_walk()``. The ``path_*()`` functions are called using different mode flags until a mode is found which works. They are first called with ``LOOKUP_RCU`` set to request "RCU-walk". If that fails with the error ``ECHILD`` they are called again with no @@ -720,7 +720,7 @@ against a dentry. The length and name pointer are copied into local variables, then ``read_seqcount_retry()`` is called to confirm the two are consistent, and only then is ``->d_compare()`` called. When standard filename comparison is used, ``dentry_cmp()`` is called -instead. Notably it does _not_ use ``read_seqcount_retry()``, but +instead. Notably it does *not* use ``read_seqcount_retry()``, but instead has a large comment explaining why the consistency guarantee isn't necessary. A subsequent ``read_seqcount_retry()`` will be sufficient to catch any problem that could occur at this point. @@ -928,7 +928,7 @@ if anything goes wrong it is much safer to just abort and try a more sedate approach. The emphasis here is "try quickly and check". It should probably be -"try quickly _and carefully,_ then check". The fact that checking is +"try quickly *and carefully*, then check". The fact that checking is needed is a reminder that the system is dynamic and only a limited number of things are safe at all. The most likely cause of errors in this whole process is assuming something is safe when in reality it @@ -1265,7 +1265,7 @@ Symlinks are different it seems. Both reading a symlink (with ``readlink()``) and looking up a symlink on the way to some other destination can update the atime on that symlink. -.. _clearest statement: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_08 +.. _clearest statement: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_08 It is not clear why this is the case; POSIX has little to say on the subject. The `clearest statement`_ is that, if a particular implementation @@ -1365,7 +1365,7 @@ as well as blocking ".." if it would jump outside the starting point. resolution of "..". Magic-links are also blocked. ``LOOKUP_IN_ROOT`` resolves all path components as though the starting point -were the filesystem root. ``nd_jump_root()`` brings the resolution back to to +were the filesystem root. ``nd_jump_root()`` brings the resolution back to the starting point, and ".." at the starting point will act as a no-op. As with ``LOOKUP_BENEATH``, ``rename_lock`` and ``mount_lock`` are used to detect attacks against ".." resolution. Magic-links are also blocked. diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 996f3cfe7030..e024a9efffd8 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -123,10 +123,10 @@ show you how you can use /proc/sys to change settings. The directory /proc contains (among other things) one subdirectory for each process running on the system, which is named after the process ID (PID). -The link self points to the process reading the file system. Each process +The link 'self' points to the process reading the file system. Each process subdirectory has the entries listed in Table 1-1. -Note that an open a file descriptor to /proc/<pid> or to any of its +Note that an open file descriptor to /proc/<pid> or to any of its contained files or subdirectories does not prevent <pid> being reused for some other process in the event that <pid> exits. Operations on open /proc/<pid> file descriptors corresponding to dead processes @@ -220,7 +220,7 @@ file /proc/PID/status. It fields are described in table 1-2. The statm file contains more detailed information about the process memory usage. Its seven fields are explained in Table 1-3. The stat file -contains details information about the process itself. Its fields are +contains detailed information about the process itself. Its fields are explained in Table 1-4. (for SMP CONFIG users) @@ -545,7 +545,7 @@ encoded manner. The codes are the following: hg huge page advise flag nh no huge page advise flag mg mergable advise flag - bt - arm64 BTI guarded page + bt arm64 BTI guarded page == ======================================= Note that there is no guarantee that every flag and associated mnemonic will @@ -782,7 +782,7 @@ SPU For this case the APIC will generate the interrupt with a IRQ vector of 0xff. This might also be generated by chipset bugs. -RES, CAL, TLB] +RES, CAL, TLB rescheduling, call and TLB flush interrupts are sent from one CPU to another per the needs of the OS. Typically, their statistics are used by kernel developers and interested users to @@ -794,7 +794,7 @@ suppressed when the system is a uniprocessor. As of this writing, only i386 and x86_64 platforms support the new IRQ vector displays. Of some interest is the introduction of the /proc/irq directory to 2.4. -It could be used to set IRQ to CPU affinity, this means that you can "hook" an +It could be used to set IRQ to CPU affinity. This means that you can "hook" an IRQ to only one CPU, or to exclude a CPU of handling IRQs. The contents of the irq subdir is one subdir for each IRQ, and two files; default_smp_affinity and prof_cpu_mask. @@ -808,7 +808,7 @@ For example:: smp_affinity smp_affinity is a bitmask, in which you can specify which CPUs can handle the -IRQ, you can set it by doing:: +IRQ. You can set it by doing:: > echo 1 > /proc/irq/10/smp_affinity @@ -821,7 +821,7 @@ The contents of each smp_affinity file is the same by default:: ffffffff There is an alternate interface, smp_affinity_list which allows specifying -a cpu range instead of a bitmask:: +a CPU range instead of a bitmask:: > cat /proc/irq/0/smp_affinity_list 1024-1031 @@ -835,7 +835,7 @@ reports itself as being attached. This hardware locality information does not include information about any possible driver locality preference. prof_cpu_mask specifies which CPUs are to be profiled by the system wide -profiler. Default value is ffffffff (all cpus if there are only 32 of them). +profiler. Default value is ffffffff (all CPUs if there are only 32 of them). The way IRQs are routed is handled by the IO-APIC, and it's Round Robin between all the CPUs which are allowed to handle it. As usual the kernel has @@ -897,7 +897,7 @@ pagetypeinfo:: Fragmentation avoidance in the kernel works by grouping pages of different migrate types into the same contiguous regions of memory called page blocks. -A page block is typically the size of the default hugepage size e.g. 2MB on +A page block is typically the size of the default hugepage size, e.g. 2MB on X86-64. By keeping pages grouped based on their ability to move, the kernel can reclaim pages within a page block to satisfy a high-order allocation. @@ -965,7 +965,7 @@ varies by architecture and compile options. The following is from a ShmemPmdMapped: 0 kB MemTotal - Total usable ram (i.e. physical ram minus a few reserved + Total usable RAM (i.e. physical RAM minus a few reserved bits and the kernel binary code) MemFree The sum of LowFree+HighFree @@ -996,7 +996,7 @@ Inactive Memory which has been less recently used. It is more eligible to be reclaimed for other purposes HighTotal, HighFree - Highmem is all memory above ~860MB of physical memory + Highmem is all memory above ~860MB of physical memory. Highmem areas are for use by userspace programs, or for the pagecache. The kernel must use tricks to access this memory, making it slower to access than lowmem. @@ -1078,7 +1078,7 @@ Committed_AS using 1G. This 1G is memory which has been "committed" to by the VM and can be used at any time by the allocating application. With strict overcommit enabled on the system - (mode 2 in 'vm.overcommit_memory'),allocations which would + (mode 2 in 'vm.overcommit_memory'), allocations which would exceed the CommitLimit (detailed above) will not be permitted. This is useful if one needs to guarantee that processes will not fail due to lack of memory once that memory has been @@ -1099,7 +1099,7 @@ vmallocinfo Provides information about vmalloced/vmaped areas. One line per area, containing the virtual address range of the area, size in bytes, caller information of the creator, and optional information depending -on the kind of area : +on the kind of area: ========== =================================================== pages=nr number of pages @@ -1144,21 +1144,21 @@ on the kind of area : softirqs ~~~~~~~~ -Provides counts of softirq handlers serviced since boot time, for each cpu. +Provides counts of softirq handlers serviced since boot time, for each CPU. :: > cat /proc/softirqs - CPU0 CPU1 CPU2 CPU3 + CPU0 CPU1 CPU2 CPU3 HI: 0 0 0 0 - TIMER: 27166 27120 27097 27034 + TIMER: 27166 27120 27097 27034 NET_TX: 0 0 0 17 NET_RX: 42 0 0 39 - BLOCK: 0 0 107 1121 - TASKLET: 0 0 0 290 - SCHED: 27035 26983 26971 26746 - HRTIMER: 0 0 0 0 - RCU: 1678 1769 2178 2250 + BLOCK: 0 0 107 1121 + TASKLET: 0 0 0 290 + SCHED: 27035 26983 26971 26746 + HRTIMER: 0 0 0 0 + RCU: 1678 1769 2178 2250 1.3 IDE devices in /proc/ide @@ -1169,7 +1169,7 @@ the kernel is aware. There is one subdirectory for each IDE controller, the file drivers and a link for each IDE device, pointing to the device directory in the controller specific subtree. -The file drivers contains general information about the drivers used for the +The file 'drivers' contains general information about the drivers used for the IDE devices:: > cat /proc/ide/drivers @@ -1409,7 +1409,7 @@ These directories contain the four files shown in Table 1-10. ------------------------- Information about the available and actually used tty's can be found in the -directory /proc/tty.You'll find entries for drivers and line disciplines in +directory /proc/tty. You'll find entries for drivers and line disciplines in this directory, as shown in Table 1-11. @@ -1471,9 +1471,9 @@ second). The meanings of the columns are as follows, from left to right: - iowait: In a word, iowait stands for waiting for I/O to complete. But there are several problems: - 1. Cpu will not wait for I/O to complete, iowait is the time that a task is - waiting for I/O to complete. When cpu goes into idle state for - outstanding task io, another task will be scheduled on this CPU. + 1. CPU will not wait for I/O to complete, iowait is the time that a task is + waiting for I/O to complete. When CPU goes into idle state for + outstanding task I/O, another task will be scheduled on this CPU. 2. In a multi-core CPU, the task waiting for I/O to complete is not running on any CPU, so the iowait of each CPU is difficult to calculate. 3. The value of iowait field in /proc/stat will decrease in certain @@ -1529,8 +1529,8 @@ in Table 1-12, below. mb_groups details of multiblock allocator buddy cache of free blocks ============== ========================================================== -2.0 /proc/consoles ------------------- +1.10 /proc/consoles +------------------- Shows registered system console lines. To see which character device lines are currently used for the system console @@ -1590,10 +1590,9 @@ production system. Set up a development machine and test to make sure that everything works the way you want it to. You may have no alternative but to reboot the machine once an error has been made. -To change a value, simply echo the new value into the file. An example is -given below in the section on the file system data. You need to be root to do -this. You can create your own boot script to perform this every time your -system boots. +To change a value, simply echo the new value into the file. +You need to be root to do this. You can create your own boot script +to perform this every time your system boots. The files in /proc/sys can be used to fine tune and monitor miscellaneous and general things in the operation of the Linux kernel. Since some of the files @@ -1624,8 +1623,8 @@ Chapter 3: Per-process Parameters 3.1 /proc/<pid>/oom_adj & /proc/<pid>/oom_score_adj- Adjust the oom-killer score -------------------------------------------------------------------------------- -These file can be used to adjust the badness heuristic used to select which -process gets killed in out of memory conditions. +These files can be used to adjust the badness heuristic used to select which +process gets killed in out of memory (oom) conditions. The badness heuristic assigns a value to each candidate task ranging from 0 (never kill) to 1000 (always kill) to determine which process is targeted. The @@ -1681,7 +1680,7 @@ minimal amount of work. 3.2 /proc/<pid>/oom_score - Display current oom-killer score ------------------------------------------------------------- -This file can be used to check the current score used by the oom-killer is for +This file can be used to check the current score used by the oom-killer for any given <pid>. Use it together with /proc/<pid>/oom_score_adj to tune which process should be killed in an out-of-memory situation. @@ -1689,7 +1688,7 @@ process should be killed in an out-of-memory situation. 3.3 /proc/<pid>/io - Display the IO accounting fields ------------------------------------------------------- -This file contains IO statistics for each running process +This file contains IO statistics for each running process. Example ~~~~~~~ @@ -1720,7 +1719,7 @@ The number of bytes which this task has caused to be read from storage. This is simply the sum of bytes which this process passed to read() and pread(). It includes things like tty IO and it is unaffected by whether or not actual physical disk IO was required (the read might have been satisfied from -pagecache) +pagecache). wchar @@ -1878,7 +1877,7 @@ For more information on mount propagation see: 3.6 /proc/<pid>/comm & /proc/<pid>/task/<tid>/comm -------------------------------------------------------- -These files provide a method to access a tasks comm value. It also allows for +These files provide a method to access a task's comm value. It also allows for a task to set its own or one of its thread siblings comm value. The comm value is limited in size compared to the cmdline value, so writing anything longer then the kernel's TASK_COMM_LEN (currently 16 chars) will result in a truncated @@ -1891,21 +1890,21 @@ This file provides a fast way to retrieve first level children pids of a task pointed by <pid>/<tid> pair. The format is a space separated stream of pids. -Note the "first level" here -- if a child has own children they will -not be listed here, one needs to read /proc/<children-pid>/task/<tid>/children +Note the "first level" here -- if a child has its own children they will +not be listed here; one needs to read /proc/<children-pid>/task/<tid>/children to obtain the descendants. Since this interface is intended to be fast and cheap it doesn't guarantee to provide precise results and some children might be skipped, especially if they've exited right after we printed their -pids, so one need to either stop or freeze processes being inspected +pids, so one needs to either stop or freeze processes being inspected if precise results are needed. 3.8 /proc/<pid>/fdinfo/<fd> - Information about opened file --------------------------------------------------------------- This file provides information associated with an opened file. The regular -files have at least three fields -- 'pos', 'flags' and mnt_id. The 'pos' +files have at least three fields -- 'pos', 'flags' and 'mnt_id'. The 'pos' represents the current offset of the opened file in decimal form [see lseek(2) for details], 'flags' denotes the octal O_xxx mask the file has been created with [see open(2) for details] and 'mnt_id' represents mount ID of @@ -1976,7 +1975,7 @@ For inotify files the format is the following:: flags: 02000000 inotify wd:3 ino:9e7e sdev:800013 mask:800afce ignored_mask:0 fhandle-bytes:8 fhandle-type:1 f_handle:7e9e0000640d1b6d -where 'wd' is a watch descriptor in decimal form, ie a target file +where 'wd' is a watch descriptor in decimal form, i.e. a target file descriptor number, 'ino' and 'sdev' are inode and device where the target file resides and the 'mask' is the mask of events, all in hex form [see inotify(7) for more details]. @@ -2003,10 +2002,10 @@ For fanotify files the format is:: where fanotify 'flags' and 'event-flags' are values used in fanotify_init call, 'mnt_id' is the mount point identifier, 'mflags' is the value of flags associated with mark which are tracked separately from events -mask. 'ino', 'sdev' are target inode and device, 'mask' is the events +mask. 'ino' and 'sdev' are target inode and device, 'mask' is the events mask and 'ignored_mask' is the mask of events which are to be ignored. -All in hex format. Incorporation of 'mflags', 'mask' and 'ignored_mask' -does provide information about flags and mask used in fanotify_mark +All are in hex format. Incorporation of 'mflags', 'mask' and 'ignored_mask' +provide information about flags and mask used in fanotify_mark call [see fsnotify manpage for details]. While the first three lines are mandatory and always printed, the rest is @@ -2029,7 +2028,7 @@ Timerfd files where 'clockid' is the clock type and 'ticks' is the number of the timer expirations that have occurred [see timerfd_create(2) for details]. 'settime flags' are flags in octal form been used to setup the timer [see timerfd_settime(2) for -details]. 'it_value' is remaining time until the timer exiration. +details]. 'it_value' is remaining time until the timer expiration. 'it_interval' is the interval for the timer. Note the timer might be set up with TIMER_ABSTIME option which will be shown in 'settime flags', but 'it_value' still exhibits timer's remaining time. @@ -2059,13 +2058,13 @@ are actually shared. 3.10 /proc/<pid>/timerslack_ns - Task timerslack value --------------------------------------------------------- This file provides the value of the task's timerslack value in nanoseconds. -This value specifies a amount of time that normal timers may be deferred +This value specifies an amount of time that normal timers may be deferred in order to coalesce timers and avoid unnecessary wakeups. -This allows a task's interactivity vs power consumption trade off to be +This allows a task's interactivity vs power consumption tradeoff to be adjusted. -Writing 0 to the file will set the tasks timerslack to the default value. +Writing 0 to the file will set the task's timerslack to the default value. Valid values are from 0 - ULLONG_MAX @@ -2105,10 +2104,10 @@ Example Description ~~~~~~~~~~~ -x86 specific entries: +x86 specific entries ~~~~~~~~~~~~~~~~~~~~~ -AVX512_elapsed_ms: +AVX512_elapsed_ms ^^^^^^^^^^^^^^^^^^ If AVX512 is supported on the machine, this entry shows the milliseconds @@ -2134,8 +2133,8 @@ AVX512_elapsed_ms: the task is unlikely an AVX512 user, but depends on the workload and the scheduling scenario, it also could be a false negative mentioned above. -Configuring procfs ------------------- +Chapter 4: Configuring procfs +============================= 4.1 Mount options --------------------- @@ -2178,47 +2177,45 @@ information about processes information, just add identd to this group. subset=pid hides all top level files and directories in the procfs that are not related to tasks. -5 Filesystem behavior ----------------------------- +Chapter 5: Filesystem behavior +============================== Originally, before the advent of pid namepsace, procfs was a global file system. It means that there was only one procfs instance in the system. When pid namespace was added, a separate procfs instance was mounted in each pid namespace. So, procfs mount options are global among all -mountpoints within the same namespace. - -:: +mountpoints within the same namespace:: -# grep ^proc /proc/mounts -proc /proc proc rw,relatime,hidepid=2 0 0 + # grep ^proc /proc/mounts + proc /proc proc rw,relatime,hidepid=2 0 0 -# strace -e mount mount -o hidepid=1 -t proc proc /tmp/proc -mount("proc", "/tmp/proc", "proc", 0, "hidepid=1") = 0 -+++ exited with 0 +++ + # strace -e mount mount -o hidepid=1 -t proc proc /tmp/proc + mount("proc", "/tmp/proc", "proc", 0, "hidepid=1") = 0 + +++ exited with 0 +++ -# grep ^proc /proc/mounts -proc /proc proc rw,relatime,hidepid=2 0 0 -proc /tmp/proc proc rw,relatime,hidepid=2 0 0 + # grep ^proc /proc/mounts + proc /proc proc rw,relatime,hidepid=2 0 0 + proc /tmp/proc proc rw,relatime,hidepid=2 0 0 and only after remounting procfs mount options will change at all -mountpoints. +mountpoints:: -# mount -o remount,hidepid=1 -t proc proc /tmp/proc + # mount -o remount,hidepid=1 -t proc proc /tmp/proc -# grep ^proc /proc/mounts -proc /proc proc rw,relatime,hidepid=1 0 0 -proc /tmp/proc proc rw,relatime,hidepid=1 0 0 + # grep ^proc /proc/mounts + proc /proc proc rw,relatime,hidepid=1 0 0 + proc /tmp/proc proc rw,relatime,hidepid=1 0 0 This behavior is different from the behavior of other filesystems. The new procfs behavior is more like other filesystems. Each procfs mount creates a new procfs instance. Mount options affect own procfs instance. It means that it became possible to have several procfs instances -displaying tasks with different filtering options in one pid namespace. +displaying tasks with different filtering options in one pid namespace:: -# mount -o hidepid=invisible -t proc proc /proc -# mount -o hidepid=noaccess -t proc proc /tmp/proc -# grep ^proc /proc/mounts -proc /proc proc rw,relatime,hidepid=invisible 0 0 -proc /tmp/proc proc rw,relatime,hidepid=noaccess 0 0 + # mount -o hidepid=invisible -t proc proc /proc + # mount -o hidepid=noaccess -t proc proc /tmp/proc + # grep ^proc /proc/mounts + proc /proc proc rw,relatime,hidepid=invisible 0 0 + proc /tmp/proc proc rw,relatime,hidepid=noaccess 0 0 diff --git a/Documentation/filesystems/quota.rst b/Documentation/filesystems/quota.rst index a30cdd47c652..abd4303c546e 100644 --- a/Documentation/filesystems/quota.rst +++ b/Documentation/filesystems/quota.rst @@ -18,7 +18,7 @@ Quota limits (and amount of grace time) are set independently for each filesystem. For more details about quota design, see the documentation in quota-tools package -(http://sourceforge.net/projects/linuxquota). +(https://sourceforge.net/projects/linuxquota). Quota netlink interface ======================= @@ -31,11 +31,11 @@ the above events to userspace. There they can be captured by an application and processed accordingly. The interface uses generic netlink framework (see -http://lwn.net/Articles/208755/ and http://people.suug.ch/~tgr/libnl/ for more -details about this layer). The name of the quota generic netlink interface -is "VFS_DQUOT". Definitions of constants below are in <linux/quota.h>. -Since the quota netlink protocol is not namespace aware, quota netlink messages -are sent only in initial network namespace. +https://lwn.net/Articles/208755/ and http://www.infradead.org/~tgr/libnl/ for +more details about this layer). The name of the quota generic netlink interface +is "VFS_DQUOT". Definitions of constants below are in <linux/quota.h>. Since +the quota netlink protocol is not namespace aware, quota netlink messages are +sent only in initial network namespace. Currently, the interface supports only one message type QUOTA_NL_C_WARNING. This command is used to send a notification about any of the above mentioned diff --git a/Documentation/filesystems/ramfs-rootfs-initramfs.rst b/Documentation/filesystems/ramfs-rootfs-initramfs.rst index 3fddacc6bf14..4598b0d90b60 100644 --- a/Documentation/filesystems/ramfs-rootfs-initramfs.rst +++ b/Documentation/filesystems/ramfs-rootfs-initramfs.rst @@ -246,15 +246,15 @@ If you don't already understand what shared libraries, devices, and paths you need to get a minimal root filesystem up and running, here are some references: -- http://www.tldp.org/HOWTO/Bootdisk-HOWTO/ -- http://www.tldp.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html +- https://www.tldp.org/HOWTO/Bootdisk-HOWTO/ +- https://www.tldp.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html - http://www.linuxfromscratch.org/lfs/view/stable/ -The "klibc" package (http://www.kernel.org/pub/linux/libs/klibc) is +The "klibc" package (https://www.kernel.org/pub/linux/libs/klibc) is designed to be a tiny C library to statically link early userspace code against, along with some related utilities. It is BSD licensed. -I use uClibc (http://www.uclibc.org) and busybox (http://www.busybox.net) +I use uClibc (https://www.uclibc.org) and busybox (https://www.busybox.net) myself. These are LGPL and GPL, respectively. (A self-contained initramfs package is planned for the busybox 1.3 release.) diff --git a/Documentation/filesystems/sysfs-pci.rst b/Documentation/filesystems/sysfs-pci.rst index a265f3e2cc80..742fbd21dc1f 100644 --- a/Documentation/filesystems/sysfs-pci.rst +++ b/Documentation/filesystems/sysfs-pci.rst @@ -63,7 +63,7 @@ files, each with their own function. binary - file contains binary data cpumask - file contains a cpumask type -.. [1] rw for RESOURCE_IO (I/O port) regions only +.. [1] rw for IORESOURCE_IO (I/O port) regions only The read only files are informational, writes to them will be ignored, with the exception of the 'rom' file. Writable files can be used to perform diff --git a/Documentation/filesystems/sysfs-tagging.rst b/Documentation/filesystems/sysfs-tagging.rst index 8888a05c398e..83647e10c207 100644 --- a/Documentation/filesystems/sysfs-tagging.rst +++ b/Documentation/filesystems/sysfs-tagging.rst @@ -15,7 +15,7 @@ To avoid that problem and allow existing applications in network namespaces to see the same interface that is currently presented in sysfs, sysfs now has tagging directory support. -By using the network namespace pointers as tags to separate out the +By using the network namespace pointers as tags to separate out the sysfs directory entries we ensure that we don't have conflicts in the directories and applications only see a limited set of the network devices. diff --git a/Documentation/filesystems/tmpfs.rst b/Documentation/filesystems/tmpfs.rst index 4e95929301a5..c44f8b1d3cab 100644 --- a/Documentation/filesystems/tmpfs.rst +++ b/Documentation/filesystems/tmpfs.rst @@ -150,6 +150,22 @@ These options do not have any effect on remount. You can change these parameters with chmod(1), chown(1) and chgrp(1) on a mounted filesystem. +tmpfs has a mount option to select whether it will wrap at 32- or 64-bit inode +numbers: + +======= ======================== +inode64 Use 64-bit inode numbers +inode32 Use 32-bit inode numbers +======= ======================== + +On a 32-bit kernel, inode32 is implicit, and inode64 is refused at mount time. +On a 64-bit kernel, CONFIG_TMPFS_INODE64 sets the default. inode64 avoids the +possibility of multiple files with the same inode number on a single device; +but risks glibc failing with EOVERFLOW once 33-bit inode numbers are reached - +if a long-lived tmpfs is accessed by 32-bit applications so ancient that +opening a file larger than 2GiB fails with EINVAL. + + So 'mount -t tmpfs -o size=10G,nr_inodes=10k,mode=700 tmpfs /mytmpfs' will give you tmpfs instance on /mytmpfs which can allocate 10GB RAM/SWAP in 10240 inodes and it is only accessible by root. @@ -161,3 +177,5 @@ RAM/SWAP in 10240 inodes and it is only accessible by root. Hugh Dickins, 4 June 2007 :Updated: KOSAKI Motohiro, 16 Mar 2010 +:Updated: + Chris Down, 13 July 2020 diff --git a/Documentation/filesystems/ubifs-authentication.rst b/Documentation/filesystems/ubifs-authentication.rst index 16efd729bf7c..1f39c8cea702 100644 --- a/Documentation/filesystems/ubifs-authentication.rst +++ b/Documentation/filesystems/ubifs-authentication.rst @@ -433,9 +433,9 @@ will then have to be provided beforehand in the normal way. References ========== -[CRYPTSETUP2] http://www.saout.de/pipermail/dm-crypt/2017-November/005745.html +[CRYPTSETUP2] https://www.saout.de/pipermail/dm-crypt/2017-November/005745.html -[DMC-CBC-ATTACK] http://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/ +[DMC-CBC-ATTACK] https://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/ [DM-INTEGRITY] https://www.kernel.org/doc/Documentation/device-mapper/dm-integrity.rst diff --git a/Documentation/filesystems/udf.rst b/Documentation/filesystems/udf.rst index d9badbf285b2..f9489ddbb767 100644 --- a/Documentation/filesystems/udf.rst +++ b/Documentation/filesystems/udf.rst @@ -72,4 +72,4 @@ For the latest version and toolset see: Documentation on UDF and ECMA 167 is available FREE from: - http://www.osta.org/ - - http://www.ecma-international.org/ + - https://www.ecma-international.org/ diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index ed17771c212b..ca52c82e5bb5 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -392,7 +392,7 @@ Extended attributes are name:value pairs. ``set`` Called by the VFS to set the value of a particular extended attribute. When the new value is NULL, called to remove a - particular extended attribute. This method is called by the the + particular extended attribute. This method is called by the setxattr(2) and removexattr(2) system calls. When none of the xattr handlers of a filesystem match the specified @@ -652,7 +652,7 @@ at any point after PG_Dirty is clear. Once it is known to be safe, PG_Writeback is cleared. Writeback makes use of a writeback_control structure to direct the -operations. This gives the the writepage and writepages operations some +operations. This gives the writepage and writepages operations some information about the nature of and reason for the writeback request, and the constraints under which it is being done. It is also used to return information back to the caller about the result of a writepage or @@ -766,9 +766,9 @@ cache in your filesystem. The following members are defined: ``writepages`` called by the VM to write out pages associated with the - address_space object. If wbc->sync_mode is WBC_SYNC_ALL, then + address_space object. If wbc->sync_mode is WB_SYNC_ALL, then the writeback_control will specify a range of pages that must be - written out. If it is WBC_SYNC_NONE, then a nr_to_write is + written out. If it is WB_SYNC_NONE, then a nr_to_write is given and that many pages should be written if possible. If no ->writepages is given, then mpage_writepages is used instead. This will choose pages from the address space that are tagged as @@ -1116,7 +1116,7 @@ otherwise noted. before any bytes were remapped. The remap_flags parameter accepts REMAP_FILE_* flags. If REMAP_FILE_DEDUP is set then the implementation must only remap if the requested file ranges have - identical contents. If REMAP_CAN_SHORTEN is set, the caller is + identical contents. If REMAP_FILE_CAN_SHORTEN is set, the caller is ok with the implementation shortening the request length to satisfy alignment or EOF requirements (or any other reason). @@ -1431,13 +1431,13 @@ Resources version.) Creating Linux virtual filesystems. 2002 - <http://lwn.net/Articles/13325/> + <https://lwn.net/Articles/13325/> The Linux Virtual File-system Layer by Neil Brown. 1999 <http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/vfs.html> A tour of the Linux VFS by Michael K. Johnson. 1996 - <http://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html> + <https://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html> A small trail through the Linux kernel by Andries Brouwer. 2001 - <http://www.win.tue.nl/~aeb/linux/vfs/trail.html> + <https://www.win.tue.nl/~aeb/linux/vfs/trail.html> diff --git a/Documentation/firmware-guide/acpi/DSD-properties-rules.rst b/Documentation/firmware-guide/acpi/DSD-properties-rules.rst index 4306f29b6103..8b2d8d0864c2 100644 --- a/Documentation/firmware-guide/acpi/DSD-properties-rules.rst +++ b/Documentation/firmware-guide/acpi/DSD-properties-rules.rst @@ -96,5 +96,5 @@ contents. References ========== -.. [1] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf -.. [2] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf +.. [1] https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf +.. [2] https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf diff --git a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst index febccbc5689d..9b17dc77d18c 100644 --- a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst +++ b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst @@ -85,9 +85,9 @@ References ========== [1] Hierarchical Data Extension UUID For _DSD. -<http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, +<https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, referenced 2018-07-17. [2] Device Properties UUID For _DSD. -<http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, +<https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, referenced 2016-10-04. diff --git a/Documentation/firmware-guide/acpi/dsd/graph.rst b/Documentation/firmware-guide/acpi/dsd/graph.rst index 1a6ce7afba5e..7072db801aeb 100644 --- a/Documentation/firmware-guide/acpi/dsd/graph.rst +++ b/Documentation/firmware-guide/acpi/dsd/graph.rst @@ -154,23 +154,23 @@ References ========== [1] _DSD (Device Specific Data) Implementation Guide. - http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm, + https://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm, referenced 2016-10-03. -[2] Devicetree. http://www.devicetree.org, referenced 2016-10-03. +[2] Devicetree. https://www.devicetree.org, referenced 2016-10-03. [3] Documentation/devicetree/bindings/graph.txt [4] Device Properties UUID For _DSD. - http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf, + https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf, referenced 2016-10-04. [5] Hierarchical Data Extension UUID For _DSD. - http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf, + https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf, referenced 2016-10-04. [6] Advanced Configuration and Power Interface Specification. - http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf, + https://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf, referenced 2016-10-04. [7] _DSD Device Properties Usage Rules. diff --git a/Documentation/firmware-guide/acpi/dsd/leds.rst b/Documentation/firmware-guide/acpi/dsd/leds.rst index 946efe2b2936..aba1e9abfeeb 100644 --- a/Documentation/firmware-guide/acpi/dsd/leds.rst +++ b/Documentation/firmware-guide/acpi/dsd/leds.rst @@ -90,7 +90,7 @@ where References ========== -[1] Device tree. <URL:http://www.devicetree.org>, referenced 2019-02-21. +[1] Device tree. <URL:https://www.devicetree.org>, referenced 2019-02-21. [2] Advanced Configuration and Power Interface Specification. <URL:https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf>, @@ -101,11 +101,11 @@ References [4] Documentation/devicetree/bindings/media/video-interfaces.txt [5] Device Properties UUID For _DSD. - <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, + <URL:https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, referenced 2019-02-21. [6] Hierarchical Data Extension UUID For _DSD. - <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, + <URL:https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, referenced 2019-02-21. [7] Documentation/firmware-guide/acpi/dsd/data-node-references.rst diff --git a/Documentation/firmware-guide/acpi/lpit.rst b/Documentation/firmware-guide/acpi/lpit.rst index aca928fab027..37922a903573 100644 --- a/Documentation/firmware-guide/acpi/lpit.rst +++ b/Documentation/firmware-guide/acpi/lpit.rst @@ -7,7 +7,7 @@ Low Power Idle Table (LPIT) To enumerate platform Low Power Idle states, Intel platforms are using “Low Power Idle Table†(LPIT). More details about this table can be downloaded from: -http://www.uefi.org/sites/default/files/resources/Intel_ACPI_Low_Power_S0_Idle.pdf +https://www.uefi.org/sites/default/files/resources/Intel_ACPI_Low_Power_S0_Idle.pdf Residencies for each low power state can be read via FFH (Function fixed hardware) or a memory mapped interface. diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst index 978c4af416a4..0404fe6ffc74 100644 --- a/Documentation/fpga/dfl.rst +++ b/Documentation/fpga/dfl.rst @@ -8,7 +8,7 @@ Authors: - Xiao Guangrong <guangrong.xiao@linux.intel.com> - Wu Hao <hao.wu@intel.com> -The Device Feature List (DFL) FPGA framework (and drivers according to this +The Device Feature List (DFL) FPGA framework (and drivers according to this framework) hides the very details of low layer hardwares and provides unified interfaces to userspace. Applications could use these interfaces to configure, enumerate, open and access FPGA accelerators on platforms which @@ -89,6 +89,8 @@ The following functions are exposed through ioctls: - Program bitstream (DFL_FPGA_FME_PORT_PR) - Assign port to PF (DFL_FPGA_FME_PORT_ASSIGN) - Release port from PF (DFL_FPGA_FME_PORT_RELEASE) +- Get number of irqs of FME global error (DFL_FPGA_FME_ERR_GET_IRQ_NUM) +- Set interrupt trigger for FME error (DFL_FPGA_FME_ERR_SET_IRQ) More functions are exposed through sysfs (/sys/class/fpga_region/regionX/dfl-fme.n/): @@ -149,6 +151,10 @@ The following functions are exposed through ioctls: - Map DMA buffer (DFL_FPGA_PORT_DMA_MAP) - Unmap DMA buffer (DFL_FPGA_PORT_DMA_UNMAP) - Reset AFU (DFL_FPGA_PORT_RESET) +- Get number of irqs of port error (DFL_FPGA_PORT_ERR_GET_IRQ_NUM) +- Set interrupt trigger for port error (DFL_FPGA_PORT_ERR_SET_IRQ) +- Get number of irqs of UINT (DFL_FPGA_PORT_UINT_GET_IRQ_NUM) +- Set interrupt trigger for UINT (DFL_FPGA_PORT_UINT_SET_IRQ) DFL_FPGA_PORT_RESET: reset the FPGA Port and its AFU. Userspace can do Port @@ -462,6 +468,19 @@ since they are system-wide counters on FPGA device. The current driver does not support sampling. So "perf record" is unsupported. +Interrupt support +================= +Some FME and AFU private features are able to generate interrupts. As mentioned +above, users could call ioctl (DFL_FPGA_*_GET_IRQ_NUM) to know whether or how +many interrupts are supported for this private feature. Drivers also implement +an eventfd based interrupt handling mechanism for users to get notified when +interrupt happens. Users could set eventfds to driver via +ioctl (DFL_FPGA_*_SET_IRQ), and then poll/select on these eventfds waiting for +notification. +In Current DFL, 3 sub features (Port error, FME global error and AFU interrupt) +support interrupts. + + Add new FIUs support ==================== It's possible that developers made some new function blocks (FIUs) under this diff --git a/Documentation/gpu/amdgpu.rst b/Documentation/gpu/amdgpu.rst index 4cc74325bf91..17112352f605 100644 --- a/Documentation/gpu/amdgpu.rst +++ b/Documentation/gpu/amdgpu.rst @@ -197,11 +197,14 @@ pp_power_profile_mode .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c :doc: pp_power_profile_mode -busy_percent -~~~~~~~~~~~~ +*_busy_percent +~~~~~~~~~~~~~~ .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c - :doc: busy_percent + :doc: gpu_busy_percent + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c + :doc: mem_busy_percent GPU Product Information ======================= diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index ee730457bf4e..b89ddd06dabb 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -411,15 +411,3 @@ Legacy CRTC/Modeset Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c :export: - -SHMEM GEM Helper Reference -========================== - -.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c - :doc: overview - -.. kernel-doc:: include/drm/drm_gem_shmem_helper.h - :internal: - -.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c - :export: diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 397314d08f77..3c5ae4f6dfd2 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -460,6 +460,12 @@ HDMI Specific Connector Properties .. kernel-doc:: drivers/gpu/drm/drm_connector.c :doc: HDMI connector properties +Standard CRTC Properties +------------------------ + +.. kernel-doc:: drivers/gpu/drm/drm_crtc.c + :doc: standard CRTC properties + Plane Composition Properties ---------------------------- @@ -537,3 +543,18 @@ Vertical Blanking and Interrupt Handling Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_vblank.c :export: + +Vertical Blank Work +=================== + +.. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c + :doc: vblank works + +Vertical Blank Work Functions Reference +--------------------------------------- + +.. kernel-doc:: include/drm/drm_vblank_work.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c + :export: diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index 1839762044be..9abee1589c1e 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -179,10 +179,7 @@ GEM Objects Lifetime All GEM objects are reference-counted by the GEM core. References can be acquired and release by calling drm_gem_object_get() and drm_gem_object_put() -respectively. The caller must hold the :c:type:`struct drm_device <drm_device>` -struct_mutex lock when calling drm_gem_object_get(). As a convenience, GEM -provides drm_gem_object_put_unlocked() functions that can be called without -holding the lock. +respectively. When the last reference to a GEM object is released the GEM core calls the :c:type:`struct drm_driver <drm_driver>` gem_free_object_unlocked @@ -314,7 +311,7 @@ To use drm_gem_cma_get_unmapped_area(), drivers must fill the struct a pointer on drm_gem_cma_get_unmapped_area(). More detailed information about get_unmapped_area can be found in -Documentation/nommu-mmap.txt +Documentation/admin-guide/mm/nommu-mmap.rst Memory Coherency ---------------- @@ -373,6 +370,18 @@ GEM CMA Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c :export: +GEM SHMEM Helper Function Reference +----------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c + :doc: overview + +.. kernel-doc:: include/drm/drm_gem_shmem_helper.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c + :export: + GEM VRAM Helper Functions Reference ----------------------------------- diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 56fec6ed1ad8..496d8fcd4da0 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -195,7 +195,7 @@ ENOSPC: EPERM/EACCES: Returned for an operation that is valid, but needs more privileges. E.g. root-only or much more common, DRM master-only operations return - this when when called by unpriviledged clients. There's no clear + this when called by unpriviledged clients. There's no clear difference between EACCES and EPERM. ENODEV: diff --git a/Documentation/gpu/komeda-kms.rst b/Documentation/gpu/komeda-kms.rst index b08da1cffecc..eb693c857e2d 100644 --- a/Documentation/gpu/komeda-kms.rst +++ b/Documentation/gpu/komeda-kms.rst @@ -41,7 +41,7 @@ Compositor blends multiple layers or pixel data flows into one single display frame. its output frame can be fed into post image processor for showing it on the monitor or fed into wb_layer and written to memory at the same time. user can also insert a scaler between compositor and wb_layer to down scale -the display frame first and and then write to memory. +the display frame first and then write to memory. Writeback Layer (wb_layer) -------------------------- diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 658b52f7ffc6..7969f106877d 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -157,8 +157,8 @@ private lock. The tricky part is the BO free functions, since those can't reliably take that lock any more. Instead state needs to be protected with suitable subordinate locks or some cleanup work pushed to a worker thread. For performance-critical drivers it might also be better to go with a more -fine-grained per-buffer object and per-context lockings scheme. Currently only the -``msm`` driver still use ``struct_mutex``. +fine-grained per-buffer object and per-context lockings scheme. Currently only +the ``msm`` and `i915` drivers use ``struct_mutex``. Contact: Daniel Vetter, respective driver maintainers @@ -305,7 +305,7 @@ acquire context. Replace the boilerplate code surrounding drm_modeset_lock_all_ctx() with DRM_MODESET_LOCK_ALL_BEGIN() and DRM_MODESET_LOCK_ALL_END() instead. -This should also be done for all places where drm_modest_lock_all() is still +This should also be done for all places where drm_modeset_lock_all() is still used. As a reference, take a look at the conversions already completed in drm core. @@ -327,26 +327,6 @@ Contact: Laurent Pinchart, Daniel Vetter Level: Intermediate (mostly because it is a huge tasks without good partial milestones, not technically itself that challenging) -Convert direct mode.vrefresh accesses to use drm_mode_vrefresh() ----------------------------------------------------------------- - -drm_display_mode.vrefresh isn't guaranteed to be populated. As such, using it -is risky and has been known to cause div-by-zero bugs. Fortunately, drm core -has helper which will use mode.vrefresh if it's !0 and will calculate it from -the timings when it's 0. - -Use simple search/replace, or (more fun) cocci to replace instances of direct -vrefresh access with a call to the helper. Check out -https://lists.freedesktop.org/archives/dri-devel/2019-January/205186.html for -inspiration. - -Once all instances of vrefresh have been converted, remove vrefresh from -drm_display_mode to avoid future use. - -Contact: Sean Paul - -Level: Starter - connector register/unregister fixes ----------------------------------- @@ -392,6 +372,38 @@ Contact: Laurent Pinchart, respective driver maintainers Level: Intermediate +Consolidate custom driver modeset properties +-------------------------------------------- + +Before atomic modeset took place, many drivers where creating their own +properties. Among other things, atomic brought the requirement that custom, +driver specific properties should not be used. + +For this task, we aim to introduce core helpers or reuse the existing ones +if available: + +A quick, unconfirmed, examples list. + +Introduce core helpers: +- audio (amdgpu, intel, gma500, radeon) +- brightness, contrast, etc (armada, nouveau) - overlay only (?) +- broadcast rgb (gma500, intel) +- colorkey (armada, nouveau, rcar) - overlay only (?) +- dither (amdgpu, nouveau, radeon) - varies across drivers +- underscan family (amdgpu, radeon, nouveau) + +Already in core: +- colorspace (sti) +- tv format names, enhancements (gma500, intel) +- tv overscan, margins, etc. (gma500, intel) +- zorder (omapdrm) - same as zpos (?) + + +Contact: Emil Velikov, respective driver maintainers + +Level: Intermediate + + Core refactorings ================= diff --git a/Documentation/gpu/vgaarbiter.rst b/Documentation/gpu/vgaarbiter.rst index 0b41b051d021..339ed5fecd2e 100644 --- a/Documentation/gpu/vgaarbiter.rst +++ b/Documentation/gpu/vgaarbiter.rst @@ -185,7 +185,7 @@ enhancing the kernel code to adapt as a kernel module and also did the implementation of the user space side [3]. Now (2009) Tiago Vignatti and Dave Airlie finally put this work in shape and queued to Jesse Barnes' PCI tree. -0) http://cgit.freedesktop.org/xorg/xserver/commit/?id=4b42448a2388d40f257774fbffdccaea87bd0347 -1) http://lists.freedesktop.org/archives/xorg/2005-March/006663.html -2) http://lists.freedesktop.org/archives/xorg/2005-March/006745.html -3) http://lists.freedesktop.org/archives/xorg/2007-October/029507.html +0) https://cgit.freedesktop.org/xorg/xserver/commit/?id=4b42448a2388d40f257774fbffdccaea87bd0347 +1) https://lists.freedesktop.org/archives/xorg/2005-March/006663.html +2) https://lists.freedesktop.org/archives/xorg/2005-March/006745.html +3) https://lists.freedesktop.org/archives/xorg/2007-October/029507.html diff --git a/Documentation/hid/hiddev.rst b/Documentation/hid/hiddev.rst index 209e6ba4e019..9b28a97c03e6 100644 --- a/Documentation/hid/hiddev.rst +++ b/Documentation/hid/hiddev.rst @@ -65,7 +65,7 @@ The HIDDEV API ============== This description should be read in conjunction with the HID -specification, freely available from http://www.usb.org, and +specification, freely available from https://www.usb.org, and conveniently linked of http://www.linux-usb.org. The hiddev API uses a read() interface, and a set of ioctl() calls. diff --git a/Documentation/hid/intel-ish-hid.rst b/Documentation/hid/intel-ish-hid.rst index cccbf4be17d7..d4785cf6eefd 100644 --- a/Documentation/hid/intel-ish-hid.rst +++ b/Documentation/hid/intel-ish-hid.rst @@ -235,7 +235,7 @@ There can be multiple sensor clients and clients for calibration function. To ease in implantation and allow independent driver handle each client this transport layer takes advantage of Linux Bus driver model. Each -client is registered as device on the the transport bus (ishtp bus). +client is registered as device on the transport bus (ishtp bus). Enumeration sequence of messages: diff --git a/Documentation/hwmon/acpi_power_meter.rst b/Documentation/hwmon/acpi_power_meter.rst index 4a0941ade0ca..8628c1161015 100644 --- a/Documentation/hwmon/acpi_power_meter.rst +++ b/Documentation/hwmon/acpi_power_meter.rst @@ -9,7 +9,7 @@ Supported systems: Prefix: 'power_meter' - Datasheet: http://acpi.info/, section 10.4. + Datasheet: https://uefi.org/specifications, section 10.4. Author: Darrick J. Wong diff --git a/Documentation/hwmon/adc128d818.rst b/Documentation/hwmon/adc128d818.rst index 6753468932ab..d2488023430f 100644 --- a/Documentation/hwmon/adc128d818.rst +++ b/Documentation/hwmon/adc128d818.rst @@ -9,7 +9,7 @@ Supported chips: Addresses scanned: I2C 0x1d, 0x1e, 0x1f, 0x2d, 0x2e, 0x2f - Datasheet: Publicly available at the TI website http://www.ti.com/ + Datasheet: Publicly available at the TI website https://www.ti.com/ Author: Guenter Roeck diff --git a/Documentation/hwmon/adm1026.rst b/Documentation/hwmon/adm1026.rst index 35d63e6498a3..66f996fa3031 100644 --- a/Documentation/hwmon/adm1026.rst +++ b/Documentation/hwmon/adm1026.rst @@ -10,7 +10,7 @@ Supported chips: Datasheet: Publicly available at the Analog Devices website - http://www.onsemi.com/PowerSolutions/product.do?id=ADM1026 + https://www.onsemi.com/PowerSolutions/product.do?id=ADM1026 Authors: - Philip Pokorny <ppokorny@penguincomputing.com> for Penguin Computing diff --git a/Documentation/hwmon/adm1031.rst b/Documentation/hwmon/adm1031.rst index a677c3ab5574..be74ec1f3e73 100644 --- a/Documentation/hwmon/adm1031.rst +++ b/Documentation/hwmon/adm1031.rst @@ -10,7 +10,7 @@ Supported chips: Datasheet: Publicly available at the Analog Devices website - http://www.analog.com/en/prod/0%2C2877%2CADM1030%2C00.html + https://www.analog.com/en/prod/0%2C2877%2CADM1030%2C00.html * Analog Devices ADM1031 @@ -20,7 +20,7 @@ Supported chips: Datasheet: Publicly available at the Analog Devices website - http://www.analog.com/en/prod/0%2C2877%2CADM1031%2C00.html + https://www.analog.com/en/prod/0%2C2877%2CADM1031%2C00.html Authors: - Alexandre d'Alton <alex@alexdalton.org> diff --git a/Documentation/hwmon/adm1275.rst b/Documentation/hwmon/adm1275.rst index 49966ed70ec6..ce6528f90e4a 100644 --- a/Documentation/hwmon/adm1275.rst +++ b/Documentation/hwmon/adm1275.rst @@ -49,7 +49,7 @@ Supported chips: Addresses scanned: - - Datasheet: http://www.analog.com/media/en/technical-documentation/data-sheets/ADM1293_1294.pdf + Datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/ADM1293_1294.pdf Author: Guenter Roeck <linux@roeck-us.net> diff --git a/Documentation/hwmon/adt7410.rst b/Documentation/hwmon/adt7410.rst index 24caaa83c8ec..3f5a43561bf1 100644 --- a/Documentation/hwmon/adt7410.rst +++ b/Documentation/hwmon/adt7410.rst @@ -11,7 +11,7 @@ Supported chips: Datasheet: Publicly available at the Analog Devices website - http://www.analog.com/static/imported-files/data_sheets/ADT7410.pdf + https://www.analog.com/static/imported-files/data_sheets/ADT7410.pdf * Analog Devices ADT7420 Prefix: 'adt7420' @@ -20,7 +20,7 @@ Supported chips: Datasheet: Publicly available at the Analog Devices website - http://www.analog.com/static/imported-files/data_sheets/ADT7420.pdf + https://www.analog.com/static/imported-files/data_sheets/ADT7420.pdf * Analog Devices ADT7310 @@ -30,7 +30,7 @@ Supported chips: Datasheet: Publicly available at the Analog Devices website - http://www.analog.com/static/imported-files/data_sheets/ADT7310.pdf + https://www.analog.com/static/imported-files/data_sheets/ADT7310.pdf * Analog Devices ADT7320 @@ -40,7 +40,7 @@ Supported chips: Datasheet: Publicly available at the Analog Devices website - http://www.analog.com/static/imported-files/data_sheets/ADT7320.pdf + https://www.analog.com/static/imported-files/data_sheets/ADT7320.pdf Author: Hartmut Knaack <knaack.h@gmx.de> diff --git a/Documentation/hwmon/corsair-cpro.rst b/Documentation/hwmon/corsair-cpro.rst new file mode 100644 index 000000000000..751f95476b57 --- /dev/null +++ b/Documentation/hwmon/corsair-cpro.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver corsair-cpro +========================== + +Supported devices: + + * Corsair Commander Pro + * Corsair Commander Pro (1000D) + +Author: Marius Zachmann + +Description +----------- + +This driver implements the sysfs interface for the Corsair Commander Pro. +The Corsair Commander Pro is a USB device with 6 fan connectors, +4 temperature sensor connectors and 2 Corsair LED connectors. +It can read the voltage levels on the SATA power connector. + +Usage Notes +----------- + +Since it is a USB device, hotswapping is possible. The device is autodetected. + +Sysfs entries +------------- + +======================= ===================================================================== +in0_input Voltage on SATA 12v +in1_input Voltage on SATA 5v +in2_input Voltage on SATA 3.3v +temp[1-4]_input Temperature on connected temperature sensors +fan[1-6]_input Connected fan rpm. +fan[1-6]_label Shows fan type as detected by the device. +fan[1-6]_target Sets fan speed target rpm. + When reading, it reports the last value if it was set by the driver. + Otherwise returns an error. +pwm[1-6] Sets the fan speed. Values from 0-255. Can only be read if pwm + was set directly. +======================= ===================================================================== diff --git a/Documentation/hwmon/emc1403.rst b/Documentation/hwmon/emc1403.rst index 3a4913b63ef3..0de9616b24ed 100644 --- a/Documentation/hwmon/emc1403.rst +++ b/Documentation/hwmon/emc1403.rst @@ -12,7 +12,7 @@ Supported chips: Datasheets: - http://ww1.microchip.com/downloads/en/DeviceDoc/1412.pdf - - http://ww1.microchip.com/downloads/en/DeviceDoc/1402.pdf + - https://ww1.microchip.com/downloads/en/DeviceDoc/1402.pdf * SMSC / Microchip EMC1403, EMC1404, EMC1413, EMC1414 @@ -33,7 +33,7 @@ Supported chips: Datasheet: - - http://ww1.microchip.com/downloads/en/DeviceDoc/1422.pdf + - https://ww1.microchip.com/downloads/en/DeviceDoc/1422.pdf * SMSC / Microchip EMC1423, EMC1424 @@ -43,7 +43,7 @@ Supported chips: Datasheet: - - http://ww1.microchip.com/downloads/en/DeviceDoc/1423_1424.pdf + - https://ww1.microchip.com/downloads/en/DeviceDoc/1423_1424.pdf Author: Kalhan Trisal <kalhan.trisal@intel.com diff --git a/Documentation/hwmon/f71882fg.rst b/Documentation/hwmon/f71882fg.rst index 5c0b7b0db150..38e30fbd4806 100644 --- a/Documentation/hwmon/f71882fg.rst +++ b/Documentation/hwmon/f71882fg.rst @@ -145,7 +145,7 @@ motherboard, so the driver assumes that the BIOS set the method properly. Note that the lowest numbered temperature zone trip point corresponds to -to the border between the highest and one but highest temperature zones, and +the border between the highest and one but highest temperature zones, and vica versa. So the temperature zone trip points 1-4 (or 1-2) go from high temp to low temp! This is how things are implemented in the IC, and the driver mimics this. diff --git a/Documentation/hwmon/ina209.rst b/Documentation/hwmon/ina209.rst index 64322075a145..162256131517 100644 --- a/Documentation/hwmon/ina209.rst +++ b/Documentation/hwmon/ina209.rst @@ -10,7 +10,7 @@ Supported chips: Addresses scanned: - Datasheet: - http://www.ti.com/lit/gpn/ina209 + https://www.ti.com/lit/gpn/ina209 Author: - Paul Hays <Paul.Hays@cattail.ca> diff --git a/Documentation/hwmon/ina2xx.rst b/Documentation/hwmon/ina2xx.rst index ed81f5416331..f78a5cd44c4c 100644 --- a/Documentation/hwmon/ina2xx.rst +++ b/Documentation/hwmon/ina2xx.rst @@ -11,7 +11,7 @@ Supported chips: Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/ + https://www.ti.com/ * Texas Instruments INA220 @@ -21,7 +21,7 @@ Supported chips: Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/ + https://www.ti.com/ * Texas Instruments INA226 @@ -31,7 +31,7 @@ Supported chips: Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/ + https://www.ti.com/ * Texas Instruments INA230 @@ -41,7 +41,7 @@ Supported chips: Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/ + https://www.ti.com/ * Texas Instruments INA231 @@ -51,7 +51,7 @@ Supported chips: Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/ + https://www.ti.com/ Author: Lothar Felten <lothar.felten@gmail.com> diff --git a/Documentation/hwmon/ina3221.rst b/Documentation/hwmon/ina3221.rst index 297f7323b441..8c12c54d2c24 100644 --- a/Documentation/hwmon/ina3221.rst +++ b/Documentation/hwmon/ina3221.rst @@ -11,7 +11,7 @@ Supported chips: Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/ + https://www.ti.com/ Author: Andrew F. Davis <afd@ti.com> diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index 55ff4b7c5349..750d3a975d82 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -47,6 +47,7 @@ Hardware Monitoring Kernel Drivers bel-pfe bt1-pvt coretemp + corsair-cpro da9052 da9055 dell-smm-hwmon diff --git a/Documentation/hwmon/jc42.rst b/Documentation/hwmon/jc42.rst index 5b14b49bb6f7..19d10512f6c0 100644 --- a/Documentation/hwmon/jc42.rst +++ b/Documentation/hwmon/jc42.rst @@ -7,7 +7,7 @@ Supported chips: Datasheets: - http://www.analog.com/static/imported-files/data_sheets/ADT7408.pdf + https://www.analog.com/static/imported-files/data_sheets/ADT7408.pdf * Atmel AT30TS00, AT30TS002A/B, AT30TSE004A @@ -39,37 +39,37 @@ Supported chips: Datasheets: - http://ww1.microchip.com/downloads/en/DeviceDoc/22203C.pdf + https://ww1.microchip.com/downloads/en/DeviceDoc/22203C.pdf - http://ww1.microchip.com/downloads/en/DeviceDoc/21977b.pdf + https://ww1.microchip.com/downloads/en/DeviceDoc/21977b.pdf - http://ww1.microchip.com/downloads/en/DeviceDoc/25095A.pdf + https://ww1.microchip.com/downloads/en/DeviceDoc/25095A.pdf - http://ww1.microchip.com/downloads/en/DeviceDoc/21996a.pdf + https://ww1.microchip.com/downloads/en/DeviceDoc/21996a.pdf - http://ww1.microchip.com/downloads/en/DeviceDoc/22153c.pdf + https://ww1.microchip.com/downloads/en/DeviceDoc/22153c.pdf - http://ww1.microchip.com/downloads/en/DeviceDoc/22327A.pdf + https://ww1.microchip.com/downloads/en/DeviceDoc/22327A.pdf * NXP Semiconductors SE97, SE97B, SE98, SE98A Datasheets: - http://www.nxp.com/documents/data_sheet/SE97.pdf + https://www.nxp.com/documents/data_sheet/SE97.pdf - http://www.nxp.com/documents/data_sheet/SE97B.pdf + https://www.nxp.com/documents/data_sheet/SE97B.pdf - http://www.nxp.com/documents/data_sheet/SE98.pdf + https://www.nxp.com/documents/data_sheet/SE98.pdf - http://www.nxp.com/documents/data_sheet/SE98A.pdf + https://www.nxp.com/documents/data_sheet/SE98A.pdf * ON Semiconductor CAT34TS02, CAT6095 Datasheet: - http://www.onsemi.com/pub_link/Collateral/CAT34TS02-D.PDF + https://www.onsemi.com/pub_link/Collateral/CAT34TS02-D.PDF - http://www.onsemi.com/pub/Collateral/CAT6095-D.PDF + https://www.onsemi.com/pub/Collateral/CAT6095-D.PDF * ST Microelectronics STTS424, STTS424E02, STTS2002, STTS2004, STTS3000 diff --git a/Documentation/hwmon/k8temp.rst b/Documentation/hwmon/k8temp.rst index fe9109521056..ab25a73e778f 100644 --- a/Documentation/hwmon/k8temp.rst +++ b/Documentation/hwmon/k8temp.rst @@ -9,7 +9,7 @@ Supported chips: Addresses scanned: PCI space - Datasheet: http://www.amd.com/system/files/TechDocs/32559.pdf + Datasheet: https://www.amd.com/system/files/TechDocs/32559.pdf Author: Rudolf Marek diff --git a/Documentation/hwmon/lm25066.rst b/Documentation/hwmon/lm25066.rst index 30e6e77fb3c8..9f1d7e4d3ca1 100644 --- a/Documentation/hwmon/lm25066.rst +++ b/Documentation/hwmon/lm25066.rst @@ -11,9 +11,9 @@ Supported chips: Datasheets: - http://www.ti.com/lit/gpn/lm25056 + https://www.ti.com/lit/gpn/lm25056 - http://www.ti.com/lit/gpn/lm25056a + https://www.ti.com/lit/gpn/lm25056a * National Semiconductor LM25066 @@ -55,7 +55,7 @@ Supported chips: Datasheet: - http://www.ti.com/product/LM5066I + https://www.ti.com/product/LM5066I Author: Guenter Roeck <linux@roeck-us.net> diff --git a/Documentation/hwmon/lm63.rst b/Documentation/hwmon/lm63.rst index f478132b0408..9e27367d7405 100644 --- a/Documentation/hwmon/lm63.rst +++ b/Documentation/hwmon/lm63.rst @@ -39,7 +39,7 @@ Author: Jean Delvare <jdelvare@suse.de> Thanks go to Tyan and especially Alex Buckingham for setting up a remote access to their S4882 test platform for this driver. - http://www.tyan.com/ + https://www.tyan.com/ Description ----------- diff --git a/Documentation/hwmon/lm70.rst b/Documentation/hwmon/lm70.rst index f259bc1fcd91..6ddc5b67ccb5 100644 --- a/Documentation/hwmon/lm70.rst +++ b/Documentation/hwmon/lm70.rst @@ -13,15 +13,15 @@ Supported chips: * Texas Instruments TMP122/TMP124 - Information: http://www.ti.com/product/tmp122 + Information: https://www.ti.com/product/tmp122 * National Semiconductor LM71 - Datasheet: http://www.ti.com/product/LM71 + Datasheet: https://www.ti.com/product/LM71 * National Semiconductor LM74 - Datasheet: http://www.ti.com/product/LM74 + Datasheet: https://www.ti.com/product/LM74 Author: diff --git a/Documentation/hwmon/lm73.rst b/Documentation/hwmon/lm73.rst index 1d6a46844e85..74e909be6ef7 100644 --- a/Documentation/hwmon/lm73.rst +++ b/Documentation/hwmon/lm73.rst @@ -11,7 +11,7 @@ Supported chips: Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/product/lm73 + https://www.ti.com/product/lm73 Author: Guillaume Ligneul <guillaume.ligneul@gmail.com> diff --git a/Documentation/hwmon/lm75.rst b/Documentation/hwmon/lm75.rst index e749f827c002..81257d5fc48f 100644 --- a/Documentation/hwmon/lm75.rst +++ b/Documentation/hwmon/lm75.rst @@ -31,7 +31,7 @@ Supported chips: Datasheet: Publicly available at the Maxim website - http://www.maximintegrated.com/ + https://www.maximintegrated.com/ * Maxim MAX6625, MAX6626, MAX31725, MAX31726 @@ -71,7 +71,7 @@ Supported chips: Datasheet: Publicly available at the Analog Devices website - http://www.analog.com/adt75 + https://www.analog.com/adt75 * ST Microelectronics STDS75 @@ -101,23 +101,23 @@ Supported chips: Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/product/tmp100 + https://www.ti.com/product/tmp100 - http://www.ti.com/product/tmp101 + https://www.ti.com/product/tmp101 - http://www.ti.com/product/tmp105 + https://www.ti.com/product/tmp105 - http://www.ti.com/product/tmp112 + https://www.ti.com/product/tmp112 - http://www.ti.com/product/tmp75 + https://www.ti.com/product/tmp75 - http://www.ti.com/product/tmp75b + https://www.ti.com/product/tmp75b - http://www.ti.com/product/tmp75c + https://www.ti.com/product/tmp75c - http://www.ti.com/product/tmp175 + https://www.ti.com/product/tmp175 - http://www.ti.com/product/tmp275 + https://www.ti.com/product/tmp275 * NXP LM75B, PCT2075 @@ -127,9 +127,9 @@ Supported chips: Datasheet: Publicly available at the NXP website - http://www.nxp.com/documents/data_sheet/LM75B.pdf + https://www.nxp.com/documents/data_sheet/LM75B.pdf - http://www.nxp.com/docs/en/data-sheet/PCT2075.pdf + https://www.nxp.com/docs/en/data-sheet/PCT2075.pdf Author: Frodo Looijaard <frodol@dds.nl> diff --git a/Documentation/hwmon/lm85.rst b/Documentation/hwmon/lm85.rst index faa92f54431c..55e1d9cdaaae 100644 --- a/Documentation/hwmon/lm85.rst +++ b/Documentation/hwmon/lm85.rst @@ -17,7 +17,7 @@ Supported chips: Addresses scanned: I2C 0x2c, 0x2d, 0x2e - Datasheet: http://www.ti.com/lit/ds/symlink/lm96000.pdf + Datasheet: https://www.ti.com/lit/ds/symlink/lm96000.pdf * Analog Devices ADM1027 @@ -25,7 +25,7 @@ Supported chips: Addresses scanned: I2C 0x2c, 0x2d, 0x2e - Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADM1027 + Datasheet: https://www.onsemi.com/PowerSolutions/product.do?id=ADM1027 * Analog Devices ADT7463 @@ -33,7 +33,7 @@ Supported chips: Addresses scanned: I2C 0x2c, 0x2d, 0x2e - Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADT7463 + Datasheet: https://www.onsemi.com/PowerSolutions/product.do?id=ADT7463 * Analog Devices ADT7468 @@ -41,7 +41,7 @@ Supported chips: Addresses scanned: I2C 0x2c, 0x2d, 0x2e - Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADT7468 + Datasheet: https://www.onsemi.com/PowerSolutions/product.do?id=ADT7468 * SMSC EMC6D100, SMSC EMC6D101 diff --git a/Documentation/hwmon/lm87.rst b/Documentation/hwmon/lm87.rst index 72fcb577ef2a..b8fec5689648 100644 --- a/Documentation/hwmon/lm87.rst +++ b/Documentation/hwmon/lm87.rst @@ -17,7 +17,7 @@ Supported chips: Addresses scanned: I2C 0x2c - 0x2e - Datasheet: http://www.analog.com/en/prod/0,2877,ADM1024,00.html + Datasheet: https://www.analog.com/en/prod/0,2877,ADM1024,00.html Authors: diff --git a/Documentation/hwmon/lm90.rst b/Documentation/hwmon/lm90.rst index 78dfc01b47a2..3da8c6e06a36 100644 --- a/Documentation/hwmon/lm90.rst +++ b/Documentation/hwmon/lm90.rst @@ -51,7 +51,7 @@ Supported chips: Datasheet: Publicly available at the ON Semiconductor website - http://www.onsemi.com/PowerSolutions/product.do?id=ADM1032 + https://www.onsemi.com/PowerSolutions/product.do?id=ADM1032 * Analog Devices ADT7461 @@ -61,7 +61,7 @@ Supported chips: Datasheet: Publicly available at the ON Semiconductor website - http://www.onsemi.com/PowerSolutions/product.do?id=ADT7461 + https://www.onsemi.com/PowerSolutions/product.do?id=ADT7461 * Analog Devices ADT7461A @@ -71,7 +71,7 @@ Supported chips: Datasheet: Publicly available at the ON Semiconductor website - http://www.onsemi.com/PowerSolutions/product.do?id=ADT7461A + https://www.onsemi.com/PowerSolutions/product.do?id=ADT7461A * ON Semiconductor NCT1008 @@ -81,7 +81,7 @@ Supported chips: Datasheet: Publicly available at the ON Semiconductor website - http://www.onsemi.com/PowerSolutions/product.do?id=NCT1008 + https://www.onsemi.com/PowerSolutions/product.do?id=NCT1008 * Maxim MAX6646 @@ -263,7 +263,7 @@ Supported chips: Datasheet: Publicly available at TI website - http://www.ti.com/litv/pdf/sbos686 + https://www.ti.com/litv/pdf/sbos686 Author: Jean Delvare <jdelvare@suse.de> diff --git a/Documentation/hwmon/lm93.rst b/Documentation/hwmon/lm93.rst index 49d199b45b67..369e15898af9 100644 --- a/Documentation/hwmon/lm93.rst +++ b/Documentation/hwmon/lm93.rst @@ -133,7 +133,7 @@ Smart Tach Mode (from the datasheet):: four signals are measured within 4 seconds. Smart tach mode is enabled by the driver by writing 1 or 2 (associating the -the fan tachometer with a pwm) to the sysfs file fan<n>_smart_tach. A zero +fan tachometer with a pwm) to the sysfs file fan<n>_smart_tach. A zero will disable the function for that fan. Note that Smart tach mode cannot be enabled if the PWM output frequency is 22500 Hz (see below). diff --git a/Documentation/hwmon/lm95234.rst b/Documentation/hwmon/lm95234.rst index e4c14bea5efd..a44e8f529826 100644 --- a/Documentation/hwmon/lm95234.rst +++ b/Documentation/hwmon/lm95234.rst @@ -9,7 +9,7 @@ Supported chips: Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/product/lm95233 + https://www.ti.com/product/lm95233 * National Semiconductor / Texas Instruments LM95234 @@ -17,7 +17,7 @@ Supported chips: Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/product/lm95234 + https://www.ti.com/product/lm95234 Author: Guenter Roeck <linux@roeck-us.net> diff --git a/Documentation/hwmon/lm95245.rst b/Documentation/hwmon/lm95245.rst index 566d1dc8c5a6..836d9a3f53f9 100644 --- a/Documentation/hwmon/lm95245.rst +++ b/Documentation/hwmon/lm95245.rst @@ -9,7 +9,7 @@ Supported chips: Datasheet: Publicly available at the TI website - http://www.ti.com/lit/ds/symlink/lm95235.pdf + https://www.ti.com/lit/ds/symlink/lm95235.pdf * TI / National Semiconductor LM95245 @@ -17,7 +17,7 @@ Supported chips: Datasheet: Publicly available at the TI website - http://www.ti.com/lit/ds/symlink/lm95245.pdf + https://www.ti.com/lit/ds/symlink/lm95245.pdf Author: Alexander Stein <alexander.stein@systec-electronic.com> diff --git a/Documentation/hwmon/ltc2978.rst b/Documentation/hwmon/ltc2978.rst index bc5270e5a477..b99a63965cfb 100644 --- a/Documentation/hwmon/ltc2978.rst +++ b/Documentation/hwmon/ltc2978.rst @@ -179,7 +179,7 @@ Supported chips: Addresses scanned: - - Datasheet: http://www.analog.com/ltm4680 + Datasheet: https://www.analog.com/ltm4680 * Analog Devices LTM4686 @@ -187,7 +187,7 @@ Supported chips: Addresses scanned: - - Datasheet: http://www.analog.com/ltm4686 + Datasheet: https://www.analog.com/ltm4686 * Analog Devices LTM4700 @@ -195,7 +195,7 @@ Supported chips: Addresses scanned: - - Datasheet: http://www.analog.com/ltm4700 + Datasheet: https://www.analog.com/ltm4700 diff --git a/Documentation/hwmon/max20730.rst b/Documentation/hwmon/max20730.rst index cea7ae58c2f7..cb0c95b2b1f6 100644 --- a/Documentation/hwmon/max20730.rst +++ b/Documentation/hwmon/max20730.rst @@ -5,6 +5,14 @@ Kernel driver max20730 Supported chips: + * Maxim MAX20710 + + Prefix: 'max20710' + + Addresses scanned: - + + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX20710.pdf + * Maxim MAX20730 Prefix: 'max20730' @@ -35,7 +43,7 @@ Author: Guenter Roeck <linux@roeck-us.net> Description ----------- -This driver implements support for Maxim MAX20730, MAX20734, and MAX20743 +This driver implements support for Maxim MAX20710, MAX20730, MAX20734, and MAX20743 Integrated, Step-Down Switching Regulators with PMBus support. The driver is a client driver to the core PMBus driver. diff --git a/Documentation/hwmon/max20751.rst b/Documentation/hwmon/max20751.rst index fe701e07eaf5..f9febefce02d 100644 --- a/Documentation/hwmon/max20751.rst +++ b/Documentation/hwmon/max20751.rst @@ -9,9 +9,9 @@ Supported chips: Addresses scanned: - - Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX20751.pdf + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX20751.pdf - Application note: http://pdfserv.maximintegrated.com/en/an/AN5941.pdf + Application note: https://pdfserv.maximintegrated.com/en/an/AN5941.pdf Author: Guenter Roeck <linux@roeck-us.net> diff --git a/Documentation/hwmon/max31790.rst b/Documentation/hwmon/max31790.rst index 84c62a12ef3a..f301385d8cef 100644 --- a/Documentation/hwmon/max31790.rst +++ b/Documentation/hwmon/max31790.rst @@ -9,7 +9,7 @@ Supported chips: Addresses scanned: - - Datasheet: http://pdfserv.maximintegrated.com/en/ds/MAX31790.pdf + Datasheet: https://pdfserv.maximintegrated.com/en/ds/MAX31790.pdf Author: Il Han <corone.il.han@gmail.com> diff --git a/Documentation/hwmon/max34440.rst b/Documentation/hwmon/max34440.rst index 5744df100a5d..162d289f0814 100644 --- a/Documentation/hwmon/max34440.rst +++ b/Documentation/hwmon/max34440.rst @@ -9,7 +9,7 @@ Supported chips: Addresses scanned: - - Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX34440.pdf + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX34440.pdf * Maxim MAX34441 @@ -19,7 +19,7 @@ Supported chips: Addresses scanned: - - Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX34441.pdf + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX34441.pdf * Maxim MAX34446 @@ -29,7 +29,7 @@ Supported chips: Addresses scanned: - - Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX34446.pdf + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX34446.pdf * Maxim MAX34451 @@ -39,7 +39,7 @@ Supported chips: Addresses scanned: - - Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX34451.pdf + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX34451.pdf * Maxim MAX34460 @@ -49,7 +49,7 @@ Supported chips: Addresses scanned: - - Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX34460.pdf + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX34460.pdf * Maxim MAX34461 @@ -59,7 +59,7 @@ Supported chips: Addresses scanned: - - Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX34461.pdf + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX34461.pdf Author: Guenter Roeck <linux@roeck-us.net> diff --git a/Documentation/hwmon/nct6775.rst b/Documentation/hwmon/nct6775.rst index 1d0315c40952..5ba8276aad4b 100644 --- a/Documentation/hwmon/nct6775.rst +++ b/Documentation/hwmon/nct6775.rst @@ -276,5 +276,5 @@ temperature measurement device. As a result, the temperature reported on CPUTIN will not reflect a usable value. It often reports unreasonably high temperatures, and in some cases the reported temperature declines if the actual temperature increases (similar to the raw PECI temperature value - see PECI -specification for details). CPUTIN should therefore be be ignored on ASUS +specification for details). CPUTIN should therefore be ignored on ASUS boards. The CPU temperature on ASUS boards is reported from PECI 0. diff --git a/Documentation/hwmon/pmbus.rst b/Documentation/hwmon/pmbus.rst index 2658ddee70eb..66b3e894612f 100644 --- a/Documentation/hwmon/pmbus.rst +++ b/Documentation/hwmon/pmbus.rst @@ -21,11 +21,11 @@ Supported chips: Datasheets: - http://www.onsemi.com/pub_link/Collateral/ADP4000-D.PDF + https://www.onsemi.com/pub_link/Collateral/ADP4000-D.PDF - http://www.onsemi.com/pub_link/Collateral/NCP4200-D.PDF + https://www.onsemi.com/pub_link/Collateral/NCP4200-D.PDF - http://www.onsemi.com/pub_link/Collateral/JUNE%202009-%20REV.%200.PDF + https://www.onsemi.com/pub_link/Collateral/JUNE%202009-%20REV.%200.PDF * Lineage Power @@ -53,15 +53,15 @@ Supported chips: Datasheets: - http://www.ti.com/lit/gpn/tps40400 + https://www.ti.com/lit/gpn/tps40400 - http://www.ti.com/lit/gpn/tps544b20 + https://www.ti.com/lit/gpn/tps544b20 - http://www.ti.com/lit/gpn/tps544b25 + https://www.ti.com/lit/gpn/tps544b25 - http://www.ti.com/lit/gpn/tps544c20 + https://www.ti.com/lit/gpn/tps544c20 - http://www.ti.com/lit/gpn/tps544c25 + https://www.ti.com/lit/gpn/tps544c25 * Maxim MAX20796 diff --git a/Documentation/hwmon/sht21.rst b/Documentation/hwmon/sht21.rst index f1f5da030108..1bccc8e8aac8 100644 --- a/Documentation/hwmon/sht21.rst +++ b/Documentation/hwmon/sht21.rst @@ -11,7 +11,7 @@ Supported chips: Datasheet: Publicly available at the Sensirion website - http://www.sensirion.com/file/datasheet_sht21 + https://www.sensirion.com/file/datasheet_sht21 @@ -23,7 +23,7 @@ Supported chips: Datasheet: Publicly available at the Sensirion website - http://www.sensirion.com/file/datasheet_sht25 + https://www.sensirion.com/file/datasheet_sht25 diff --git a/Documentation/hwmon/shtc1.rst b/Documentation/hwmon/shtc1.rst index 08380f21ab6a..f38c4c9d2f74 100644 --- a/Documentation/hwmon/shtc1.rst +++ b/Documentation/hwmon/shtc1.rst @@ -9,7 +9,7 @@ Supported chips: Addresses scanned: none - Datasheet: http://www.sensirion.com/file/datasheet_shtc1 + Datasheet: https://www.sensirion.com/file/datasheet_shtc1 @@ -19,7 +19,7 @@ Supported chips: Addresses scanned: none - Datasheet: http://www.sensirion.com/file/datasheet_shtw1 + Datasheet: https://www.sensirion.com/file/datasheet_shtw1 @@ -29,7 +29,7 @@ Supported chips: Addresses scanned: none - Datasheet: http://www.sensirion.com/file/datasheet_shtc3 + Datasheet: https://www.sensirion.com/file/datasheet_shtc3 diff --git a/Documentation/hwmon/sparx5-temp.rst b/Documentation/hwmon/sparx5-temp.rst new file mode 100644 index 000000000000..014080908954 --- /dev/null +++ b/Documentation/hwmon/sparx5-temp.rst @@ -0,0 +1,33 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +Microchip SparX-5 SoC +===================== + +Supported chips: + + * VSC7546, VSC7549, VSC755, VSC7556, and VSC7558 (Sparx5 series) + + Prefix: 'sparx5-temp' + + Addresses scanned: - + + Datasheet: Provided by Microchip upon request and under NDA + +Author: Lars Povlsen <lars.povlsen@microchip.com> + +Description +----------- + +The Sparx5 SoC contains a temperature sensor based on the MR74060 +Moortec IP. + +The sensor has a range of -40°C to +125°C and an accuracy of +/-5°C. + +Sysfs entries +------------- + +The following attributes are supported. + +======================= ======================================================== +temp1_input Die temperature (in millidegree Celsius.) +======================= ======================================================== diff --git a/Documentation/hwmon/thmc50.rst b/Documentation/hwmon/thmc50.rst index cfff3885287d..090f040294a3 100644 --- a/Documentation/hwmon/thmc50.rst +++ b/Documentation/hwmon/thmc50.rst @@ -17,7 +17,7 @@ Supported chips: Addresses scanned: I2C 0x2c - 0x2e - Datasheet: http://www.ti.com/ + Datasheet: https://www.ti.com/ Author: Krzysztof Helt <krzysztof.h1@wp.pl> diff --git a/Documentation/hwmon/tmp103.rst b/Documentation/hwmon/tmp103.rst index 205de6148fcb..e195a7d14309 100644 --- a/Documentation/hwmon/tmp103.rst +++ b/Documentation/hwmon/tmp103.rst @@ -9,7 +9,7 @@ Supported chips: Addresses scanned: none - Product info and datasheet: http://www.ti.com/product/tmp103 + Product info and datasheet: https://www.ti.com/product/tmp103 Author: diff --git a/Documentation/hwmon/tmp108.rst b/Documentation/hwmon/tmp108.rst index 5f4266a16cb2..6df7cf1b42f4 100644 --- a/Documentation/hwmon/tmp108.rst +++ b/Documentation/hwmon/tmp108.rst @@ -9,7 +9,7 @@ Supported chips: Addresses scanned: none - Datasheet: http://www.ti.com/product/tmp108 + Datasheet: https://www.ti.com/product/tmp108 Author: diff --git a/Documentation/hwmon/tmp401.rst b/Documentation/hwmon/tmp401.rst index 6a05a0719bc7..14bf1fbf4493 100644 --- a/Documentation/hwmon/tmp401.rst +++ b/Documentation/hwmon/tmp401.rst @@ -47,7 +47,7 @@ Supported chips: Prefix: 'tmp461' - Datasheet: http://www.ti.com/product/tmp461 + Datasheet: https://www.ti.com/product/tmp461 diff --git a/Documentation/hwmon/tmp421.rst b/Documentation/hwmon/tmp421.rst index 1ba926a3605c..ddcd5159c75d 100644 --- a/Documentation/hwmon/tmp421.rst +++ b/Documentation/hwmon/tmp421.rst @@ -33,7 +33,7 @@ Supported chips: Addresses scanned: I2C 0x2a, 0x4c, 0x4d, 0x4e and 0x4f - Datasheet: http://www.ti.com/product/tmp441 + Datasheet: https://www.ti.com/product/tmp441 * Texas Instruments TMP442 @@ -41,7 +41,7 @@ Supported chips: Addresses scanned: I2C 0x4c and 0x4d - Datasheet: http://www.ti.com/product/tmp442 + Datasheet: https://www.ti.com/product/tmp442 Authors: diff --git a/Documentation/hwmon/tmp513.rst b/Documentation/hwmon/tmp513.rst index 6c8fae4b1a75..f2dfc1677ad9 100644 --- a/Documentation/hwmon/tmp513.rst +++ b/Documentation/hwmon/tmp513.rst @@ -9,13 +9,13 @@ Supported chips: Prefix: 'tmp512' - Datasheet: http://www.ti.com/lit/ds/symlink/tmp512.pdf + Datasheet: https://www.ti.com/lit/ds/symlink/tmp512.pdf * Texas Instruments TMP513 Prefix: 'tmp513' - Datasheet: http://www.ti.com/lit/ds/symlink/tmp513.pdf + Datasheet: https://www.ti.com/lit/ds/symlink/tmp513.pdf Authors: diff --git a/Documentation/hwmon/tps40422.rst b/Documentation/hwmon/tps40422.rst index 8fe3e1c3572e..32a62ccea192 100644 --- a/Documentation/hwmon/tps40422.rst +++ b/Documentation/hwmon/tps40422.rst @@ -9,7 +9,7 @@ Supported chips: Addresses scanned: - - Datasheet: http://www.ti.com/lit/gpn/tps40422 + Datasheet: https://www.ti.com/lit/gpn/tps40422 Author: Zhu Laiwen <richard.zhu@nsn.com> diff --git a/Documentation/hwmon/tps53679.rst b/Documentation/hwmon/tps53679.rst index be94cab78967..c7c589e49789 100644 --- a/Documentation/hwmon/tps53679.rst +++ b/Documentation/hwmon/tps53679.rst @@ -9,7 +9,7 @@ Supported chips: Addresses scanned: - - Datasheet: http://www.ti.com/lit/gpn/tps53647 + Datasheet: https://www.ti.com/lit/gpn/tps53647 * Texas Instruments TPS53667 @@ -17,7 +17,7 @@ Supported chips: Addresses scanned: - - Datasheet: http://www.ti.com/lit/gpn/TPS53667 + Datasheet: https://www.ti.com/lit/gpn/TPS53667 * Texas Instruments TPS53679 @@ -25,7 +25,7 @@ Supported chips: Addresses scanned: - - Datasheet: http://www.ti.com/lit/gpn/TPS53679 (short version) + Datasheet: https://www.ti.com/lit/gpn/TPS53679 (short version) * Texas Instruments TPS53681 @@ -33,7 +33,7 @@ Supported chips: Addresses scanned: - - Datasheet: http://www.ti.com/lit/gpn/TPS53681 + Datasheet: https://www.ti.com/lit/gpn/TPS53681 * Texas Instruments TPS53688 diff --git a/Documentation/hwmon/w83627ehf.rst b/Documentation/hwmon/w83627ehf.rst index 74d19ef11e1f..7bb557c94858 100644 --- a/Documentation/hwmon/w83627ehf.rst +++ b/Documentation/hwmon/w83627ehf.rst @@ -96,7 +96,7 @@ sensors. The configured source for each of the temperature sensors is provided in tempX_label. Temperatures are measured in degrees Celsius and measurement resolution is 1 -degC for temp1 and and 0.5 degC for temp2 and temp3. For temp4 and higher, +degC for temp1 and 0.5 degC for temp2 and temp3. For temp4 and higher, resolution is 1 degC for W83667HG-B and 0.0 degC for NCT6775F and NCT6776F. An alarm is triggered when the temperature gets higher than high limit; it stays on until the temperature falls below the hysteresis value. diff --git a/Documentation/hwmon/w83781d.rst b/Documentation/hwmon/w83781d.rst index f36d33dfb704..c2dcb6856012 100644 --- a/Documentation/hwmon/w83781d.rst +++ b/Documentation/hwmon/w83781d.rst @@ -17,7 +17,7 @@ Supported chips: Addresses scanned: I2C 0x28 - 0x2f, ISA 0x290 (8 I/O ports) - Datasheet: http://www.winbond.com + Datasheet: https://www.winbond.com * Winbond W83783S diff --git a/Documentation/hwmon/w83l786ng.rst b/Documentation/hwmon/w83l786ng.rst index 2b7776190de3..06234dea42a2 100644 --- a/Documentation/hwmon/w83l786ng.rst +++ b/Documentation/hwmon/w83l786ng.rst @@ -36,7 +36,7 @@ Temperatures are measured in degrees Celsius and measurement resolution is 1 degC for temp1 and temp2. Fan rotation speeds are reported in RPM (rotations per minute). Fan readings -readings can be divided by a programmable divider (1, 2, 4, 8, 16, 32, 64 +can be divided by a programmable divider (1, 2, 4, 8, 16, 32, 64 or 128 for fan 1/2) to give the readings more range or accuracy. Voltage sensors (also known as IN sensors) report their values in millivolts. diff --git a/Documentation/i2c/slave-eeprom-backend.rst b/Documentation/i2c/slave-eeprom-backend.rst index 0b8cd83698e0..38d951f10302 100644 --- a/Documentation/i2c/slave-eeprom-backend.rst +++ b/Documentation/i2c/slave-eeprom-backend.rst @@ -1,14 +1,26 @@ ============================== -Linux I2C slave eeprom backend +Linux I2C slave EEPROM backend ============================== -by Wolfram Sang <wsa@sang-engineering.com> in 2014-15 +by Wolfram Sang <wsa@sang-engineering.com> in 2014-20 -This is a proof-of-concept backend which acts like an EEPROM on the connected -I2C bus. The memory contents can be modified from userspace via this file -located in sysfs:: +This backend simulates an EEPROM on the connected I2C bus. Its memory contents +can be accessed from userspace via this file located in sysfs:: /sys/bus/i2c/devices/<device-directory>/slave-eeprom +The following types are available: 24c02, 24c32, 24c64, and 24c512. Read-only +variants are also supported. The name needed for instantiating has the form +'slave-<type>[ro]'. Examples follow: + +24c02, read/write, address 0x64: + # echo slave-24c02 0x1064 > /sys/bus/i2c/devices/i2c-1/new_device + +24c512, read-only, address 0x42: + # echo slave-24c512ro 0x1042 > /sys/bus/i2c/devices/i2c-1/new_device + +You can also preload data during boot if a device-property named +'firmware-name' contains a valid filename (DT or ACPI only). + As of 2015, Linux doesn't support poll on binary sysfs files, so there is no notification when another master changed the content. diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst index c2e29633071e..64689d19dd51 100644 --- a/Documentation/i2c/smbus-protocol.rst +++ b/Documentation/i2c/smbus-protocol.rst @@ -57,7 +57,7 @@ SMBus Quick Command This sends a single bit to the device, at the place of the Rd/Wr bit:: - A Addr Rd/Wr [A] P + S Addr Rd/Wr [A] P Functionality flag: I2C_FUNC_SMBUS_QUICK diff --git a/Documentation/i2c/upgrading-clients.rst b/Documentation/i2c/upgrading-clients.rst index 27d29032c138..1708090d7b8f 100644 --- a/Documentation/i2c/upgrading-clients.rst +++ b/Documentation/i2c/upgrading-clients.rst @@ -8,7 +8,7 @@ Introduction ------------ This guide outlines how to alter existing Linux 2.6 client drivers from -the old to the new new binding methods. +the old to the new binding methods. Example old-style driver diff --git a/Documentation/ia64/efirtc.rst b/Documentation/ia64/efirtc.rst index 2f7ff5026308..fd8328408301 100644 --- a/Documentation/ia64/efirtc.rst +++ b/Documentation/ia64/efirtc.rst @@ -113,7 +113,7 @@ We have added 2 new ioctl()s that are specific to the EFI driver: Read the current state of the alarm:: - ioctl(d, RTC_WKLAM_RD, &wkt) + ioctl(d, RTC_WKALM_RD, &wkt) Set the alarm or change its status:: diff --git a/Documentation/index.rst b/Documentation/index.rst index 71eca3171574..57719744774c 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -182,6 +182,20 @@ subprojects. filesystems/ext4/index +Other documentation +------------------- + +There are several unsorted documents that don't seem to fit on other parts +of the documentation body, or may require some adjustments and/or conversion +to ReStructured Text format, or are simply too old. + +.. toctree:: + :maxdepth: 2 + + staging/index + watch_queue + + Translations ------------ diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst index a1601ec3317b..39881b719782 100644 --- a/Documentation/kbuild/kconfig-language.rst +++ b/Documentation/kbuild/kconfig-language.rst @@ -681,7 +681,7 @@ translate Kconfig logic into boolean formulas and run a SAT solver on this to find dead code / features (always inactive), 114 dead features were found in Linux using this methodology [1]_ (Section 8: Threats to validity). -Confirming this could prove useful as Kconfig stands as one of the the leading +Confirming this could prove useful as Kconfig stands as one of the leading industrial variability modeling languages [1]_ [2]_. Its study would help evaluate practical uses of such languages, their use was only theoretical and real world requirements were not well understood. As it stands though diff --git a/Documentation/kbuild/modules.rst b/Documentation/kbuild/modules.rst index a45cccff467d..85ccc878895e 100644 --- a/Documentation/kbuild/modules.rst +++ b/Documentation/kbuild/modules.rst @@ -182,7 +182,8 @@ module 8123.ko, which is built from the following files:: 8123_pci.c 8123_bin.o_shipped <= Binary blob ---- 3.1 Shared Makefile +3.1 Shared Makefile +------------------- An external module always includes a wrapper makefile that supports building the module using "make" with no arguments. @@ -470,9 +471,9 @@ build. The syntax of the Module.symvers file is:: - <CRC> <Symbol> <Module> <Export Type> <Namespace> + <CRC> <Symbol> <Module> <Export Type> <Namespace> - 0xe1cc2a05 usb_stor_suspend drivers/usb/storage/usb-storage EXPORT_SYMBOL_GPL USB_STORAGE + 0xe1cc2a05 usb_stor_suspend drivers/usb/storage/usb-storage EXPORT_SYMBOL_GPL USB_STORAGE The fields are separated by tabs and values may be empty (e.g. if no namespace is defined for an exported symbol). diff --git a/Documentation/kbuild/reproducible-builds.rst b/Documentation/kbuild/reproducible-builds.rst index 503393854e2e..3b25655e441b 100644 --- a/Documentation/kbuild/reproducible-builds.rst +++ b/Documentation/kbuild/reproducible-builds.rst @@ -101,7 +101,7 @@ Structure randomisation If you enable ``CONFIG_GCC_PLUGIN_RANDSTRUCT``, you will need to pre-generate the random seed in -``scripts/gcc-plgins/randomize_layout_seed.h`` so the same value +``scripts/gcc-plugins/randomize_layout_seed.h`` so the same value is used in rebuilds. Debug info conflicts diff --git a/Documentation/leds/index.rst b/Documentation/leds/index.rst index 060f4e485897..bc70c6aa7138 100644 --- a/Documentation/leds/index.rst +++ b/Documentation/leds/index.rst @@ -9,6 +9,7 @@ LEDs leds-class leds-class-flash + leds-class-multicolor ledtrig-oneshot ledtrig-transient ledtrig-usbport diff --git a/Documentation/leds/leds-class-multicolor.rst b/Documentation/leds/leds-class-multicolor.rst new file mode 100644 index 000000000000..c57b98bfd387 --- /dev/null +++ b/Documentation/leds/leds-class-multicolor.rst @@ -0,0 +1,86 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================================== +Multicolor LED handling under Linux +==================================== + +Description +=========== +The multicolor class groups monochrome LEDs and allows controlling two +aspects of the final combined color: hue and lightness. The former is +controlled via the multi_intensity array file and the latter is controlled +via brightness file. + +Multicolor Class Control +======================== +The multicolor class presents files that groups the colors as indexes in an +array. These files are children under the LED parent node created by the +led_class framework. The led_class framework is documented in led-class.rst +within this documentation directory. + +Each colored LED will be indexed under the multi_* files. The order of the +colors will be arbitrary. The multi_index file can be read to determine the +color name to indexed value. + +The multi_index file is an array that contains the string list of the colors as +they are defined in each multi_* array file. + +The multi_intensity is an array that can be read or written to for the +individual color intensities. All elements within this array must be written in +order for the color LED intensities to be updated. + +Directory Layout Example +======================== +root:/sys/class/leds/multicolor:status# ls -lR +-rw-r--r-- 1 root root 4096 Oct 19 16:16 brightness +-r--r--r-- 1 root root 4096 Oct 19 16:16 max_brightness +-r--r--r-- 1 root root 4096 Oct 19 16:16 multi_index +-rw-r--r-- 1 root root 4096 Oct 19 16:16 multi_intensity + +Multicolor Class Brightness Control +=================================== +The brightness level for each LED is calculated based on the color LED +intensity setting divided by the global max_brightness setting multiplied by +the requested brightness. + +led_brightness = brightness * multi_intensity/max_brightness + +Example: +A user first writes the multi_intensity file with the brightness levels +for each LED that are necessary to achieve a certain color output from a +multicolor LED group. + +cat /sys/class/leds/multicolor:status/multi_index +green blue red + +echo 43 226 138 > /sys/class/leds/multicolor:status/multi_intensity + +red - + intensity = 138 + max_brightness = 255 +green - + intensity = 43 + max_brightness = 255 +blue - + intensity = 226 + max_brightness = 255 + +The user can control the brightness of that multicolor LED group by writing the +global 'brightness' control. Assuming a max_brightness of 255 the user +may want to dim the LED color group to half. The user would write a value of +128 to the global brightness file then the values written to each LED will be +adjusted base on this value. + +cat /sys/class/leds/multicolor:status/max_brightness +255 +echo 128 > /sys/class/leds/multicolor:status/brightness + +adjusted_red_value = 128 * 138/255 = 69 +adjusted_green_value = 128 * 43/255 = 21 +adjusted_blue_value = 128 * 226/255 = 113 + +Reading the global brightness file will return the current brightness value of +the color LED group. + +cat /sys/class/leds/multicolor:status/brightness +128 diff --git a/Documentation/leds/ledtrig-transient.rst b/Documentation/leds/ledtrig-transient.rst index d921dc830cd0..eedfa1626e8a 100644 --- a/Documentation/leds/ledtrig-transient.rst +++ b/Documentation/leds/ledtrig-transient.rst @@ -157,7 +157,7 @@ repeat the following step as needed:: echo 1 > activate - start timer = duration to run once echo none > trigger -This trigger is intended to be used for for the following example use cases: +This trigger is intended to be used for the following example use cases: - Control of vibrate (phones, tablets etc.) hardware by user space app. - Use of LED by user space app as activity indicator. diff --git a/Documentation/litmus-tests/README b/Documentation/litmus-tests/README new file mode 100644 index 000000000000..7f5c6c3ed6c3 --- /dev/null +++ b/Documentation/litmus-tests/README @@ -0,0 +1,35 @@ +============ +LITMUS TESTS +============ + +Each subdirectory contains litmus tests that are typical to describe the +semantics of respective kernel APIs. +For more information about how to "run" a litmus test or how to generate +a kernel test module based on a litmus test, please see +tools/memory-model/README. + + +atomic (/atomic derectory) +-------------------------- + +Atomic-RMW+mb__after_atomic-is-stronger-than-acquire.litmus + Test that an atomic RMW followed by a smp_mb__after_atomic() is + stronger than a normal acquire: both the read and write parts of + the RMW are ordered before the subsequential memory accesses. + +Atomic-RMW-ops-are-atomic-WRT-atomic_set.litmus + Test that atomic_set() cannot break the atomicity of atomic RMWs. + NOTE: Require herd7 7.56 or later which supports "(void)expr". + + +RCU (/rcu directory) +-------------------- + +MP+onceassign+derefonce.litmus (under tools/memory-model/litmus-tests/) + Demonstrates the use of rcu_assign_pointer() and rcu_dereference() to + ensure that an RCU reader will not see pre-initialization garbage. + +RCU+sync+read.litmus +RCU+sync+free.litmus + Both the above litmus tests demonstrate the RCU grace period guarantee + that an RCU read-side critical section can never span a grace period. diff --git a/Documentation/litmus-tests/atomic/Atomic-RMW+mb__after_atomic-is-stronger-than-acquire.litmus b/Documentation/litmus-tests/atomic/Atomic-RMW+mb__after_atomic-is-stronger-than-acquire.litmus new file mode 100644 index 000000000000..9a8e31a44b28 --- /dev/null +++ b/Documentation/litmus-tests/atomic/Atomic-RMW+mb__after_atomic-is-stronger-than-acquire.litmus @@ -0,0 +1,32 @@ +C Atomic-RMW+mb__after_atomic-is-stronger-than-acquire + +(* + * Result: Never + * + * Test that an atomic RMW followed by a smp_mb__after_atomic() is + * stronger than a normal acquire: both the read and write parts of + * the RMW are ordered before the subsequential memory accesses. + *) + +{ +} + +P0(int *x, atomic_t *y) +{ + int r0; + int r1; + + r0 = READ_ONCE(*x); + smp_rmb(); + r1 = atomic_read(y); +} + +P1(int *x, atomic_t *y) +{ + atomic_inc(y); + smp_mb__after_atomic(); + WRITE_ONCE(*x, 1); +} + +exists +(0:r0=1 /\ 0:r1=0) diff --git a/Documentation/litmus-tests/atomic/Atomic-RMW-ops-are-atomic-WRT-atomic_set.litmus b/Documentation/litmus-tests/atomic/Atomic-RMW-ops-are-atomic-WRT-atomic_set.litmus new file mode 100644 index 000000000000..ffd4d3e79c4a --- /dev/null +++ b/Documentation/litmus-tests/atomic/Atomic-RMW-ops-are-atomic-WRT-atomic_set.litmus @@ -0,0 +1,25 @@ +C Atomic-RMW-ops-are-atomic-WRT-atomic_set + +(* + * Result: Never + * + * Test that atomic_set() cannot break the atomicity of atomic RMWs. + * NOTE: This requires herd7 7.56 or later which supports "(void)expr". + *) + +{ + atomic_t v = ATOMIC_INIT(1); +} + +P0(atomic_t *v) +{ + (void)atomic_add_unless(v, 1, 0); +} + +P1(atomic_t *v) +{ + atomic_set(v, 0); +} + +exists +(v=2) diff --git a/Documentation/litmus-tests/rcu/RCU+sync+free.litmus b/Documentation/litmus-tests/rcu/RCU+sync+free.litmus new file mode 100644 index 000000000000..4ee67e12f513 --- /dev/null +++ b/Documentation/litmus-tests/rcu/RCU+sync+free.litmus @@ -0,0 +1,42 @@ +C RCU+sync+free + +(* + * Result: Never + * + * This litmus test demonstrates that an RCU reader can never see a write that + * follows a grace period, if it did not see writes that precede that grace + * period. + * + * This is a typical pattern of RCU usage, where the write before the grace + * period assigns a pointer, and the writes following the grace period destroy + * the object that the pointer used to point to. + * + * This is one implication of the RCU grace-period guarantee, which says (among + * other things) that an RCU read-side critical section cannot span a grace period. + *) + +{ +int x = 1; +int *y = &x; +int z = 1; +} + +P0(int *x, int *z, int **y) +{ + int *r0; + int r1; + + rcu_read_lock(); + r0 = rcu_dereference(*y); + r1 = READ_ONCE(*r0); + rcu_read_unlock(); +} + +P1(int *x, int *z, int **y) +{ + rcu_assign_pointer(*y, z); + synchronize_rcu(); + WRITE_ONCE(*x, 0); +} + +exists (0:r0=x /\ 0:r1=0) diff --git a/Documentation/litmus-tests/rcu/RCU+sync+read.litmus b/Documentation/litmus-tests/rcu/RCU+sync+read.litmus new file mode 100644 index 000000000000..f34176720231 --- /dev/null +++ b/Documentation/litmus-tests/rcu/RCU+sync+read.litmus @@ -0,0 +1,37 @@ +C RCU+sync+read + +(* + * Result: Never + * + * This litmus test demonstrates that after a grace period, an RCU updater always + * sees all stores done in prior RCU read-side critical sections. Such + * read-side critical sections would have ended before the grace period ended. + * + * This is one implication of the RCU grace-period guarantee, which says (among + * other things) that an RCU read-side critical section cannot span a grace period. + *) + +{ +int x = 0; +int y = 0; +} + +P0(int *x, int *y) +{ + rcu_read_lock(); + WRITE_ONCE(*x, 1); + WRITE_ONCE(*y, 1); + rcu_read_unlock(); +} + +P1(int *x, int *y) +{ + int r0; + int r1; + + r0 = READ_ONCE(*x); + synchronize_rcu(); + r1 = READ_ONCE(*y); +} + +exists (1:r0=1 /\ 1:r1=0) diff --git a/Documentation/locking/index.rst b/Documentation/locking/index.rst index d785878cad65..7003bd5aeff4 100644 --- a/Documentation/locking/index.rst +++ b/Documentation/locking/index.rst @@ -14,6 +14,7 @@ locking mutex-design rt-mutex-design rt-mutex + seqlock spinlocks ww-mutex-design preempt-locking diff --git a/Documentation/locking/locktorture.rst b/Documentation/locking/locktorture.rst index 8012a74555e7..dfaf9fc883f4 100644 --- a/Documentation/locking/locktorture.rst +++ b/Documentation/locking/locktorture.rst @@ -166,4 +166,4 @@ checked for such errors. The "rmmod" command forces a "SUCCESS", two are self-explanatory, while the last indicates that while there were no locking failures, CPU-hotplug problems were detected. -Also see: Documentation/RCU/torture.txt +Also see: Documentation/RCU/torture.rst diff --git a/Documentation/locking/mutex-design.rst b/Documentation/locking/mutex-design.rst index 4d8236b81fa5..78540cd7f54b 100644 --- a/Documentation/locking/mutex-design.rst +++ b/Documentation/locking/mutex-design.rst @@ -18,7 +18,7 @@ as an alternative to these. This new data structure provided a number of advantages, including simpler interfaces, and at that time smaller code (see Disadvantages). -[1] http://lwn.net/Articles/164802/ +[1] https://lwn.net/Articles/164802/ Implementation -------------- @@ -28,7 +28,7 @@ and implemented in kernel/locking/mutex.c. These locks use an atomic variable (->owner) to keep track of the lock state during its lifetime. Field owner actually contains `struct task_struct *` to the current lock owner and it is therefore NULL if not currently owned. Since task_struct pointers are aligned -at at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g., +to at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g., if waiter list is non-empty). In its most basic form it also includes a wait-queue and a spinlock that serializes access to it. Furthermore, CONFIG_MUTEX_SPIN_ON_OWNER=y systems use a spinner MCS lock (->osq), described diff --git a/Documentation/locking/seqlock.rst b/Documentation/locking/seqlock.rst new file mode 100644 index 000000000000..366dd368d90a --- /dev/null +++ b/Documentation/locking/seqlock.rst @@ -0,0 +1,170 @@ +====================================== +Sequence counters and sequential locks +====================================== + +Introduction +============ + +Sequence counters are a reader-writer consistency mechanism with +lockless readers (read-only retry loops), and no writer starvation. They +are used for data that's rarely written to (e.g. system time), where the +reader wants a consistent set of information and is willing to retry if +that information changes. + +A data set is consistent when the sequence count at the beginning of the +read side critical section is even and the same sequence count value is +read again at the end of the critical section. The data in the set must +be copied out inside the read side critical section. If the sequence +count has changed between the start and the end of the critical section, +the reader must retry. + +Writers increment the sequence count at the start and the end of their +critical section. After starting the critical section the sequence count +is odd and indicates to the readers that an update is in progress. At +the end of the write side critical section the sequence count becomes +even again which lets readers make progress. + +A sequence counter write side critical section must never be preempted +or interrupted by read side sections. Otherwise the reader will spin for +the entire scheduler tick due to the odd sequence count value and the +interrupted writer. If that reader belongs to a real-time scheduling +class, it can spin forever and the kernel will livelock. + +This mechanism cannot be used if the protected data contains pointers, +as the writer can invalidate a pointer that the reader is following. + + +.. _seqcount_t: + +Sequence counters (``seqcount_t``) +================================== + +This is the the raw counting mechanism, which does not protect against +multiple writers. Write side critical sections must thus be serialized +by an external lock. + +If the write serialization primitive is not implicitly disabling +preemption, preemption must be explicitly disabled before entering the +write side section. If the read section can be invoked from hardirq or +softirq contexts, interrupts or bottom halves must also be respectively +disabled before entering the write section. + +If it's desired to automatically handle the sequence counter +requirements of writer serialization and non-preemptibility, use +:ref:`seqlock_t` instead. + +Initialization:: + + /* dynamic */ + seqcount_t foo_seqcount; + seqcount_init(&foo_seqcount); + + /* static */ + static seqcount_t foo_seqcount = SEQCNT_ZERO(foo_seqcount); + + /* C99 struct init */ + struct { + .seq = SEQCNT_ZERO(foo.seq), + } foo; + +Write path:: + + /* Serialized context with disabled preemption */ + + write_seqcount_begin(&foo_seqcount); + + /* ... [[write-side critical section]] ... */ + + write_seqcount_end(&foo_seqcount); + +Read path:: + + do { + seq = read_seqcount_begin(&foo_seqcount); + + /* ... [[read-side critical section]] ... */ + + } while (read_seqcount_retry(&foo_seqcount, seq)); + + +.. _seqlock_t: + +Sequential locks (``seqlock_t``) +================================ + +This contains the :ref:`seqcount_t` mechanism earlier discussed, plus an +embedded spinlock for writer serialization and non-preemptibility. + +If the read side section can be invoked from hardirq or softirq context, +use the write side function variants which disable interrupts or bottom +halves respectively. + +Initialization:: + + /* dynamic */ + seqlock_t foo_seqlock; + seqlock_init(&foo_seqlock); + + /* static */ + static DEFINE_SEQLOCK(foo_seqlock); + + /* C99 struct init */ + struct { + .seql = __SEQLOCK_UNLOCKED(foo.seql) + } foo; + +Write path:: + + write_seqlock(&foo_seqlock); + + /* ... [[write-side critical section]] ... */ + + write_sequnlock(&foo_seqlock); + +Read path, three categories: + +1. Normal Sequence readers which never block a writer but they must + retry if a writer is in progress by detecting change in the sequence + number. Writers do not wait for a sequence reader:: + + do { + seq = read_seqbegin(&foo_seqlock); + + /* ... [[read-side critical section]] ... */ + + } while (read_seqretry(&foo_seqlock, seq)); + +2. Locking readers which will wait if a writer or another locking reader + is in progress. A locking reader in progress will also block a writer + from entering its critical section. This read lock is + exclusive. Unlike rwlock_t, only one locking reader can acquire it:: + + read_seqlock_excl(&foo_seqlock); + + /* ... [[read-side critical section]] ... */ + + read_sequnlock_excl(&foo_seqlock); + +3. Conditional lockless reader (as in 1), or locking reader (as in 2), + according to a passed marker. This is used to avoid lockless readers + starvation (too much retry loops) in case of a sharp spike in write + activity. First, a lockless read is tried (even marker passed). If + that trial fails (odd sequence counter is returned, which is used as + the next iteration marker), the lockless read is transformed to a + full locking read and no retry loop is necessary:: + + /* marker; even initialization */ + int seq = 0; + do { + read_seqbegin_or_lock(&foo_seqlock, &seq); + + /* ... [[read-side critical section]] ... */ + + } while (need_seqretry(&foo_seqlock, seq)); + done_seqretry(&foo_seqlock, seq); + + +API documentation +================= + +.. kernel-doc:: include/linux/seqlock.h diff --git a/Documentation/locking/ww-mutex-design.rst b/Documentation/locking/ww-mutex-design.rst index 1846c199da23..54d9c17bb66b 100644 --- a/Documentation/locking/ww-mutex-design.rst +++ b/Documentation/locking/ww-mutex-design.rst @@ -49,7 +49,7 @@ However, the Wound-Wait algorithm is typically stated to generate fewer backoffs compared to Wait-Die, but is, on the other hand, associated with more work than Wait-Die when recovering from a backoff. Wound-Wait is also a preemptive algorithm in that transactions are wounded by other transactions, and that -requires a reliable way to pick up up the wounded condition and preempt the +requires a reliable way to pick up the wounded condition and preempt the running transaction. Note that this is not the same as process preemption. A Wound-Wait transaction is considered preempted when it dies (returning -EDEADLK) following a wound. diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst index 77e43c8b24b4..227f427118e8 100644 --- a/Documentation/maintainer/maintainer-entry-profile.rst +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -31,7 +31,7 @@ Example questions to consider: - What branch should contributors submit against? - Links to any other Maintainer Entry Profiles? For example a device-driver may point to an entry for its parent subsystem. This makes - the contributor aware of obligations a maintainer may have have for + the contributor aware of obligations a maintainer may have for other maintainers in the submission chain. diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index eaabc3134294..96186332e5f4 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -553,12 +553,12 @@ There are certain things that the Linux kernel memory barriers do not guarantee: DATA DEPENDENCY BARRIERS (HISTORICAL) ------------------------------------- -As of v4.15 of the Linux kernel, an smp_read_barrier_depends() was -added to READ_ONCE(), which means that about the only people who -need to pay attention to this section are those working on DEC Alpha -architecture-specific code and those working on READ_ONCE() itself. -For those who need it, and for those who are interested in the history, -here is the story of data-dependency barriers. +As of v4.15 of the Linux kernel, an smp_mb() was added to READ_ONCE() for +DEC Alpha, which means that about the only people who need to pay attention +to this section are those working on DEC Alpha architecture-specific code +and those working on READ_ONCE() itself. For those who need it, and for +those who are interested in the history, here is the story of +data-dependency barriers. The usage requirements of data dependency barriers are a little subtle, and it's not always obvious that they're needed. To illustrate, consider the @@ -1935,6 +1935,20 @@ There are some more advanced barrier functions: relaxed I/O accessors and the Documentation/DMA-API.txt file for more information on consistent memory. + (*) pmem_wmb(); + + This is for use with persistent memory to ensure that stores for which + modifications are written to persistent storage reached a platform + durability domain. + + For example, after a non-temporal write to pmem region, we use pmem_wmb() + to ensure that stores have reached a platform durability domain. This ensures + that stores have updated persistent storage before any data access or + data transfer caused by subsequent instructions is initiated. This is + in addition to the ordering done by wmb(). + + For load from persistent memory, existing read memory barriers are sufficient + to ensure read ordering. =============================== IMPLICIT KERNEL MEMORY BARRIERS @@ -2708,144 +2722,6 @@ the properties of the memory window through which devices are accessed and/or the use of any special device communication instructions the CPU may have. -CACHE COHERENCY ---------------- - -Life isn't quite as simple as it may appear above, however: for while the -caches are expected to be coherent, there's no guarantee that that coherency -will be ordered. This means that while changes made on one CPU will -eventually become visible on all CPUs, there's no guarantee that they will -become apparent in the same order on those other CPUs. - - -Consider dealing with a system that has a pair of CPUs (1 & 2), each of which -has a pair of parallel data caches (CPU 1 has A/B, and CPU 2 has C/D): - - : - : +--------+ - : +---------+ | | - +--------+ : +--->| Cache A |<------->| | - | | : | +---------+ | | - | CPU 1 |<---+ | | - | | : | +---------+ | | - +--------+ : +--->| Cache B |<------->| | - : +---------+ | | - : | Memory | - : +---------+ | System | - +--------+ : +--->| Cache C |<------->| | - | | : | +---------+ | | - | CPU 2 |<---+ | | - | | : | +---------+ | | - +--------+ : +--->| Cache D |<------->| | - : +---------+ | | - : +--------+ - : - -Imagine the system has the following properties: - - (*) an odd-numbered cache line may be in cache A, cache C or it may still be - resident in memory; - - (*) an even-numbered cache line may be in cache B, cache D or it may still be - resident in memory; - - (*) while the CPU core is interrogating one cache, the other cache may be - making use of the bus to access the rest of the system - perhaps to - displace a dirty cacheline or to do a speculative load; - - (*) each cache has a queue of operations that need to be applied to that cache - to maintain coherency with the rest of the system; - - (*) the coherency queue is not flushed by normal loads to lines already - present in the cache, even though the contents of the queue may - potentially affect those loads. - -Imagine, then, that two writes are made on the first CPU, with a write barrier -between them to guarantee that they will appear to reach that CPU's caches in -the requisite order: - - CPU 1 CPU 2 COMMENT - =============== =============== ======================================= - u == 0, v == 1 and p == &u, q == &u - v = 2; - smp_wmb(); Make sure change to v is visible before - change to p - <A:modify v=2> v is now in cache A exclusively - p = &v; - <B:modify p=&v> p is now in cache B exclusively - -The write memory barrier forces the other CPUs in the system to perceive that -the local CPU's caches have apparently been updated in the correct order. But -now imagine that the second CPU wants to read those values: - - CPU 1 CPU 2 COMMENT - =============== =============== ======================================= - ... - q = p; - x = *q; - -The above pair of reads may then fail to happen in the expected order, as the -cacheline holding p may get updated in one of the second CPU's caches while -the update to the cacheline holding v is delayed in the other of the second -CPU's caches by some other cache event: - - CPU 1 CPU 2 COMMENT - =============== =============== ======================================= - u == 0, v == 1 and p == &u, q == &u - v = 2; - smp_wmb(); - <A:modify v=2> <C:busy> - <C:queue v=2> - p = &v; q = p; - <D:request p> - <B:modify p=&v> <D:commit p=&v> - <D:read p> - x = *q; - <C:read *q> Reads from v before v updated in cache - <C:unbusy> - <C:commit v=2> - -Basically, while both cachelines will be updated on CPU 2 eventually, there's -no guarantee that, without intervention, the order of update will be the same -as that committed on CPU 1. - - -To intervene, we need to interpolate a data dependency barrier or a read -barrier between the loads (which as of v4.15 is supplied unconditionally -by the READ_ONCE() macro). This will force the cache to commit its -coherency queue before processing any further requests: - - CPU 1 CPU 2 COMMENT - =============== =============== ======================================= - u == 0, v == 1 and p == &u, q == &u - v = 2; - smp_wmb(); - <A:modify v=2> <C:busy> - <C:queue v=2> - p = &v; q = p; - <D:request p> - <B:modify p=&v> <D:commit p=&v> - <D:read p> - smp_read_barrier_depends() - <C:unbusy> - <C:commit v=2> - x = *q; - <C:read *q> Reads from v after v updated in cache - - -This sort of problem can be encountered on DEC Alpha processors as they have a -split cache that improves performance by making better use of the data bus. -While most CPUs do imply a data dependency barrier on the read when a memory -access depends on a read, not all do, so it may not be relied on. - -Other CPUs may also have split caches, but must coordinate between the various -cachelets for normal memory accesses. The semantics of the Alpha removes the -need for hardware coordination in the absence of memory barriers, which -permitted Alpha to sport higher CPU clock rates back in the day. However, -please note that (again, as of v4.15) smp_read_barrier_depends() should not -be used except in Alpha arch-specific code and within the READ_ONCE() macro. - - CACHE COHERENCY VS DMA ---------------------- @@ -3009,10 +2885,8 @@ caches with the memory coherence system, thus making it seem like pointer changes vs new data occur in the right order. The Alpha defines the Linux kernel's memory model, although as of v4.15 -the Linux kernel's addition of smp_read_barrier_depends() to READ_ONCE() -greatly reduced Alpha's impact on the memory model. - -See the subsection on "Cache Coherency" above. +the Linux kernel's addition of smp_mb() to READ_ONCE() on Alpha greatly +reduced its impact on the memory model. VIRTUAL MACHINE GUESTS diff --git a/Documentation/mips/ingenic-tcu.rst b/Documentation/mips/ingenic-tcu.rst index c5a646b14450..2ce4cb1314dc 100644 --- a/Documentation/mips/ingenic-tcu.rst +++ b/Documentation/mips/ingenic-tcu.rst @@ -5,7 +5,7 @@ Ingenic JZ47xx SoCs Timer/Counter Unit hardware =============================================== The Timer/Counter Unit (TCU) in Ingenic JZ47xx SoCs is a multi-function -hardware block. It features up to to eight channels, that can be used as +hardware block. It features up to eight channels, that can be used as counters, timers, or PWM. - JZ4725B, JZ4750, JZ4755 only have six TCU channels. The other SoCs all @@ -68,4 +68,4 @@ and frameworks can be controlled from the same registers, all of these drivers access their registers through the same regmap. For more information regarding the devicetree bindings of the TCU drivers, -have a look at Documentation/devicetree/bindings/timer/ingenic,tcu.txt. +have a look at Documentation/devicetree/bindings/timer/ingenic,tcu.yaml. diff --git a/Documentation/misc-devices/ad525x_dpot.txt b/Documentation/misc-devices/ad525x_dpot.rst index 0c9413b1cbf3..6483ec254520 100644 --- a/Documentation/misc-devices/ad525x_dpot.txt +++ b/Documentation/misc-devices/ad525x_dpot.rst @@ -1,6 +1,8 @@ ---------------------------------- - AD525x Digital Potentiometers ---------------------------------- +.. SPDX-License-Identifier: GPL-2.0 + +============================= +AD525x Digital Potentiometers +============================= The ad525x_dpot driver exports a simple sysfs interface. This allows you to work with the immediate resistance settings as well as update the saved startup @@ -8,9 +10,8 @@ settings. Access to the factory programmed tolerance is also provided, but interpretation of this settings is required by the end application according to the specific part in use. ---------- - Files ---------- +Files +===== Each dpot device will have a set of eeprom, rdac, and tolerance files. How many depends on the actual part you have, as will the range of allowed values. @@ -24,23 +25,22 @@ and may vary greatly on a part-by-part basis. For exact interpretation of this field, please consult the datasheet for your part. This is presented as a hex file for easier parsing. ------------ - Example ------------ +Example +======= Locate the device in your sysfs tree. This is probably easiest by going into -the common i2c directory and locating the device by the i2c slave address. +the common i2c directory and locating the device by the i2c slave address:: # ls /sys/bus/i2c/devices/ 0-0022 0-0027 0-002f So assuming the device in question is on the first i2c bus and has the slave -address of 0x2f, we descend (unrelated sysfs entries have been trimmed). +address of 0x2f, we descend (unrelated sysfs entries have been trimmed):: # ls /sys/bus/i2c/devices/0-002f/ eeprom0 rdac0 tolerance0 -You can use simple reads/writes to access these files: +You can use simple reads/writes to access these files:: # cd /sys/bus/i2c/devices/0-002f/ diff --git a/Documentation/misc-devices/apds990x.txt b/Documentation/misc-devices/apds990x.rst index 454d95d623b3..e2f75577f731 100644 --- a/Documentation/misc-devices/apds990x.txt +++ b/Documentation/misc-devices/apds990x.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================== Kernel driver apds990x ====================== @@ -50,14 +53,18 @@ chip_id power_state RW - enable / disable chip. Uses counting logic + 1 enables the chip 0 disables the chip lux0_input RO - measured lux value + sysfs_notify called when threshold interrupt occurs lux0_sensor_range - RO - lux0_input max value. Actually never reaches since sensor tends + RO - lux0_input max value. + + Actually never reaches since sensor tends to saturate much before that. Real max value varies depending on the light spectrum etc. @@ -68,7 +75,9 @@ lux0_rate_avail RO - supported measurement rates lux0_calibscale - RW - calibration value. Set to neutral value by default. + RW - calibration value. + + Set to neutral value by default. Output results are multiplied with calibscale / calibscale_default value. @@ -76,16 +85,21 @@ lux0_calibscale_default RO - neutral calibration value lux0_thresh_above_value - RW - HI level threshold value. All results above the value + RW - HI level threshold value. + + All results above the value trigs an interrupt. 65535 (i.e. sensor_range) disables the above interrupt. lux0_thresh_below_value - RW - LO level threshold value. All results below the value + RW - LO level threshold value. + + All results below the value trigs an interrupt. 0 disables the below interrupt. prox0_raw RO - measured proximity value + sysfs_notify called when threshold interrupt occurs prox0_sensor_range @@ -93,11 +107,14 @@ prox0_sensor_range prox0_raw_en RW - enable / disable proximity - uses counting logic - 1 enables the proximity - 0 disables the proximity + + - 1 enables the proximity + - 0 disables the proximity prox0_reporting_mode - RW - trigger / periodic. In "trigger" mode the driver tells two possible + RW - trigger / periodic. + + In "trigger" mode the driver tells two possible values: 0 or prox0_sensor_range value. 0 means no proximity, 1023 means proximity. This causes minimal number of interrupts. In "periodic" mode the driver reports all values above diff --git a/Documentation/misc-devices/bh1770glc.txt b/Documentation/misc-devices/bh1770glc.rst index 7d64c014dc70..ea5ca58bb958 100644 --- a/Documentation/misc-devices/bh1770glc.txt +++ b/Documentation/misc-devices/bh1770glc.rst @@ -1,9 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================= Kernel driver bh1770glc ======================= Supported chips: -ROHM BH1770GLC -OSRAM SFH7770 + +- ROHM BH1770GLC +- OSRAM SFH7770 Data sheet: Not freely available @@ -48,12 +52,16 @@ chip_id RO - shows detected chip type and version power_state - RW - enable / disable chip. Uses counting logic - 1 enables the chip - 0 disables the chip + RW - enable / disable chip + + Uses counting logic + + - 1 enables the chip + - 0 disables the chip lux0_input RO - measured lux value + sysfs_notify called when threshold interrupt occurs lux0_sensor_range @@ -66,16 +74,22 @@ lux0_rate_avail RO - supported measurement rates lux0_thresh_above_value - RW - HI level threshold value. All results above the value + RW - HI level threshold value + + All results above the value trigs an interrupt. 65535 (i.e. sensor_range) disables the above interrupt. lux0_thresh_below_value - RW - LO level threshold value. All results below the value + RW - LO level threshold value + + All results below the value trigs an interrupt. 0 disables the below interrupt. lux0_calibscale - RW - calibration value. Set to neutral value by default. + RW - calibration value + + Set to neutral value by default. Output results are multiplied with calibscale / calibscale_default value. @@ -84,32 +98,37 @@ lux0_calibscale_default prox0_raw RO - measured proximity value + sysfs_notify called when threshold interrupt occurs prox0_sensor_range RO - prox0_raw max value prox0_raw_en - RW - enable / disable proximity - uses counting logic - 1 enables the proximity - 0 disables the proximity + RW - enable / disable proximity + + Uses counting logic + + - 1 enables the proximity + - 0 disables the proximity prox0_thresh_above_count RW - number of proximity interrupts needed before triggering the event prox0_rate_above RW - Measurement rate (in Hz) when the level is above threshold - i.e. when proximity on has been reported. + i.e. when proximity on has been reported. prox0_rate_below RW - Measurement rate (in Hz) when the level is below threshold - i.e. when proximity off has been reported. + i.e. when proximity off has been reported. prox0_rate_avail RO - Supported proximity measurement rates in Hz prox0_thresh_above0_value RW - threshold level which trigs proximity events. + Filtered by persistence filter (prox0_thresh_above_count) prox0_thresh_above1_value diff --git a/Documentation/misc-devices/c2port.txt b/Documentation/misc-devices/c2port.rst index 31351b1a5a1f..7e4f6a79418a 100644 --- a/Documentation/misc-devices/c2port.txt +++ b/Documentation/misc-devices/c2port.rst @@ -1,5 +1,9 @@ - C2 port support - --------------- +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + +=============== +C2 port support +=============== (C) Copyright 2007 Rodolfo Giometti <giometti@enneenne.com> @@ -32,10 +36,10 @@ The C2 Interface main references are at (https://www.silabs.com) Silicon Laboratories site], see: - AN127: FLASH Programming via the C2 Interface at -https://www.silabs.com/Support Documents/TechnicalDocs/an127.pdf + https://www.silabs.com/Support Documents/TechnicalDocs/an127.pdf - C2 Specification at -https://www.silabs.com/pages/DownloadDoc.aspx?FILEURL=Support%20Documents/TechnicalDocs/an127.pdf&src=SearchResults + https://www.silabs.com/pages/DownloadDoc.aspx?FILEURL=Support%20Documents/TechnicalDocs/an127.pdf&src=SearchResults however it implements a two wire serial communication protocol (bit banging) designed to enable in-system programming, debugging, and @@ -47,44 +51,44 @@ Using the driver ---------------- Once the driver is loaded you can use sysfs support to get C2port's -info or read/write in-system flash. +info or read/write in-system flash:: -# ls /sys/class/c2port/c2port0/ -access flash_block_size flash_erase rev_id -dev_id flash_blocks_num flash_size subsystem/ -flash_access flash_data reset uevent + # ls /sys/class/c2port/c2port0/ + access flash_block_size flash_erase rev_id + dev_id flash_blocks_num flash_size subsystem/ + flash_access flash_data reset uevent Initially the C2port access is disabled since you hardware may have such lines multiplexed with other devices so, to get access to the -C2port, you need the command: +C2port, you need the command:: -# echo 1 > /sys/class/c2port/c2port0/access + # echo 1 > /sys/class/c2port/c2port0/access after that you should read the device ID and revision ID of the -connected micro controller: +connected micro controller:: -# cat /sys/class/c2port/c2port0/dev_id -8 -# cat /sys/class/c2port/c2port0/rev_id -1 + # cat /sys/class/c2port/c2port0/dev_id + 8 + # cat /sys/class/c2port/c2port0/rev_id + 1 However, for security reasons, the in-system flash access in not -enabled yet, to do so you need the command: +enabled yet, to do so you need the command:: -# echo 1 > /sys/class/c2port/c2port0/flash_access + # echo 1 > /sys/class/c2port/c2port0/flash_access -After that you can read the whole flash: +After that you can read the whole flash:: -# cat /sys/class/c2port/c2port0/flash_data > image + # cat /sys/class/c2port/c2port0/flash_data > image -erase it: +erase it:: -# echo 1 > /sys/class/c2port/c2port0/flash_erase + # echo 1 > /sys/class/c2port/c2port0/flash_erase -and write it: +and write it:: -# cat image > /sys/class/c2port/c2port0/flash_data + # cat image > /sys/class/c2port/c2port0/flash_data -after writing you have to reset the device to execute the new code: +after writing you have to reset the device to execute the new code:: -# echo 1 > /sys/class/c2port/c2port0/reset + # echo 1 > /sys/class/c2port/c2port0/reset diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst index 1ecc05fbe6f4..46072ce3d7ef 100644 --- a/Documentation/misc-devices/index.rst +++ b/Documentation/misc-devices/index.rst @@ -14,12 +14,18 @@ fit into other categories. .. toctree:: :maxdepth: 2 + ad525x_dpot + apds990x + bh1770glc eeprom + c2port ibmvmc ics932s401 isl29003 lis3lv02d max6875 mic/index + pci-endpoint-test + spear-pcie-gadget uacce xilinx_sdfec diff --git a/Documentation/misc-devices/pci-endpoint-test.rst b/Documentation/misc-devices/pci-endpoint-test.rst new file mode 100644 index 000000000000..4cf3f4433be7 --- /dev/null +++ b/Documentation/misc-devices/pci-endpoint-test.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================================== +Driver for PCI Endpoint Test Function +===================================== + +This driver should be used as a host side driver if the root complex is +connected to a configurable PCI endpoint running ``pci_epf_test`` function +driver configured according to [1]_. + +The "pci_endpoint_test" driver can be used to perform the following tests. + +The PCI driver for the test device performs the following tests: + + #) verifying addresses programmed in BAR + #) raise legacy IRQ + #) raise MSI IRQ + #) raise MSI-X IRQ + #) read data + #) write data + #) copy data + +This misc driver creates /dev/pci-endpoint-test.<num> for every +``pci_epf_test`` function connected to the root complex and "ioctls" +should be used to perform the above tests. + +ioctl +----- + + PCITEST_BAR: + Tests the BAR. The number of the BAR to be tested + should be passed as argument. + PCITEST_LEGACY_IRQ: + Tests legacy IRQ + PCITEST_MSI: + Tests message signalled interrupts. The MSI number + to be tested should be passed as argument. + PCITEST_MSIX: + Tests message signalled interrupts. The MSI-X number + to be tested should be passed as argument. + PCITEST_SET_IRQTYPE: + Changes driver IRQ type configuration. The IRQ type + should be passed as argument (0: Legacy, 1:MSI, 2:MSI-X). + PCITEST_GET_IRQTYPE: + Gets driver IRQ type configuration. + PCITEST_WRITE: + Perform write tests. The size of the buffer should be passed + as argument. + PCITEST_READ: + Perform read tests. The size of the buffer should be passed + as argument. + PCITEST_COPY: + Perform read tests. The size of the buffer should be passed + as argument. + +.. [1] Documentation/PCI/endpoint/function/binding/pci-test.rst diff --git a/Documentation/misc-devices/pci-endpoint-test.txt b/Documentation/misc-devices/pci-endpoint-test.txt deleted file mode 100644 index 58ccca4416b1..000000000000 --- a/Documentation/misc-devices/pci-endpoint-test.txt +++ /dev/null @@ -1,41 +0,0 @@ -Driver for PCI Endpoint Test Function - -This driver should be used as a host side driver if the root complex is -connected to a configurable PCI endpoint running *pci_epf_test* function -driver configured according to [1]. - -The "pci_endpoint_test" driver can be used to perform the following tests. - -The PCI driver for the test device performs the following tests - *) verifying addresses programmed in BAR - *) raise legacy IRQ - *) raise MSI IRQ - *) raise MSI-X IRQ - *) read data - *) write data - *) copy data - -This misc driver creates /dev/pci-endpoint-test.<num> for every -*pci_epf_test* function connected to the root complex and "ioctls" -should be used to perform the above tests. - -ioctl ------ - PCITEST_BAR: Tests the BAR. The number of the BAR to be tested - should be passed as argument. - PCITEST_LEGACY_IRQ: Tests legacy IRQ - PCITEST_MSI: Tests message signalled interrupts. The MSI number - to be tested should be passed as argument. - PCITEST_MSIX: Tests message signalled interrupts. The MSI-X number - to be tested should be passed as argument. - PCITEST_SET_IRQTYPE: Changes driver IRQ type configuration. The IRQ type - should be passed as argument (0: Legacy, 1:MSI, 2:MSI-X). - PCITEST_GET_IRQTYPE: Gets driver IRQ type configuration. - PCITEST_WRITE: Perform write tests. The size of the buffer should be passed - as argument. - PCITEST_READ: Perform read tests. The size of the buffer should be passed - as argument. - PCITEST_COPY: Perform read tests. The size of the buffer should be passed - as argument. - -[1] -> Documentation/PCI/endpoint/function/binding/pci-test.txt diff --git a/Documentation/misc-devices/spear-pcie-gadget.rst b/Documentation/misc-devices/spear-pcie-gadget.rst new file mode 100644 index 000000000000..09b9d6c7ac15 --- /dev/null +++ b/Documentation/misc-devices/spear-pcie-gadget.rst @@ -0,0 +1,170 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================== +Spear PCIe Gadget Driver +======================== + +Author +====== +Pratyush Anand (pratyush.anand@gmail.com) + +Location +======== +driver/misc/spear13xx_pcie_gadget.c + +Supported Chip: +=============== +SPEAr1300 +SPEAr1310 + +Menuconfig option: +================== +Device Drivers + Misc devices + PCIe gadget support for SPEAr13XX platform + +purpose +======= +This driver has several nodes which can be read/written by configfs interface. +Its main purpose is to configure selected dual mode PCIe controller as device +and then program its various registers to configure it as a particular device +type. This driver can be used to show spear's PCIe device capability. + +Description of different nodes: +=============================== + +read behavior of nodes: +----------------------- + +=============== ============================================================== +link gives ltssm status. +int_type type of supported interrupt +no_of_msi zero if MSI is not enabled by host. A positive value is the + number of MSI vector granted. +vendor_id returns programmed vendor id (hex) +device_id returns programmed device id(hex) +bar0_size: returns size of bar0 in hex. +bar0_address returns address of bar0 mapped area in hex. +bar0_rw_offset returns offset of bar0 for which bar0_data will return value. +bar0_data returns data at bar0_rw_offset. +=============== ============================================================== + +write behavior of nodes: +------------------------ + +=============== ================================================================ +link write UP to enable ltsmm DOWN to disable +int_type write interrupt type to be configured and (int_type could be + INTA, MSI or NO_INT). Select MSI only when you have programmed + no_of_msi node. +no_of_msi number of MSI vector needed. +inta write 1 to assert INTA and 0 to de-assert. +send_msi write MSI vector to be sent. +vendor_id write vendor id(hex) to be programmed. +device_id write device id(hex) to be programmed. +bar0_size write size of bar0 in hex. default bar0 size is 1000 (hex) + bytes. +bar0_address write address of bar0 mapped area in hex. (default mapping of + bar0 is SYSRAM1(E0800000). Always program bar size before bar + address. Kernel might modify bar size and address for alignment, + so read back bar size and address after writing to cross check. +bar0_rw_offset write offset of bar0 for which bar0_data will write value. +bar0_data write data to be written at bar0_rw_offset. +=============== ================================================================ + +Node programming example +======================== + +Program all PCIe registers in such a way that when this device is connected +to the PCIe host, then host sees this device as 1MB RAM. + +:: + + #mount -t configfs none /Config + +For nth PCIe Device Controller:: + + # cd /config/pcie_gadget.n/ + +Now you have all the nodes in this directory. +program vendor id as 0x104a:: + + # echo 104A >> vendor_id + +program device id as 0xCD80:: + + # echo CD80 >> device_id + +program BAR0 size as 1MB:: + + # echo 100000 >> bar0_size + +check for programmed bar0 size:: + + # cat bar0_size + +Program BAR0 Address as DDR (0x2100000). This is the physical address of +memory, which is to be made visible to PCIe host. Similarly any other peripheral +can also be made visible to PCIe host. E.g., if you program base address of UART +as BAR0 address then when this device will be connected to a host, it will be +visible as UART. + +:: + + # echo 2100000 >> bar0_address + +program interrupt type : INTA:: + + # echo INTA >> int_type + +go for link up now:: + + # echo UP >> link + +It will have to be insured that, once link up is done on gadget, then only host +is initialized and start to search PCIe devices on its port. + +:: + + /*wait till link is up*/ + # cat link + +Wait till it returns UP. + +To assert INTA:: + + # echo 1 >> inta + +To de-assert INTA:: + + # echo 0 >> inta + +if MSI is to be used as interrupt, program no of msi vector needed (say4):: + + # echo 4 >> no_of_msi + +select MSI as interrupt type:: + + # echo MSI >> int_type + +go for link up now:: + + # echo UP >> link + +wait till link is up:: + + # cat link + +An application can repetitively read this node till link is found UP. It can +sleep between two read. + +wait till msi is enabled:: + + # cat no_of_msi + +Should return 4 (number of requested MSI vector) + +to send msi vector 2:: + + # echo 2 >> send_msi + # cd - diff --git a/Documentation/misc-devices/spear-pcie-gadget.txt b/Documentation/misc-devices/spear-pcie-gadget.txt deleted file mode 100644 index 89b88dee4143..000000000000 --- a/Documentation/misc-devices/spear-pcie-gadget.txt +++ /dev/null @@ -1,130 +0,0 @@ -Spear PCIe Gadget Driver: - -Author -============= -Pratyush Anand (pratyush.anand@gmail.com) - -Location -============ -driver/misc/spear13xx_pcie_gadget.c - -Supported Chip: -=================== -SPEAr1300 -SPEAr1310 - -Menuconfig option: -========================== -Device Drivers - Misc devices - PCIe gadget support for SPEAr13XX platform -purpose -=========== -This driver has several nodes which can be read/written by configfs interface. -Its main purpose is to configure selected dual mode PCIe controller as device -and then program its various registers to configure it as a particular device -type. This driver can be used to show spear's PCIe device capability. - -Description of different nodes: -================================= - -read behavior of nodes: ------------------------------- -link :gives ltssm status. -int_type :type of supported interrupt -no_of_msi :zero if MSI is not enabled by host. A positive value is the - number of MSI vector granted. -vendor_id :returns programmed vendor id (hex) -device_id :returns programmed device id(hex) -bar0_size: :returns size of bar0 in hex. -bar0_address :returns address of bar0 mapped area in hex. -bar0_rw_offset :returns offset of bar0 for which bar0_data will return value. -bar0_data :returns data at bar0_rw_offset. - -write behavior of nodes: ------------------------------- -link :write UP to enable ltsmm DOWN to disable -int_type :write interrupt type to be configured and (int_type could be - INTA, MSI or NO_INT). Select MSI only when you have programmed - no_of_msi node. -no_of_msi :number of MSI vector needed. -inta :write 1 to assert INTA and 0 to de-assert. -send_msi :write MSI vector to be sent. -vendor_id :write vendor id(hex) to be programmed. -device_id :write device id(hex) to be programmed. -bar0_size :write size of bar0 in hex. default bar0 size is 1000 (hex) - bytes. -bar0_address :write address of bar0 mapped area in hex. (default mapping of - bar0 is SYSRAM1(E0800000). Always program bar size before bar - address. Kernel might modify bar size and address for alignment, so - read back bar size and address after writing to cross check. -bar0_rw_offset :write offset of bar0 for which bar0_data will write value. -bar0_data :write data to be written at bar0_rw_offset. - -Node programming example -=========================== -Program all PCIe registers in such a way that when this device is connected -to the PCIe host, then host sees this device as 1MB RAM. -#mount -t configfs none /Config -For nth PCIe Device Controller -# cd /config/pcie_gadget.n/ -Now you have all the nodes in this directory. -program vendor id as 0x104a -# echo 104A >> vendor_id - -program device id as 0xCD80 -# echo CD80 >> device_id - -program BAR0 size as 1MB -# echo 100000 >> bar0_size - -check for programmed bar0 size -# cat bar0_size - -Program BAR0 Address as DDR (0x2100000). This is the physical address of -memory, which is to be made visible to PCIe host. Similarly any other peripheral -can also be made visible to PCIe host. E.g., if you program base address of UART -as BAR0 address then when this device will be connected to a host, it will be -visible as UART. -# echo 2100000 >> bar0_address - -program interrupt type : INTA -# echo INTA >> int_type - -go for link up now. -# echo UP >> link - -It will have to be insured that, once link up is done on gadget, then only host -is initialized and start to search PCIe devices on its port. - -/*wait till link is up*/ -# cat link -wait till it returns UP. - -To assert INTA -# echo 1 >> inta - -To de-assert INTA -# echo 0 >> inta - -if MSI is to be used as interrupt, program no of msi vector needed (say4) -# echo 4 >> no_of_msi - -select MSI as interrupt type -# echo MSI >> int_type - -go for link up now -# echo UP >> link - -wait till link is up -# cat link -An application can repetitively read this node till link is found UP. It can -sleep between two read. - -wait till msi is enabled -# cat no_of_msi -Should return 4 (number of requested MSI vector) - -to send msi vector 2 -# echo 2 >> send_msi -#cd - diff --git a/Documentation/misc-devices/xilinx_sdfec.rst b/Documentation/misc-devices/xilinx_sdfec.rst index 7a47075c171c..8c8a289d69a3 100644 --- a/Documentation/misc-devices/xilinx_sdfec.rst +++ b/Documentation/misc-devices/xilinx_sdfec.rst @@ -78,7 +78,7 @@ application interfaces: - open: Implements restriction that only a single file descriptor can be open per SD-FEC instance at any time - release: Allows another file descriptor to be open, that is after current file descriptor is closed - poll: Provides a method to monitor for SD-FEC Error events - - unlocked_ioctl: Provides the the following ioctl commands that allows the application configure the SD-FEC core: + - unlocked_ioctl: Provides the following ioctl commands that allows the application configure the SD-FEC core: - :c:macro:`XSDFEC_START_DEV` - :c:macro:`XSDFEC_STOP_DEV` diff --git a/Documentation/networking/arcnet.rst b/Documentation/networking/arcnet.rst index e93d9820f0f1..82fce606c0f0 100644 --- a/Documentation/networking/arcnet.rst +++ b/Documentation/networking/arcnet.rst @@ -434,7 +434,7 @@ can set up your network then: ifconfig arc0 insight route add insight arc0 route add freedom arc0 /* I would use the subnet here (like I said - to to in "single protocol" above), + to in "single protocol" above), but the rest of the subnet unfortunately lies across the PPP link on freedom, which confuses diff --git a/Documentation/networking/ax25.rst b/Documentation/networking/ax25.rst index 824afd7002db..f060cfb1445a 100644 --- a/Documentation/networking/ax25.rst +++ b/Documentation/networking/ax25.rst @@ -6,7 +6,7 @@ AX.25 To use the amateur radio protocols within Linux you will need to get a suitable copy of the AX.25 Utilities. More detailed information about -AX.25, NET/ROM and ROSE, associated programs and and utilities can be +AX.25, NET/ROM and ROSE, associated programs and utilities can be found on http://www.linux-ax25.org. There is an active mailing list for discussing Linux amateur radio matters diff --git a/Documentation/networking/bareudp.rst b/Documentation/networking/bareudp.rst index 465a8b251bfe..b9d04ee6dac1 100644 --- a/Documentation/networking/bareudp.rst +++ b/Documentation/networking/bareudp.rst @@ -8,9 +8,8 @@ There are various L3 encapsulation standards using UDP being discussed to leverage the UDP based load balancing capability of different networks. MPLSoUDP (__ https://tools.ietf.org/html/rfc7510) is one among them. -The Bareudp tunnel module provides a generic L3 encapsulation tunnelling -support for tunnelling different L3 protocols like MPLS, IP, NSH etc. inside -a UDP tunnel. +The Bareudp tunnel module provides a generic L3 encapsulation support for +tunnelling different L3 protocols like MPLS, IP, NSH etc. inside a UDP tunnel. Special Handling ---------------- @@ -26,7 +25,7 @@ Usage 1) Device creation & deletion - a) ip link add dev bareudp0 type bareudp dstport 6635 ethertype 0x8847. + a) ip link add dev bareudp0 type bareudp dstport 6635 ethertype mpls_uc This creates a bareudp tunnel device which tunnels L3 traffic with ethertype 0x8847 (MPLS traffic). The destination port of the UDP header will be set to @@ -34,14 +33,21 @@ Usage b) ip link delete bareudp0 -2) Device creation with multiple proto mode enabled +2) Device creation with multiproto mode enabled -There are two ways to create a bareudp device for MPLS & IP with multiproto mode -enabled. +The multiproto mode allows bareudp tunnels to handle several protocols of the +same family. It is currently only available for IP and MPLS. This mode has to +be enabled explicitly with the "multiproto" flag. - a) ip link add dev bareudp0 type bareudp dstport 6635 ethertype 0x8847 multiproto + a) ip link add dev bareudp0 type bareudp dstport 6635 ethertype ipv4 multiproto - b) ip link add dev bareudp0 type bareudp dstport 6635 ethertype mpls + For an IPv4 tunnel the multiproto mode allows the tunnel to also handle + IPv6. + + b) ip link add dev bareudp0 type bareudp dstport 6635 ethertype mpls_uc multiproto + + For MPLS, the multiproto mode allows the tunnel to handle both unicast + and multicast MPLS packets. 3) Device Usage diff --git a/Documentation/networking/batman-adv.rst b/Documentation/networking/batman-adv.rst index 18020943ba25..74821d29a22f 100644 --- a/Documentation/networking/batman-adv.rst +++ b/Documentation/networking/batman-adv.rst @@ -73,7 +73,7 @@ lower value. This will make the mesh more responsive to topology changes, but will also increase the overhead. Information about the current state can be accessed via the batadv generic -netlink family. batctl provides human readable version via its debug tables +netlink family. batctl provides a human readable version via its debug tables subcommands. @@ -115,8 +115,8 @@ are prefixed with "batman-adv:" So to see just these messages try:: $ dmesg | grep batman-adv When investigating problems with your mesh network, it is sometimes necessary to -see more detail debug messages. This must be enabled when compiling the -batman-adv module. When building batman-adv as part of kernel, use "make +see more detailed debug messages. This must be enabled when compiling the +batman-adv module. When building batman-adv as part of the kernel, use "make menuconfig" and enable the option ``B.A.T.M.A.N. debugging`` (``CONFIG_BATMAN_ADV_DEBUG=y``). @@ -160,7 +160,7 @@ IRC: #batman on irc.freenode.org Mailing-list: b.a.t.m.a.n@open-mesh.org (optional subscription at - https://lists.open-mesh.org/mm/listinfo/b.a.t.m.a.n) + https://lists.open-mesh.org/mailman3/postorius/lists/b.a.t.m.a.n.lists.open-mesh.org/) You can also contact the Authors: diff --git a/Documentation/networking/can_ucan_protocol.rst b/Documentation/networking/can_ucan_protocol.rst index 4cef88d24fc7..638ac1ee7914 100644 --- a/Documentation/networking/can_ucan_protocol.rst +++ b/Documentation/networking/can_ucan_protocol.rst @@ -144,7 +144,7 @@ UCAN_COMMAND_SET_BITTIMING *Host2Dev; mandatory* -Setup bittiming by sending the the structure +Setup bittiming by sending the structure ``ucan_ctl_payload_t.cmd_set_bittiming`` (see ``struct bittiming`` for details) @@ -232,7 +232,7 @@ UCAN_IN_TX_COMPLETE zero The CAN device has sent a message to the CAN bus. It answers with a -list of of tuples <echo-ids, flags>. +list of tuples <echo-ids, flags>. The echo-id identifies the frame from (echos the id from a previous UCAN_OUT_TX message). The flag indicates the result of the diff --git a/Documentation/networking/dccp.rst b/Documentation/networking/dccp.rst index dde16be04456..91e5c33ba3ff 100644 --- a/Documentation/networking/dccp.rst +++ b/Documentation/networking/dccp.rst @@ -192,6 +192,9 @@ FIONREAD Works as in udp(7): returns in the ``int`` argument pointer the size of the next pending datagram in bytes, or 0 when no datagram is pending. +SIOCOUTQ + Returns the number of unsent data bytes in the socket send queue as ``int`` + into the buffer specified by the argument pointer. Other tunables ============== diff --git a/Documentation/networking/cops.rst b/Documentation/networking/device_drivers/appletalk/cops.rst index 964ba80599a9..964ba80599a9 100644 --- a/Documentation/networking/cops.rst +++ b/Documentation/networking/device_drivers/appletalk/cops.rst diff --git a/Documentation/networking/device_drivers/appletalk/index.rst b/Documentation/networking/device_drivers/appletalk/index.rst new file mode 100644 index 000000000000..de7507f02037 --- /dev/null +++ b/Documentation/networking/device_drivers/appletalk/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) + +AppleTalk Device Drivers +======================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + cops + ltpc + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/networking/ltpc.rst b/Documentation/networking/device_drivers/appletalk/ltpc.rst index 0ad197fd17ce..0ad197fd17ce 100644 --- a/Documentation/networking/ltpc.rst +++ b/Documentation/networking/device_drivers/appletalk/ltpc.rst diff --git a/Documentation/networking/cxacru-cf.py b/Documentation/networking/device_drivers/atm/cxacru-cf.py index b41d298398c8..b41d298398c8 100644 --- a/Documentation/networking/cxacru-cf.py +++ b/Documentation/networking/device_drivers/atm/cxacru-cf.py diff --git a/Documentation/networking/cxacru.rst b/Documentation/networking/device_drivers/atm/cxacru.rst index 6088af2ffeda..6088af2ffeda 100644 --- a/Documentation/networking/cxacru.rst +++ b/Documentation/networking/device_drivers/atm/cxacru.rst diff --git a/Documentation/networking/fore200e.rst b/Documentation/networking/device_drivers/atm/fore200e.rst index 55df9ec09ac8..55df9ec09ac8 100644 --- a/Documentation/networking/fore200e.rst +++ b/Documentation/networking/device_drivers/atm/fore200e.rst diff --git a/Documentation/networking/device_drivers/atm/index.rst b/Documentation/networking/device_drivers/atm/index.rst new file mode 100644 index 000000000000..7b593f031a60 --- /dev/null +++ b/Documentation/networking/device_drivers/atm/index.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) + +Asynchronous Transfer Mode (ATM) Device Drivers +=============================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + cxacru + fore200e + iphase + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/networking/iphase.rst b/Documentation/networking/device_drivers/atm/iphase.rst index 92d9b757d75a..92d9b757d75a 100644 --- a/Documentation/networking/iphase.rst +++ b/Documentation/networking/device_drivers/atm/iphase.rst diff --git a/Documentation/networking/device_drivers/cable/index.rst b/Documentation/networking/device_drivers/cable/index.rst new file mode 100644 index 000000000000..cce3c4392972 --- /dev/null +++ b/Documentation/networking/device_drivers/cable/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) + +Cable Modem Device Drivers +========================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + sb1000 + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/networking/device_drivers/sb1000.rst b/Documentation/networking/device_drivers/cable/sb1000.rst index c8582ca4034d..c8582ca4034d 100644 --- a/Documentation/networking/device_drivers/sb1000.rst +++ b/Documentation/networking/device_drivers/cable/sb1000.rst diff --git a/Documentation/networking/device_drivers/cellular/index.rst b/Documentation/networking/device_drivers/cellular/index.rst new file mode 100644 index 000000000000..fc1812d3fc70 --- /dev/null +++ b/Documentation/networking/device_drivers/cellular/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) + +Cellular Modem Device Drivers +============================= + +Contents: + +.. toctree:: + :maxdepth: 2 + + qualcomm/rmnet + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/networking/device_drivers/qualcomm/rmnet.rst b/Documentation/networking/device_drivers/cellular/qualcomm/rmnet.rst index 70643b58de05..70643b58de05 100644 --- a/Documentation/networking/device_drivers/qualcomm/rmnet.rst +++ b/Documentation/networking/device_drivers/cellular/qualcomm/rmnet.rst diff --git a/Documentation/networking/device_drivers/3com/3c509.rst b/Documentation/networking/device_drivers/ethernet/3com/3c509.rst index 47f706bacdd9..47f706bacdd9 100644 --- a/Documentation/networking/device_drivers/3com/3c509.rst +++ b/Documentation/networking/device_drivers/ethernet/3com/3c509.rst diff --git a/Documentation/networking/device_drivers/3com/vortex.rst b/Documentation/networking/device_drivers/ethernet/3com/vortex.rst index 800add5be338..eab10fc6da5c 100644 --- a/Documentation/networking/device_drivers/3com/vortex.rst +++ b/Documentation/networking/device_drivers/ethernet/3com/vortex.rst @@ -4,8 +4,6 @@ 3Com Vortex device driver ========================= -Documentation/networking/device_drivers/3com/vortex.rst - Andrew Morton 30 April 2000 diff --git a/Documentation/networking/altera_tse.rst b/Documentation/networking/device_drivers/ethernet/altera/altera_tse.rst index 7a7040072e58..7a7040072e58 100644 --- a/Documentation/networking/altera_tse.rst +++ b/Documentation/networking/device_drivers/ethernet/altera/altera_tse.rst diff --git a/Documentation/networking/device_drivers/amazon/ena.rst b/Documentation/networking/device_drivers/ethernet/amazon/ena.rst index 11af6388ea87..11af6388ea87 100644 --- a/Documentation/networking/device_drivers/amazon/ena.rst +++ b/Documentation/networking/device_drivers/ethernet/amazon/ena.rst diff --git a/Documentation/networking/device_drivers/aquantia/atlantic.rst b/Documentation/networking/device_drivers/ethernet/aquantia/atlantic.rst index 595ddef1c8b3..595ddef1c8b3 100644 --- a/Documentation/networking/device_drivers/aquantia/atlantic.rst +++ b/Documentation/networking/device_drivers/ethernet/aquantia/atlantic.rst diff --git a/Documentation/networking/device_drivers/chelsio/cxgb.rst b/Documentation/networking/device_drivers/ethernet/chelsio/cxgb.rst index 435dce5fa2c7..435dce5fa2c7 100644 --- a/Documentation/networking/device_drivers/chelsio/cxgb.rst +++ b/Documentation/networking/device_drivers/ethernet/chelsio/cxgb.rst diff --git a/Documentation/networking/device_drivers/cirrus/cs89x0.rst b/Documentation/networking/device_drivers/ethernet/cirrus/cs89x0.rst index e5c283940ac5..e5c283940ac5 100644 --- a/Documentation/networking/device_drivers/cirrus/cs89x0.rst +++ b/Documentation/networking/device_drivers/ethernet/cirrus/cs89x0.rst diff --git a/Documentation/networking/device_drivers/davicom/dm9000.rst b/Documentation/networking/device_drivers/ethernet/davicom/dm9000.rst index d5458da01083..d5458da01083 100644 --- a/Documentation/networking/device_drivers/davicom/dm9000.rst +++ b/Documentation/networking/device_drivers/ethernet/davicom/dm9000.rst diff --git a/Documentation/networking/device_drivers/dec/de4x5.rst b/Documentation/networking/device_drivers/ethernet/dec/de4x5.rst index e03e9c631879..e03e9c631879 100644 --- a/Documentation/networking/device_drivers/dec/de4x5.rst +++ b/Documentation/networking/device_drivers/ethernet/dec/de4x5.rst diff --git a/Documentation/networking/device_drivers/dec/dmfe.rst b/Documentation/networking/device_drivers/ethernet/dec/dmfe.rst index c4cf809cad84..c4cf809cad84 100644 --- a/Documentation/networking/device_drivers/dec/dmfe.rst +++ b/Documentation/networking/device_drivers/ethernet/dec/dmfe.rst diff --git a/Documentation/networking/device_drivers/dlink/dl2k.rst b/Documentation/networking/device_drivers/ethernet/dlink/dl2k.rst index ccdb5d0d7460..ccdb5d0d7460 100644 --- a/Documentation/networking/device_drivers/dlink/dl2k.rst +++ b/Documentation/networking/device_drivers/ethernet/dlink/dl2k.rst diff --git a/Documentation/networking/device_drivers/freescale/dpaa.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa.rst index 241c6c6f6e68..241c6c6f6e68 100644 --- a/Documentation/networking/device_drivers/freescale/dpaa.rst +++ b/Documentation/networking/device_drivers/ethernet/freescale/dpaa.rst diff --git a/Documentation/networking/device_drivers/freescale/dpaa2/dpio-driver.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/dpio-driver.rst index 17dbee1ac53e..c50fd46631e0 100644 --- a/Documentation/networking/device_drivers/freescale/dpaa2/dpio-driver.rst +++ b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/dpio-driver.rst @@ -19,8 +19,10 @@ pool management for network interfaces. This document provides an overview the Linux DPIO driver, its subcomponents, and its APIs. -See Documentation/networking/device_drivers/freescale/dpaa2/overview.rst for -a general overview of DPAA2 and the general DPAA2 driver architecture in Linux. +See +Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst +for a general overview of DPAA2 and the general DPAA2 driver architecture +in Linux. Driver Overview --------------- diff --git a/Documentation/networking/device_drivers/freescale/dpaa2/ethernet-driver.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/ethernet-driver.rst index cb4c9a0c5a17..682f3986c15b 100644 --- a/Documentation/networking/device_drivers/freescale/dpaa2/ethernet-driver.rst +++ b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/ethernet-driver.rst @@ -33,7 +33,8 @@ hardware resources, like queues, do not have a corresponding MC object and are treated as internal resources of other objects. For a more detailed description of the DPAA2 architecture and its object -abstractions see *Documentation/networking/device_drivers/freescale/dpaa2/overview.rst*. +abstractions see +*Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst*. Each Linux net device is built on top of a Datapath Network Interface (DPNI) object and uses Buffer Pools (DPBPs), I/O Portals (DPIOs) and Concentrators diff --git a/Documentation/networking/device_drivers/freescale/dpaa2/index.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/index.rst index ee40fcc5ddff..ee40fcc5ddff 100644 --- a/Documentation/networking/device_drivers/freescale/dpaa2/index.rst +++ b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/index.rst diff --git a/Documentation/networking/device_drivers/freescale/dpaa2/mac-phy-support.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/mac-phy-support.rst index 51e6624fb774..51e6624fb774 100644 --- a/Documentation/networking/device_drivers/freescale/dpaa2/mac-phy-support.rst +++ b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/mac-phy-support.rst diff --git a/Documentation/networking/device_drivers/freescale/dpaa2/overview.rst b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst index d638b5a8aadd..d638b5a8aadd 100644 --- a/Documentation/networking/device_drivers/freescale/dpaa2/overview.rst +++ b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst diff --git a/Documentation/networking/device_drivers/freescale/gianfar.rst b/Documentation/networking/device_drivers/ethernet/freescale/gianfar.rst index 9c4a91d3824b..9c4a91d3824b 100644 --- a/Documentation/networking/device_drivers/freescale/gianfar.rst +++ b/Documentation/networking/device_drivers/ethernet/freescale/gianfar.rst diff --git a/Documentation/networking/device_drivers/google/gve.rst b/Documentation/networking/device_drivers/ethernet/google/gve.rst index 793693cef6e3..793693cef6e3 100644 --- a/Documentation/networking/device_drivers/google/gve.rst +++ b/Documentation/networking/device_drivers/ethernet/google/gve.rst diff --git a/Documentation/networking/hinic.rst b/Documentation/networking/device_drivers/ethernet/huawei/hinic.rst index 867ac8f4e04a..867ac8f4e04a 100644 --- a/Documentation/networking/hinic.rst +++ b/Documentation/networking/device_drivers/ethernet/huawei/hinic.rst diff --git a/Documentation/networking/device_drivers/ethernet/index.rst b/Documentation/networking/device_drivers/ethernet/index.rst new file mode 100644 index 000000000000..cbb75a1818c0 --- /dev/null +++ b/Documentation/networking/device_drivers/ethernet/index.rst @@ -0,0 +1,60 @@ +.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) + +Ethernet Device Drivers +======================= + +Device drivers for Ethernet and Ethernet-based virtual function devices. + +Contents: + +.. toctree:: + :maxdepth: 2 + + 3com/3c509 + 3com/vortex + amazon/ena + altera/altera_tse + aquantia/atlantic + chelsio/cxgb + cirrus/cs89x0 + dlink/dl2k + davicom/dm9000 + dec/de4x5 + dec/dmfe + freescale/dpaa + freescale/dpaa2/index + freescale/gianfar + google/gve + huawei/hinic + intel/e100 + intel/e1000 + intel/e1000e + intel/fm10k + intel/igb + intel/igbvf + intel/ixgb + intel/ixgbe + intel/ixgbevf + intel/i40e + intel/iavf + intel/ice + marvell/octeontx2 + mellanox/mlx5 + microsoft/netvsc + neterion/s2io + neterion/vxge + netronome/nfp + pensando/ionic + smsc/smc9 + stmicro/stmmac + ti/cpsw + ti/cpsw_switchdev + ti/tlan + toshiba/spider_net + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/networking/device_drivers/intel/e100.rst b/Documentation/networking/device_drivers/ethernet/intel/e100.rst index 3ac21e7119a7..3d4a9ba21946 100644 --- a/Documentation/networking/device_drivers/intel/e100.rst +++ b/Documentation/networking/device_drivers/ethernet/intel/e100.rst @@ -41,7 +41,7 @@ Identifying Your Adapter For information on how to identify your adapter, and for the latest Intel network drivers, refer to the Intel Support website: -http://www.intel.com/support +https://www.intel.com/support Driver Configuration Parameters =============================== @@ -179,7 +179,7 @@ filtering by Support ======= For general information, go to the Intel support website at: -http://www.intel.com/support/ +https://www.intel.com/support/ or the Intel Wired Networking project hosted by Sourceforge at: http://sourceforge.net/projects/e1000 diff --git a/Documentation/networking/device_drivers/intel/e1000.rst b/Documentation/networking/device_drivers/ethernet/intel/e1000.rst index 4aaae0f7d6ba..4aaae0f7d6ba 100644 --- a/Documentation/networking/device_drivers/intel/e1000.rst +++ b/Documentation/networking/device_drivers/ethernet/intel/e1000.rst diff --git a/Documentation/networking/device_drivers/intel/e1000e.rst b/Documentation/networking/device_drivers/ethernet/intel/e1000e.rst index f49cd370e7bf..f49cd370e7bf 100644 --- a/Documentation/networking/device_drivers/intel/e1000e.rst +++ b/Documentation/networking/device_drivers/ethernet/intel/e1000e.rst diff --git a/Documentation/networking/device_drivers/intel/fm10k.rst b/Documentation/networking/device_drivers/ethernet/intel/fm10k.rst index 4d279e64e221..9258ef6f515c 100644 --- a/Documentation/networking/device_drivers/intel/fm10k.rst +++ b/Documentation/networking/device_drivers/ethernet/intel/fm10k.rst @@ -22,7 +22,7 @@ Ethernet Multi-host Controller. For information on how to identify your adapter, and for the latest Intel network drivers, refer to the Intel Support website: -http://www.intel.com/support +https://www.intel.com/support Flow Control diff --git a/Documentation/networking/device_drivers/intel/i40e.rst b/Documentation/networking/device_drivers/ethernet/intel/i40e.rst index 8a9b18573688..8a9b18573688 100644 --- a/Documentation/networking/device_drivers/intel/i40e.rst +++ b/Documentation/networking/device_drivers/ethernet/intel/i40e.rst diff --git a/Documentation/networking/device_drivers/intel/iavf.rst b/Documentation/networking/device_drivers/ethernet/intel/iavf.rst index 84ac7e75f363..52e037b11c97 100644 --- a/Documentation/networking/device_drivers/intel/iavf.rst +++ b/Documentation/networking/device_drivers/ethernet/intel/iavf.rst @@ -43,7 +43,7 @@ device. For information on how to identify your adapter, and for the latest NVM/FW images and Intel network drivers, refer to the Intel Support website: -http://www.intel.com/support +https://www.intel.com/support Additional Features and Configurations diff --git a/Documentation/networking/device_drivers/intel/ice.rst b/Documentation/networking/device_drivers/ethernet/intel/ice.rst index ee43ea57d443..ee43ea57d443 100644 --- a/Documentation/networking/device_drivers/intel/ice.rst +++ b/Documentation/networking/device_drivers/ethernet/intel/ice.rst diff --git a/Documentation/networking/device_drivers/intel/igb.rst b/Documentation/networking/device_drivers/ethernet/intel/igb.rst index 87e560fe5eaa..d46289e182cf 100644 --- a/Documentation/networking/device_drivers/intel/igb.rst +++ b/Documentation/networking/device_drivers/ethernet/intel/igb.rst @@ -20,7 +20,7 @@ Identifying Your Adapter ======================== For information on how to identify your adapter, and for the latest Intel network drivers, refer to the Intel Support website: -http://www.intel.com/support +https://www.intel.com/support Command Line Parameters diff --git a/Documentation/networking/device_drivers/intel/igbvf.rst b/Documentation/networking/device_drivers/ethernet/intel/igbvf.rst index 557fc020ef31..40fa210c5e14 100644 --- a/Documentation/networking/device_drivers/intel/igbvf.rst +++ b/Documentation/networking/device_drivers/ethernet/intel/igbvf.rst @@ -35,7 +35,7 @@ Identifying Your Adapter ======================== For information on how to identify your adapter, and for the latest Intel network drivers, refer to the Intel Support website: -http://www.intel.com/support +https://www.intel.com/support Additional Features and Configurations diff --git a/Documentation/networking/device_drivers/intel/ixgb.rst b/Documentation/networking/device_drivers/ethernet/intel/ixgb.rst index ab624f1a44a8..c6a233e68ad6 100644 --- a/Documentation/networking/device_drivers/intel/ixgb.rst +++ b/Documentation/networking/device_drivers/ethernet/intel/ixgb.rst @@ -203,7 +203,7 @@ With the 10 Gigabit server adapters, the default Linux configuration will very likely limit the total available throughput artificially. There is a set of configuration changes that, when applied together, will increase the ability of Linux to transmit and receive data. The following enhancements were -originally acquired from settings published at http://www.spec.org/web99/ for +originally acquired from settings published at https://www.spec.org/web99/ for various submitted results using Linux. NOTE: diff --git a/Documentation/networking/device_drivers/intel/ixgbe.rst b/Documentation/networking/device_drivers/ethernet/intel/ixgbe.rst index f1d5233e5e51..f1d5233e5e51 100644 --- a/Documentation/networking/device_drivers/intel/ixgbe.rst +++ b/Documentation/networking/device_drivers/ethernet/intel/ixgbe.rst diff --git a/Documentation/networking/device_drivers/intel/ixgbevf.rst b/Documentation/networking/device_drivers/ethernet/intel/ixgbevf.rst index 76bbde736f21..76bbde736f21 100644 --- a/Documentation/networking/device_drivers/intel/ixgbevf.rst +++ b/Documentation/networking/device_drivers/ethernet/intel/ixgbevf.rst diff --git a/Documentation/networking/device_drivers/marvell/octeontx2.rst b/Documentation/networking/device_drivers/ethernet/marvell/octeontx2.rst index 88f508338c5f..88f508338c5f 100644 --- a/Documentation/networking/device_drivers/marvell/octeontx2.rst +++ b/Documentation/networking/device_drivers/ethernet/marvell/octeontx2.rst diff --git a/Documentation/networking/device_drivers/mellanox/mlx5.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst index e9b65035cd47..e9b65035cd47 100644 --- a/Documentation/networking/device_drivers/mellanox/mlx5.rst +++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5.rst diff --git a/Documentation/networking/device_drivers/microsoft/netvsc.rst b/Documentation/networking/device_drivers/ethernet/microsoft/netvsc.rst index c3f51c672a68..c3f51c672a68 100644 --- a/Documentation/networking/device_drivers/microsoft/netvsc.rst +++ b/Documentation/networking/device_drivers/ethernet/microsoft/netvsc.rst diff --git a/Documentation/networking/device_drivers/neterion/s2io.rst b/Documentation/networking/device_drivers/ethernet/neterion/s2io.rst index c5673ec4559b..c5673ec4559b 100644 --- a/Documentation/networking/device_drivers/neterion/s2io.rst +++ b/Documentation/networking/device_drivers/ethernet/neterion/s2io.rst diff --git a/Documentation/networking/device_drivers/neterion/vxge.rst b/Documentation/networking/device_drivers/ethernet/neterion/vxge.rst index 589c6b15c63d..589c6b15c63d 100644 --- a/Documentation/networking/device_drivers/neterion/vxge.rst +++ b/Documentation/networking/device_drivers/ethernet/neterion/vxge.rst diff --git a/Documentation/networking/device_drivers/netronome/nfp.rst b/Documentation/networking/device_drivers/ethernet/netronome/nfp.rst index ada611fb427c..ada611fb427c 100644 --- a/Documentation/networking/device_drivers/netronome/nfp.rst +++ b/Documentation/networking/device_drivers/ethernet/netronome/nfp.rst diff --git a/Documentation/networking/device_drivers/pensando/ionic.rst b/Documentation/networking/device_drivers/ethernet/pensando/ionic.rst index 0eabbc347d6c..0eabbc347d6c 100644 --- a/Documentation/networking/device_drivers/pensando/ionic.rst +++ b/Documentation/networking/device_drivers/ethernet/pensando/ionic.rst diff --git a/Documentation/networking/device_drivers/smsc/smc9.rst b/Documentation/networking/device_drivers/ethernet/smsc/smc9.rst index e5eac896a631..e5eac896a631 100644 --- a/Documentation/networking/device_drivers/smsc/smc9.rst +++ b/Documentation/networking/device_drivers/ethernet/smsc/smc9.rst diff --git a/Documentation/networking/device_drivers/stmicro/stmmac.rst b/Documentation/networking/device_drivers/ethernet/stmicro/stmmac.rst index 5d46e5036129..5d46e5036129 100644 --- a/Documentation/networking/device_drivers/stmicro/stmmac.rst +++ b/Documentation/networking/device_drivers/ethernet/stmicro/stmmac.rst diff --git a/Documentation/networking/device_drivers/ti/cpsw.rst b/Documentation/networking/device_drivers/ethernet/ti/cpsw.rst index a88946bd188b..a88946bd188b 100644 --- a/Documentation/networking/device_drivers/ti/cpsw.rst +++ b/Documentation/networking/device_drivers/ethernet/ti/cpsw.rst diff --git a/Documentation/networking/device_drivers/ti/cpsw_switchdev.rst b/Documentation/networking/device_drivers/ethernet/ti/cpsw_switchdev.rst index 1241ecac73bd..1241ecac73bd 100644 --- a/Documentation/networking/device_drivers/ti/cpsw_switchdev.rst +++ b/Documentation/networking/device_drivers/ethernet/ti/cpsw_switchdev.rst diff --git a/Documentation/networking/device_drivers/ti/tlan.rst b/Documentation/networking/device_drivers/ethernet/ti/tlan.rst index 4fdc0907f4fc..4fdc0907f4fc 100644 --- a/Documentation/networking/device_drivers/ti/tlan.rst +++ b/Documentation/networking/device_drivers/ethernet/ti/tlan.rst diff --git a/Documentation/networking/device_drivers/toshiba/spider_net.rst b/Documentation/networking/device_drivers/ethernet/toshiba/spider_net.rst index fe5b32be15cd..fe5b32be15cd 100644 --- a/Documentation/networking/device_drivers/toshiba/spider_net.rst +++ b/Documentation/networking/device_drivers/ethernet/toshiba/spider_net.rst diff --git a/Documentation/networking/defza.rst b/Documentation/networking/device_drivers/fddi/defza.rst index 73c2f793ea26..73c2f793ea26 100644 --- a/Documentation/networking/defza.rst +++ b/Documentation/networking/device_drivers/fddi/defza.rst diff --git a/Documentation/networking/device_drivers/fddi/index.rst b/Documentation/networking/device_drivers/fddi/index.rst new file mode 100644 index 000000000000..0b75294e6c8b --- /dev/null +++ b/Documentation/networking/device_drivers/fddi/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) + +Fiber Distributed Data Interface (FDDI) Device Drivers +====================================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + defza + skfp + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/networking/skfp.rst b/Documentation/networking/device_drivers/fddi/skfp.rst index 58f548105c1d..58f548105c1d 100644 --- a/Documentation/networking/skfp.rst +++ b/Documentation/networking/device_drivers/fddi/skfp.rst diff --git a/Documentation/networking/baycom.rst b/Documentation/networking/device_drivers/hamradio/baycom.rst index fe2d010f0e86..fe2d010f0e86 100644 --- a/Documentation/networking/baycom.rst +++ b/Documentation/networking/device_drivers/hamradio/baycom.rst diff --git a/Documentation/networking/device_drivers/hamradio/index.rst b/Documentation/networking/device_drivers/hamradio/index.rst new file mode 100644 index 000000000000..7e731732057b --- /dev/null +++ b/Documentation/networking/device_drivers/hamradio/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) + +Amateur Radio Device Drivers +============================ + +Contents: + +.. toctree:: + :maxdepth: 2 + + baycom + z8530drv + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/networking/z8530drv.rst b/Documentation/networking/device_drivers/hamradio/z8530drv.rst index d2942760f167..d2942760f167 100644 --- a/Documentation/networking/z8530drv.rst +++ b/Documentation/networking/device_drivers/hamradio/z8530drv.rst diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index e18dad11bc72..a3113ffd7a16 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -1,56 +1,22 @@ .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) -Vendor Device Drivers -===================== +Hardware Device Drivers +======================= Contents: .. toctree:: :maxdepth: 2 - freescale/dpaa2/index - intel/e100 - intel/e1000 - intel/e1000e - intel/fm10k - intel/igb - intel/igbvf - intel/ixgb - intel/ixgbe - intel/ixgbevf - intel/i40e - intel/iavf - intel/ice - google/gve - marvell/octeontx2 - mellanox/mlx5 - netronome/nfp - pensando/ionic - stmicro/stmmac - 3com/3c509 - 3com/vortex - amazon/ena - aquantia/atlantic - chelsio/cxgb - cirrus/cs89x0 - davicom/dm9000 - dec/de4x5 - dec/dmfe - dlink/dl2k - freescale/dpaa - freescale/gianfar - intel/ipw2100 - intel/ipw2200 - microsoft/netvsc - neterion/s2io - neterion/vxge - qualcomm/rmnet - sb1000 - smsc/smc9 - ti/cpsw_switchdev - ti/cpsw - ti/tlan - toshiba/spider_net + appletalk/index + atm/index + cable/index + cellular/index + ethernet/index + fddi/index + hamradio/index + wan/index + wifi/index .. only:: subproject and html diff --git a/Documentation/networking/device_drivers/wan/index.rst b/Documentation/networking/device_drivers/wan/index.rst new file mode 100644 index 000000000000..9d9ae94f00b4 --- /dev/null +++ b/Documentation/networking/device_drivers/wan/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) + +Classic WAN Device Drivers +========================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + z8530book + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/networking/z8530book.rst b/Documentation/networking/device_drivers/wan/z8530book.rst index fea2c40e7973..fea2c40e7973 100644 --- a/Documentation/networking/z8530book.rst +++ b/Documentation/networking/device_drivers/wan/z8530book.rst diff --git a/Documentation/networking/device_drivers/wifi/index.rst b/Documentation/networking/device_drivers/wifi/index.rst new file mode 100644 index 000000000000..bf91a87c7acf --- /dev/null +++ b/Documentation/networking/device_drivers/wifi/index.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) + +Wi-Fi Device Drivers +==================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + intel/ipw2100 + intel/ipw2200 + ray_cs + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/networking/device_drivers/intel/ipw2100.rst b/Documentation/networking/device_drivers/wifi/intel/ipw2100.rst index d54ad522f937..883e96355799 100644 --- a/Documentation/networking/device_drivers/intel/ipw2100.rst +++ b/Documentation/networking/device_drivers/wifi/intel/ipw2100.rst @@ -78,7 +78,7 @@ such, if you are interested in deploying or shipping a driver as part of solution intended to be used for purposes other than development, please obtain a tested driver from Intel Customer Support at: -http://www.intel.com/support/wireless/sb/CS-006408.htm +https://www.intel.com/support/wireless/sb/CS-006408.htm 1. Introduction =============== diff --git a/Documentation/networking/device_drivers/intel/ipw2200.rst b/Documentation/networking/device_drivers/wifi/intel/ipw2200.rst index 0cb42d2fd7e5..0cb42d2fd7e5 100644 --- a/Documentation/networking/device_drivers/intel/ipw2200.rst +++ b/Documentation/networking/device_drivers/wifi/intel/ipw2200.rst diff --git a/Documentation/networking/ray_cs.rst b/Documentation/networking/device_drivers/wifi/ray_cs.rst index 9a46d1ae8f20..9a46d1ae8f20 100644 --- a/Documentation/networking/ray_cs.rst +++ b/Documentation/networking/device_drivers/wifi/ray_cs.rst diff --git a/Documentation/networking/devlink/devlink-info.rst b/Documentation/networking/devlink/devlink-info.rst index 3fe11401b838..7572bf6de5c1 100644 --- a/Documentation/networking/devlink/devlink-info.rst +++ b/Documentation/networking/devlink/devlink-info.rst @@ -44,9 +44,11 @@ versions is generally discouraged - here, and via any other Linux API. reported for two ports of the same device or on two hosts of a multi-host device should be identical. - .. note:: ``devlink-info`` API should be extended with a new field - if devices want to report board/product serial number (often - reported in PCI *Vital Product Data* capability). + * - ``board.serial_number`` + - Board serial number of the device. + + This is usually the serial number of the board, often available in + PCI *Vital Product Data*. * - ``fixed`` - Group for hardware identifiers, and versions of components @@ -201,10 +203,6 @@ Future work The following extensions could be useful: - - product serial number - NIC boards often get labeled with a board serial - number rather than ASIC serial number; it'd be useful to add board serial - numbers to the API if they can be retrieved from the device; - - on-disk firmware file names - drivers list the file names of firmware they may need to load onto devices via the ``MODULE_FIRMWARE()`` macro. These, however, are per module, rather than per device. It'd be useful to list diff --git a/Documentation/networking/devlink/devlink-trap.rst b/Documentation/networking/devlink/devlink-trap.rst index 1e3f3ffee248..7a798352b45d 100644 --- a/Documentation/networking/devlink/devlink-trap.rst +++ b/Documentation/networking/devlink/devlink-trap.rst @@ -405,6 +405,10 @@ be added to the following table: - ``control`` - Traps packets logged during processing of flow action trap (e.g., via tc's trap action) + * - ``early_drop`` + - ``drop`` + - Traps packets dropped due to the RED (Random Early Detection) algorithm + (i.e., early drops) Driver-specific Packet Traps ============================ @@ -486,6 +490,10 @@ narrow. The description of these groups must be added to the following table: - Contains packet traps for packets that should be locally delivered after routing, but do not match more specific packet traps (e.g., ``ipv4_bgp``) + * - ``external_delivery`` + - Contains packet traps for packets that should be routed through an + external interface (e.g., management interface) that does not belong to + the same device (e.g., switch ASIC) as the ingress interface * - ``ipv6`` - Contains packet traps for various IPv6 control packets (e.g., Router Advertisements) diff --git a/Documentation/networking/devlink/ice.rst b/Documentation/networking/devlink/ice.rst index 72ea8d295724..237848d56f9b 100644 --- a/Documentation/networking/devlink/ice.rst +++ b/Documentation/networking/devlink/ice.rst @@ -84,8 +84,20 @@ The ``ice`` driver reports the following versions Regions ======= -The ``ice`` driver enables access to the contents of the Non Volatile Memory -flash chip via the ``nvm-flash`` region. +The ``ice`` driver implements the following regions for accessing internal +device data. + +.. list-table:: regions implemented + :widths: 15 85 + + * - Name + - Description + * - ``nvm-flash`` + - The contents of the entire flash chip, sometimes referred to as + the device's Non Volatile Memory. + * - ``device-caps`` + - The contents of the device firmware's capabilities buffer. Useful to + determine the current state and configuration of the device. Users can request an immediate capture of a snapshot via the ``DEVLINK_CMD_REGION_NEW`` @@ -105,3 +117,42 @@ Users can request an immediate capture of a snapshot via the 0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30 $ devlink region delete pci/0000:01:00.0/nvm-flash snapshot 1 + + $ devlink region new pci/0000:01:00.0/device-caps snapshot 1 + $ devlink region dump pci/0000:01:00.0/device-caps snapshot 1 + 0000000000000000 01 00 01 00 00 00 00 00 01 00 00 00 00 00 00 00 + 0000000000000010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 0000000000000020 02 00 02 01 32 03 00 00 0a 00 00 00 25 00 00 00 + 0000000000000030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 0000000000000040 04 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00 + 0000000000000050 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 0000000000000060 05 00 01 00 03 00 00 00 00 00 00 00 00 00 00 00 + 0000000000000070 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 0000000000000080 06 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00 + 0000000000000090 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 00000000000000a0 08 00 01 00 00 00 00 00 00 00 00 00 00 00 00 00 + 00000000000000b0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 00000000000000c0 12 00 01 00 01 00 00 00 01 00 01 00 00 00 00 00 + 00000000000000d0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 00000000000000e0 13 00 01 00 00 01 00 00 00 00 00 00 00 00 00 00 + 00000000000000f0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 0000000000000100 14 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00 + 0000000000000110 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 0000000000000120 15 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00 + 0000000000000130 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 0000000000000140 16 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00 + 0000000000000150 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 0000000000000160 17 00 01 00 06 00 00 00 00 00 00 00 00 00 00 00 + 0000000000000170 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 0000000000000180 18 00 01 00 01 00 00 00 01 00 00 00 08 00 00 00 + 0000000000000190 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 00000000000001a0 22 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00 + 00000000000001b0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 00000000000001c0 40 00 01 00 00 08 00 00 08 00 00 00 00 00 00 00 + 00000000000001d0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 00000000000001e0 41 00 01 00 00 08 00 00 00 00 00 00 00 00 00 00 + 00000000000001f0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 0000000000000200 42 00 01 00 00 08 00 00 00 00 00 00 00 00 00 00 + 0000000000000210 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + + $ devlink region delete pci/0000:01:00.0/device-caps snapshot 1 diff --git a/Documentation/networking/dsa/dsa.rst b/Documentation/networking/dsa/dsa.rst index 563d56c6a25c..a8d15dd2b42b 100644 --- a/Documentation/networking/dsa/dsa.rst +++ b/Documentation/networking/dsa/dsa.rst @@ -95,7 +95,7 @@ Ethernet switch. Networking stack hooks ---------------------- -When a master netdev is used with DSA, a small hook is placed in in the +When a master netdev is used with DSA, a small hook is placed in the networking stack is in order to have the DSA subsystem process the Ethernet switch specific tagging protocol. DSA accomplishes this by registering a specific (and fake) Ethernet type (later becoming ``skb->protocol``) with the diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst index 82470c36c27a..d53bcb31645a 100644 --- a/Documentation/networking/ethtool-netlink.rst +++ b/Documentation/networking/ethtool-netlink.rst @@ -443,10 +443,11 @@ supports. LINKSTATE_GET ============= -Requests link state information. At the moment, only link up/down flag (as -provided by ``ETHTOOL_GLINK`` ioctl command) is provided but some future -extensions are planned (e.g. link down reason). This request does not have any -attributes. +Requests link state information. Link up/down flag (as provided by +``ETHTOOL_GLINK`` ioctl command) is provided. Optionally, extended state might +be provided as well. In general, extended state describes reasons for why a port +is down, or why it operates in some non-obvious mode. This request does not have +any attributes. Request contents: @@ -461,16 +462,135 @@ Kernel response contents: ``ETHTOOL_A_LINKSTATE_LINK`` bool link state (up/down) ``ETHTOOL_A_LINKSTATE_SQI`` u32 Current Signal Quality Index ``ETHTOOL_A_LINKSTATE_SQI_MAX`` u32 Max support SQI value + ``ETHTOOL_A_LINKSTATE_EXT_STATE`` u8 link extended state + ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE`` u8 link extended substate ==================================== ====== ============================ For most NIC drivers, the value of ``ETHTOOL_A_LINKSTATE_LINK`` returns carrier flag provided by ``netif_carrier_ok()`` but there are drivers which define their own handler. +``ETHTOOL_A_LINKSTATE_EXT_STATE`` and ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE`` are +optional values. ethtool core can provide either both +``ETHTOOL_A_LINKSTATE_EXT_STATE`` and ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE``, +or only ``ETHTOOL_A_LINKSTATE_EXT_STATE``, or none of them. + ``LINKSTATE_GET`` allows dump requests (kernel returns reply messages for all devices supporting the request). +Link extended states: + + ================================================ ============================================ + ``ETHTOOL_LINK_EXT_STATE_AUTONEG`` States relating to the autonegotiation or + issues therein + + ``ETHTOOL_LINK_EXT_STATE_LINK_TRAINING_FAILURE`` Failure during link training + + ``ETHTOOL_LINK_EXT_STATE_LINK_LOGICAL_MISMATCH`` Logical mismatch in physical coding sublayer + or forward error correction sublayer + + ``ETHTOOL_LINK_EXT_STATE_BAD_SIGNAL_INTEGRITY`` Signal integrity issues + + ``ETHTOOL_LINK_EXT_STATE_NO_CABLE`` No cable connected + + ``ETHTOOL_LINK_EXT_STATE_CABLE_ISSUE`` Failure is related to cable, + e.g., unsupported cable + + ``ETHTOOL_LINK_EXT_STATE_EEPROM_ISSUE`` Failure is related to EEPROM, e.g., failure + during reading or parsing the data + + ``ETHTOOL_LINK_EXT_STATE_CALIBRATION_FAILURE`` Failure during calibration algorithm + + ``ETHTOOL_LINK_EXT_STATE_POWER_BUDGET_EXCEEDED`` The hardware is not able to provide the + power required from cable or module + + ``ETHTOOL_LINK_EXT_STATE_OVERHEAT`` The module is overheated + ================================================ ============================================ + +Link extended substates: + + Autoneg substates: + + =============================================================== ================================ + ``ETHTOOL_LINK_EXT_SUBSTATE_AN_NO_PARTNER_DETECTED`` Peer side is down + + ``ETHTOOL_LINK_EXT_SUBSTATE_AN_ACK_NOT_RECEIVED`` Ack not received from peer side + + ``ETHTOOL_LINK_EXT_SUBSTATE_AN_NEXT_PAGE_EXCHANGE_FAILED`` Next page exchange failed + + ``ETHTOOL_LINK_EXT_SUBSTATE_AN_NO_PARTNER_DETECTED_FORCE_MODE`` Peer side is down during force + mode or there is no agreement of + speed + + ``ETHTOOL_LINK_EXT_SUBSTATE_AN_FEC_MISMATCH_DURING_OVERRIDE`` Forward error correction modes + in both sides are mismatched + + ``ETHTOOL_LINK_EXT_SUBSTATE_AN_NO_HCD`` No Highest Common Denominator + =============================================================== ================================ + + Link training substates: + + =========================================================================== ==================== + ``ETHTOOL_LINK_EXT_SUBSTATE_LT_KR_FRAME_LOCK_NOT_ACQUIRED`` Frames were not + recognized, the + lock failed + + ``ETHTOOL_LINK_EXT_SUBSTATE_LT_KR_LINK_INHIBIT_TIMEOUT`` The lock did not + occur before + timeout + + ``ETHTOOL_LINK_EXT_SUBSTATE_LT_KR_LINK_PARTNER_DID_NOT_SET_RECEIVER_READY`` Peer side did not + send ready signal + after training + process + + ``ETHTOOL_LINK_EXT_SUBSTATE_LT_REMOTE_FAULT`` Remote side is not + ready yet + =========================================================================== ==================== + + Link logical mismatch substates: + + ================================================================ =============================== + ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_PCS_DID_NOT_ACQUIRE_BLOCK_LOCK`` Physical coding sublayer was + not locked in first phase - + block lock + + ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_PCS_DID_NOT_ACQUIRE_AM_LOCK`` Physical coding sublayer was + not locked in second phase - + alignment markers lock + + ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_PCS_DID_NOT_GET_ALIGN_STATUS`` Physical coding sublayer did + not get align status + + ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_FC_FEC_IS_NOT_LOCKED`` FC forward error correction is + not locked + + ``ETHTOOL_LINK_EXT_SUBSTATE_LLM_RS_FEC_IS_NOT_LOCKED`` RS forward error correction is + not locked + ================================================================ =============================== + + Bad signal integrity substates: + + ================================================================= ============================= + ``ETHTOOL_LINK_EXT_SUBSTATE_BSI_LARGE_NUMBER_OF_PHYSICAL_ERRORS`` Large number of physical + errors + + ``ETHTOOL_LINK_EXT_SUBSTATE_BSI_UNSUPPORTED_RATE`` The system attempted to + operate the cable at a rate + that is not formally + supported, which led to + signal integrity issues + ================================================================= ============================= + + Cable issue substates: + + =================================================== ============================================ + ``ETHTOOL_LINK_EXT_SUBSTATE_CI_UNSUPPORTED_CABLE`` Unsupported cable + + ``ETHTOOL_LINK_EXT_SUBSTATE_CI_CABLE_TEST_FAILURE`` Cable test failure + =================================================== ============================================ + DEBUG_GET ========= @@ -1110,6 +1230,42 @@ used to report the amplitude of the reflection for a given pair. | | | ``ETHTOOL_A_CABLE_AMPLITUDE_mV`` | s16 | Reflection amplitude | +-+-+-----------------------------------------+--------+----------------------+ +TUNNEL_INFO +=========== + +Gets information about the tunnel state NIC is aware of. + +Request contents: + + ===================================== ====== ========================== + ``ETHTOOL_A_TUNNEL_INFO_HEADER`` nested request header + ===================================== ====== ========================== + +Kernel response contents: + + +---------------------------------------------+--------+---------------------+ + | ``ETHTOOL_A_TUNNEL_INFO_HEADER`` | nested | reply header | + +---------------------------------------------+--------+---------------------+ + | ``ETHTOOL_A_TUNNEL_INFO_UDP_PORTS`` | nested | all UDP port tables | + +-+-------------------------------------------+--------+---------------------+ + | | ``ETHTOOL_A_TUNNEL_UDP_TABLE`` | nested | one UDP port table | + +-+-+-----------------------------------------+--------+---------------------+ + | | | ``ETHTOOL_A_TUNNEL_UDP_TABLE_SIZE`` | u32 | max size of the | + | | | | | table | + +-+-+-----------------------------------------+--------+---------------------+ + | | | ``ETHTOOL_A_TUNNEL_UDP_TABLE_TYPES`` | bitset | tunnel types which | + | | | | | table can hold | + +-+-+-----------------------------------------+--------+---------------------+ + | | | ``ETHTOOL_A_TUNNEL_UDP_TABLE_ENTRY`` | nested | offloaded UDP port | + +-+-+-+---------------------------------------+--------+---------------------+ + | | | | ``ETHTOOL_A_TUNNEL_UDP_ENTRY_PORT`` | be16 | UDP port | + +-+-+-+---------------------------------------+--------+---------------------+ + | | | | ``ETHTOOL_A_TUNNEL_UDP_ENTRY_TYPE`` | u32 | tunnel type | + +-+-+-+---------------------------------------+--------+---------------------+ + +For UDP tunnel table empty ``ETHTOOL_A_TUNNEL_UDP_TABLE_TYPES`` indicates that +the table contains static entries, hard-coded by the NIC. + Request translation =================== diff --git a/Documentation/networking/filter.rst b/Documentation/networking/filter.rst index a1d3e192b9fa..debb59e374de 100644 --- a/Documentation/networking/filter.rst +++ b/Documentation/networking/filter.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 +.. _networking-filter: + ======================================================= Linux Socket Filtering aka Berkeley Packet Filter (BPF) ======================================================= diff --git a/Documentation/networking/ieee802154.rst b/Documentation/networking/ieee802154.rst index 36ca823a1122..6f4bf8447a21 100644 --- a/Documentation/networking/ieee802154.rst +++ b/Documentation/networking/ieee802154.rst @@ -30,8 +30,8 @@ Socket API The address family, socket addresses etc. are defined in the include/net/af_ieee802154.h header or in the special header -in the userspace package (see either http://wpan.cakelab.org/ or the -git tree at https://github.com/linux-wpan/wpan-tools). +in the userspace package (see either https://linux-wpan.org/wpan-tools.html +or the git tree at https://github.com/linux-wpan/wpan-tools). 6LoWPAN Linux implementation ============================ diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 0186e276690a..c29496fff81c 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -20,7 +20,6 @@ Contents: ieee802154 j1939 kapi - z8530book msg_zerocopy failover net_dim @@ -39,36 +38,28 @@ Contents: nfc 6lowpan 6pack - altera_tse arcnet-hardware arcnet atm ax25 - baycom bonding cdc_mbim - cops - cxacru dccp dctcp decnet - defza dns_resolver driver eql fib_trie filter - fore200e framerelay generic-hdlc generic_netlink gen_stats gtp - hinic ila ipddp ip_dynaddr - iphase ipsec ip-sysctl ipv6 @@ -77,7 +68,6 @@ Contents: kcm l2tp lapb-module - ltpc mac80211-injection mpls-sysctl multiqueue @@ -97,14 +87,12 @@ Contents: ppp_generic proc_net_tcp radiotap-headers - ray_cs rds regulatory rxrpc sctp secid seg6-sysctl - skfp strparser switchdev tc-actions-env-rules @@ -122,7 +110,6 @@ Contents: xfrm_proc xfrm_sync xfrm_sysctl - z8530drv .. only:: subproject and html diff --git a/Documentation/networking/ip-sysctl.rst b/Documentation/networking/ip-sysctl.rst index b72f89d5694c..837d51f9e1fa 100644 --- a/Documentation/networking/ip-sysctl.rst +++ b/Documentation/networking/ip-sysctl.rst @@ -741,7 +741,7 @@ tcp_fastopen - INTEGER Default: 0x1 - Note that that additional client or server features are only + Note that additional client or server features are only effective if the basic support (0x1 and 0x2) are enabled respectively. tcp_fastopen_blackhole_timeout_sec - INTEGER diff --git a/Documentation/networking/ipvs-sysctl.rst b/Documentation/networking/ipvs-sysctl.rst index be36c4600e8f..2afccc63856e 100644 --- a/Documentation/networking/ipvs-sysctl.rst +++ b/Documentation/networking/ipvs-sysctl.rst @@ -114,7 +114,7 @@ drop_entry - INTEGER modes (when there is no enough available memory, the strategy is enabled and the variable is automatically set to 2, otherwise the strategy is disabled and the variable is set to - 1), and 3 means that that the strategy is always enabled. + 1), and 3 means that the strategy is always enabled. drop_packet - INTEGER - 0 - disabled (default) diff --git a/Documentation/networking/rxrpc.rst b/Documentation/networking/rxrpc.rst index 68552b92dc44..39c2249c7aa7 100644 --- a/Documentation/networking/rxrpc.rst +++ b/Documentation/networking/rxrpc.rst @@ -186,7 +186,7 @@ About the AF_RXRPC driver: time [tunable] after the last connection using it discarded, in case a new connection is made that could use it. - (#) A client-side connection is only shared between calls if they have have + (#) A client-side connection is only shared between calls if they have the same key struct describing their security (and assuming the calls would otherwise share the connection). Non-secured calls would also be able to share connections with each other. diff --git a/Documentation/networking/timestamping.rst b/Documentation/networking/timestamping.rst index 1adead6a4527..03f7beade470 100644 --- a/Documentation/networking/timestamping.rst +++ b/Documentation/networking/timestamping.rst @@ -589,3 +589,168 @@ Time stamps for outgoing packets are to be generated as follows: this would occur at a later time in the processing pipeline than other software time stamping and therefore could lead to unexpected deltas between time stamps. + +3.2 Special considerations for stacked PTP Hardware Clocks +---------------------------------------------------------- + +There are situations when there may be more than one PHC (PTP Hardware Clock) +in the data path of a packet. The kernel has no explicit mechanism to allow the +user to select which PHC to use for timestamping Ethernet frames. Instead, the +assumption is that the outermost PHC is always the most preferable, and that +kernel drivers collaborate towards achieving that goal. Currently there are 3 +cases of stacked PHCs, detailed below: + +3.2.1 DSA (Distributed Switch Architecture) switches +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +These are Ethernet switches which have one of their ports connected to an +(otherwise completely unaware) host Ethernet interface, and perform the role of +a port multiplier with optional forwarding acceleration features. Each DSA +switch port is visible to the user as a standalone (virtual) network interface, +and its network I/O is performed, under the hood, indirectly through the host +interface (redirecting to the host port on TX, and intercepting frames on RX). + +When a DSA switch is attached to a host port, PTP synchronization has to +suffer, since the switch's variable queuing delay introduces a path delay +jitter between the host port and its PTP partner. For this reason, some DSA +switches include a timestamping clock of their own, and have the ability to +perform network timestamping on their own MAC, such that path delays only +measure wire and PHY propagation latencies. Timestamping DSA switches are +supported in Linux and expose the same ABI as any other network interface (save +for the fact that the DSA interfaces are in fact virtual in terms of network +I/O, they do have their own PHC). It is typical, but not mandatory, for all +interfaces of a DSA switch to share the same PHC. + +By design, PTP timestamping with a DSA switch does not need any special +handling in the driver for the host port it is attached to. However, when the +host port also supports PTP timestamping, DSA will take care of intercepting +the ``.ndo_do_ioctl`` calls towards the host port, and block attempts to enable +hardware timestamping on it. This is because the SO_TIMESTAMPING API does not +allow the delivery of multiple hardware timestamps for the same packet, so +anybody else except for the DSA switch port must be prevented from doing so. + +In code, DSA provides for most of the infrastructure for timestamping already, +in generic code: a BPF classifier (``ptp_classify_raw``) is used to identify +PTP event messages (any other packets, including PTP general messages, are not +timestamped), and provides two hooks to drivers: + +- ``.port_txtstamp()``: The driver is passed a clone of the timestampable skb + to be transmitted, before actually transmitting it. Typically, a switch will + have a PTP TX timestamp register (or sometimes a FIFO) where the timestamp + becomes available. There may be an IRQ that is raised upon this timestamp's + availability, or the driver might have to poll after invoking + ``dev_queue_xmit()`` towards the host interface. Either way, in the + ``.port_txtstamp()`` method, the driver only needs to save the clone for + later use (when the timestamp becomes available). Each skb is annotated with + a pointer to its clone, in ``DSA_SKB_CB(skb)->clone``, to ease the driver's + job of keeping track of which clone belongs to which skb. + +- ``.port_rxtstamp()``: The original (and only) timestampable skb is provided + to the driver, for it to annotate it with a timestamp, if that is immediately + available, or defer to later. On reception, timestamps might either be + available in-band (through metadata in the DSA header, or attached in other + ways to the packet), or out-of-band (through another RX timestamping FIFO). + Deferral on RX is typically necessary when retrieving the timestamp needs a + sleepable context. In that case, it is the responsibility of the DSA driver + to call ``netif_rx_ni()`` on the freshly timestamped skb. + +3.2.2 Ethernet PHYs +^^^^^^^^^^^^^^^^^^^ + +These are devices that typically fulfill a Layer 1 role in the network stack, +hence they do not have a representation in terms of a network interface as DSA +switches do. However, PHYs may be able to detect and timestamp PTP packets, for +performance reasons: timestamps taken as close as possible to the wire have the +potential to yield a more stable and precise synchronization. + +A PHY driver that supports PTP timestamping must create a ``struct +mii_timestamper`` and add a pointer to it in ``phydev->mii_ts``. The presence +of this pointer will be checked by the networking stack. + +Since PHYs do not have network interface representations, the timestamping and +ethtool ioctl operations for them need to be mediated by their respective MAC +driver. Therefore, as opposed to DSA switches, modifications need to be done +to each individual MAC driver for PHY timestamping support. This entails: + +- Checking, in ``.ndo_do_ioctl``, whether ``phy_has_hwtstamp(netdev->phydev)`` + is true or not. If it is, then the MAC driver should not process this request + but instead pass it on to the PHY using ``phy_mii_ioctl()``. + +- On RX, special intervention may or may not be needed, depending on the + function used to deliver skb's up the network stack. In the case of plain + ``netif_rx()`` and similar, MAC drivers must check whether + ``skb_defer_rx_timestamp(skb)`` is necessary or not - and if it is, don't + call ``netif_rx()`` at all. If ``CONFIG_NETWORK_PHY_TIMESTAMPING`` is + enabled, and ``skb->dev->phydev->mii_ts`` exists, its ``.rxtstamp()`` hook + will be called now, to determine, using logic very similar to DSA, whether + deferral for RX timestamping is necessary. Again like DSA, it becomes the + responsibility of the PHY driver to send the packet up the stack when the + timestamp is available. + + For other skb receive functions, such as ``napi_gro_receive`` and + ``netif_receive_skb``, the stack automatically checks whether + ``skb_defer_rx_timestamp()`` is necessary, so this check is not needed inside + the driver. + +- On TX, again, special intervention might or might not be needed. The + function that calls the ``mii_ts->txtstamp()`` hook is named + ``skb_clone_tx_timestamp()``. This function can either be called directly + (case in which explicit MAC driver support is indeed needed), but the + function also piggybacks from the ``skb_tx_timestamp()`` call, which many MAC + drivers already perform for software timestamping purposes. Therefore, if a + MAC supports software timestamping, it does not need to do anything further + at this stage. + +3.2.3 MII bus snooping devices +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +These perform the same role as timestamping Ethernet PHYs, save for the fact +that they are discrete devices and can therefore be used in conjunction with +any PHY even if it doesn't support timestamping. In Linux, they are +discoverable and attachable to a ``struct phy_device`` through Device Tree, and +for the rest, they use the same mii_ts infrastructure as those. See +Documentation/devicetree/bindings/ptp/timestamper.txt for more details. + +3.2.4 Other caveats for MAC drivers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Stacked PHCs, especially DSA (but not only) - since that doesn't require any +modification to MAC drivers, so it is more difficult to ensure correctness of +all possible code paths - is that they uncover bugs which were impossible to +trigger before the existence of stacked PTP clocks. One example has to do with +this line of code, already presented earlier:: + + skb_shinfo(skb)->tx_flags |= SKBTX_IN_PROGRESS; + +Any TX timestamping logic, be it a plain MAC driver, a DSA switch driver, a PHY +driver or a MII bus snooping device driver, should set this flag. +But a MAC driver that is unaware of PHC stacking might get tripped up by +somebody other than itself setting this flag, and deliver a duplicate +timestamp. +For example, a typical driver design for TX timestamping might be to split the +transmission part into 2 portions: + +1. "TX": checks whether PTP timestamping has been previously enabled through + the ``.ndo_do_ioctl`` ("``priv->hwtstamp_tx_enabled == true``") and the + current skb requires a TX timestamp ("``skb_shinfo(skb)->tx_flags & + SKBTX_HW_TSTAMP``"). If this is true, it sets the + "``skb_shinfo(skb)->tx_flags |= SKBTX_IN_PROGRESS``" flag. Note: as + described above, in the case of a stacked PHC system, this condition should + never trigger, as this MAC is certainly not the outermost PHC. But this is + not where the typical issue is. Transmission proceeds with this packet. + +2. "TX confirmation": Transmission has finished. The driver checks whether it + is necessary to collect any TX timestamp for it. Here is where the typical + issues are: the MAC driver takes a shortcut and only checks whether + "``skb_shinfo(skb)->tx_flags & SKBTX_IN_PROGRESS``" was set. With a stacked + PHC system, this is incorrect because this MAC driver is not the only entity + in the TX data path who could have enabled SKBTX_IN_PROGRESS in the first + place. + +The correct solution for this problem is for MAC drivers to have a compound +check in their "TX confirmation" portion, not only for +"``skb_shinfo(skb)->tx_flags & SKBTX_IN_PROGRESS``", but also for +"``priv->hwtstamp_tx_enabled == true``". Because the rest of the system ensures +that PTP timestamping is not enabled for anything other than the outermost PHC, +this enhanced check will avoid delivering a duplicated TX timestamp to user +space. diff --git a/Documentation/networking/tls-offload.rst b/Documentation/networking/tls-offload.rst index f914e81fd3a6..37773da2bee5 100644 --- a/Documentation/networking/tls-offload.rst +++ b/Documentation/networking/tls-offload.rst @@ -428,6 +428,24 @@ by the driver: which were part of a TLS stream. * ``rx_tls_decrypted_bytes`` - number of TLS payload bytes in RX packets which were successfully decrypted. + * ``rx_tls_ctx`` - number of TLS RX HW offload contexts added to device for + decryption. + * ``rx_tls_del`` - number of TLS RX HW offload contexts deleted from device + (connection has finished). + * ``rx_tls_resync_req_pkt`` - number of received TLS packets with a resync + request. + * ``rx_tls_resync_req_start`` - number of times the TLS async resync request + was started. + * ``rx_tls_resync_req_end`` - number of times the TLS async resync request + properly ended with providing the HW tracked tcp-seq. + * ``rx_tls_resync_req_skip`` - number of times the TLS async resync request + procedure was started by not properly ended. + * ``rx_tls_resync_res_ok`` - number of times the TLS resync response call to + the driver was successfully handled. + * ``rx_tls_resync_res_skip`` - number of times the TLS resync response call to + the driver was terminated unsuccessfully. + * ``rx_tls_err`` - number of RX packets which were part of a TLS stream + but were not decrypted due to unexpected error in the state machine. * ``tx_tls_encrypted_packets`` - number of TX packets passed to the device for encryption of their TLS payload. * ``tx_tls_encrypted_bytes`` - number of TLS payload bytes in TX packets diff --git a/Documentation/openrisc/openrisc_port.rst b/Documentation/openrisc/openrisc_port.rst index 4b2c437942a0..657ac4af7be6 100644 --- a/Documentation/openrisc/openrisc_port.rst +++ b/Documentation/openrisc/openrisc_port.rst @@ -8,7 +8,7 @@ target architecture, specifically, is the 32-bit OpenRISC 1000 family (or1k). For information about OpenRISC processors and ongoing development: ======= ============================= - website http://openrisc.io + website https://openrisc.io email openrisc@lists.librecores.org ======= ============================= diff --git a/Documentation/power/energy-model.rst b/Documentation/power/energy-model.rst index 90a345d57ae9..a6fb986abe3c 100644 --- a/Documentation/power/energy-model.rst +++ b/Documentation/power/energy-model.rst @@ -1,15 +1,17 @@ -==================== -Energy Model of CPUs -==================== +.. SPDX-License-Identifier: GPL-2.0 + +======================= +Energy Model of devices +======================= 1. Overview ----------- The Energy Model (EM) framework serves as an interface between drivers knowing -the power consumed by CPUs at various performance levels, and the kernel +the power consumed by devices at various performance levels, and the kernel subsystems willing to use that information to make energy-aware decisions. -The source of the information about the power consumed by CPUs can vary greatly +The source of the information about the power consumed by devices can vary greatly from one platform to another. These power costs can be estimated using devicetree data in some cases. In others, the firmware will know better. Alternatively, userspace might be best positioned. And so on. In order to avoid @@ -25,7 +27,7 @@ framework, and interested clients reading the data from it:: +---------------+ +-----------------+ +---------------+ | Thermal (IPA) | | Scheduler (EAS) | | Other | +---------------+ +-----------------+ +---------------+ - | | em_pd_energy() | + | | em_cpu_energy() | | | em_cpu_get() | +---------+ | +---------+ | | | @@ -35,7 +37,7 @@ framework, and interested clients reading the data from it:: | Framework | +---------------------+ ^ ^ ^ - | | | em_register_perf_domain() + | | | em_dev_register_perf_domain() +----------+ | +---------+ | | | +---------------+ +---------------+ +--------------+ @@ -47,12 +49,12 @@ framework, and interested clients reading the data from it:: | Device Tree | | Firmware | | ? | +--------------+ +---------------+ +--------------+ -The EM framework manages power cost tables per 'performance domain' in the -system. A performance domain is a group of CPUs whose performance is scaled -together. Performance domains generally have a 1-to-1 mapping with CPUFreq -policies. All CPUs in a performance domain are required to have the same -micro-architecture. CPUs in different performance domains can have different -micro-architectures. +In case of CPU devices the EM framework manages power cost tables per +'performance domain' in the system. A performance domain is a group of CPUs +whose performance is scaled together. Performance domains generally have a +1-to-1 mapping with CPUFreq policies. All CPUs in a performance domain are +required to have the same micro-architecture. CPUs in different performance +domains can have different micro-architectures. 2. Core APIs @@ -70,14 +72,16 @@ CONFIG_ENERGY_MODEL must be enabled to use the EM framework. Drivers are expected to register performance domains into the EM framework by calling the following API:: - int em_register_perf_domain(cpumask_t *span, unsigned int nr_states, - struct em_data_callback *cb); + int em_dev_register_perf_domain(struct device *dev, unsigned int nr_states, + struct em_data_callback *cb, cpumask_t *cpus); -Drivers must specify the CPUs of the performance domains using the cpumask -argument, and provide a callback function returning <frequency, power> tuples -for each capacity state. The callback function provided by the driver is free +Drivers must provide a callback function returning <frequency, power> tuples +for each performance state. The callback function provided by the driver is free to fetch data from any relevant location (DT, firmware, ...), and by any mean -deemed necessary. See Section 3. for an example of driver implementing this +deemed necessary. Only for CPU devices, drivers must specify the CPUs of the +performance domains using cpumask. For other devices than CPUs the last +argument must be set to NULL. +See Section 3. for an example of driver implementing this callback, and kernel/power/energy_model.c for further documentation on this API. @@ -85,13 +89,20 @@ API. 2.3 Accessing performance domains ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +There are two API functions which provide the access to the energy model: +em_cpu_get() which takes CPU id as an argument and em_pd_get() with device +pointer as an argument. It depends on the subsystem which interface it is +going to use, but in case of CPU devices both functions return the same +performance domain. + Subsystems interested in the energy model of a CPU can retrieve it using the em_cpu_get() API. The energy model tables are allocated once upon creation of the performance domains, and kept in memory untouched. The energy consumed by a performance domain can be estimated using the -em_pd_energy() API. The estimation is performed assuming that the schedutil -CPUfreq governor is in use. +em_cpu_energy() API. The estimation is performed assuming that the schedutil +CPUfreq governor is in use in case of CPU device. Currently this calculation is +not provided for other type of devices. More details about the above APIs can be found in include/linux/energy_model.h. @@ -106,42 +117,46 @@ EM framework:: -> drivers/cpufreq/foo_cpufreq.c - 01 static int est_power(unsigned long *mW, unsigned long *KHz, int cpu) - 02 { - 03 long freq, power; - 04 - 05 /* Use the 'foo' protocol to ceil the frequency */ - 06 freq = foo_get_freq_ceil(cpu, *KHz); - 07 if (freq < 0); - 08 return freq; - 09 - 10 /* Estimate the power cost for the CPU at the relevant freq. */ - 11 power = foo_estimate_power(cpu, freq); - 12 if (power < 0); - 13 return power; - 14 - 15 /* Return the values to the EM framework */ - 16 *mW = power; - 17 *KHz = freq; - 18 - 19 return 0; - 20 } - 21 - 22 static int foo_cpufreq_init(struct cpufreq_policy *policy) - 23 { - 24 struct em_data_callback em_cb = EM_DATA_CB(est_power); - 25 int nr_opp, ret; - 26 - 27 /* Do the actual CPUFreq init work ... */ - 28 ret = do_foo_cpufreq_init(policy); - 29 if (ret) - 30 return ret; - 31 - 32 /* Find the number of OPPs for this policy */ - 33 nr_opp = foo_get_nr_opp(policy); - 34 - 35 /* And register the new performance domain */ - 36 em_register_perf_domain(policy->cpus, nr_opp, &em_cb); - 37 - 38 return 0; - 39 } + 01 static int est_power(unsigned long *mW, unsigned long *KHz, + 02 struct device *dev) + 03 { + 04 long freq, power; + 05 + 06 /* Use the 'foo' protocol to ceil the frequency */ + 07 freq = foo_get_freq_ceil(dev, *KHz); + 08 if (freq < 0); + 09 return freq; + 10 + 11 /* Estimate the power cost for the dev at the relevant freq. */ + 12 power = foo_estimate_power(dev, freq); + 13 if (power < 0); + 14 return power; + 15 + 16 /* Return the values to the EM framework */ + 17 *mW = power; + 18 *KHz = freq; + 19 + 20 return 0; + 21 } + 22 + 23 static int foo_cpufreq_init(struct cpufreq_policy *policy) + 24 { + 25 struct em_data_callback em_cb = EM_DATA_CB(est_power); + 26 struct device *cpu_dev; + 27 int nr_opp, ret; + 28 + 29 cpu_dev = get_cpu_device(cpumask_first(policy->cpus)); + 30 + 31 /* Do the actual CPUFreq init work ... */ + 32 ret = do_foo_cpufreq_init(policy); + 33 if (ret) + 34 return ret; + 35 + 36 /* Find the number of OPPs for this policy */ + 37 nr_opp = foo_get_nr_opp(policy); + 38 + 39 /* And register the new performance domain */ + 40 em_dev_register_perf_domain(cpu_dev, nr_opp, &em_cb, policy->cpus); + 41 + 42 return 0; + 43 } diff --git a/Documentation/power/powercap/powercap.rst b/Documentation/power/powercap/powercap.rst index 7ae3b44c7624..e75d12596dac 100644 --- a/Documentation/power/powercap/powercap.rst +++ b/Documentation/power/powercap/powercap.rst @@ -167,11 +167,13 @@ For example:: package-0 --------- -The Intel RAPL technology allows two constraints, short term and long term, -with two different time windows to be applied to each power zone. Thus for -each zone there are 2 attributes representing the constraint names, 2 power -limits and 2 attributes representing the sizes of the time windows. Such that, -constraint_j_* attributes correspond to the jth constraint (j = 0,1). +Depending on different power zones, the Intel RAPL technology allows +one or multiple constraints like short term, long term and peak power, +with different time windows to be applied to each power zone. +All the zones contain attributes representing the constraint names, +power limits and the sizes of the time windows. Note that time window +is not applicable to peak power. Here, constraint_j_* attributes +correspond to the jth constraint (j = 0,1,2). For example:: @@ -181,6 +183,9 @@ For example:: constraint_1_name constraint_1_power_limit_uw constraint_1_time_window_us + constraint_2_name + constraint_2_power_limit_uw + constraint_2_time_window_us Power Zone Attributes ===================== diff --git a/Documentation/powerpc/cpu_families.rst b/Documentation/powerpc/cpu_families.rst index 1e063c5440c3..9b84e045e713 100644 --- a/Documentation/powerpc/cpu_families.rst +++ b/Documentation/powerpc/cpu_families.rst @@ -9,7 +9,9 @@ and are supported by arch/powerpc. Book3S (aka sPAPR) ------------------ -- Hash MMU +- Hash MMU (except 603 and e300) +- Software loaded TLB (603 and e300) +- Selectable Software loaded TLB in addition to hash MMU (755, 7450, e600) - Mix of 32 & 64 bit:: +--------------+ +----------------+ @@ -24,9 +26,9 @@ Book3S (aka sPAPR) | | | | v v - +--------------+ +----------------+ +-------+ - | 604 | | 750 (G3) | ---> | 750CX | - +--------------+ +----------------+ +-------+ + +--------------+ +-----+ +----------------+ +-------+ + | 604 | | 755 | <--- | 750 (G3) | ---> | 750CX | + +--------------+ +-----+ +----------------+ +-------+ | | | | | | v v v diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst index afe2d5e54db6..748bf483b1c2 100644 --- a/Documentation/powerpc/index.rst +++ b/Documentation/powerpc/index.rst @@ -31,6 +31,7 @@ powerpc transactional_memory ultravisor vas-api + vcpudispatch_stats .. only:: subproject and html diff --git a/Documentation/powerpc/mpc52xx.rst b/Documentation/powerpc/mpc52xx.rst index 8676ac63e077..30260707c3fe 100644 --- a/Documentation/powerpc/mpc52xx.rst +++ b/Documentation/powerpc/mpc52xx.rst @@ -2,7 +2,7 @@ Linux 2.6.x on MPC52xx family ============================= -For the latest info, go to http://www.246tNt.com/mpc52xx/ +For the latest info, go to https://www.246tNt.com/mpc52xx/ To compile/use : diff --git a/Documentation/powerpc/papr_hcalls.rst b/Documentation/powerpc/papr_hcalls.rst index 3493631a60f8..48fcf1255a33 100644 --- a/Documentation/powerpc/papr_hcalls.rst +++ b/Documentation/powerpc/papr_hcalls.rst @@ -220,13 +220,51 @@ from the LPAR memory. **H_SCM_HEALTH** | Input: drcIndex -| Out: *health-bitmap, health-bit-valid-bitmap* +| Out: *health-bitmap (r4), health-bit-valid-bitmap (r5)* | Return Value: *H_Success, H_Parameter, H_Hardware* Given a DRC Index return the info on predictive failure and overall health of -the NVDIMM. The asserted bits in the health-bitmap indicate a single predictive -failure and health-bit-valid-bitmap indicate which bits in health-bitmap are -valid. +the PMEM device. The asserted bits in the health-bitmap indicate one or more states +(described in table below) of the PMEM device and health-bit-valid-bitmap indicate +which bits in health-bitmap are valid. The bits are reported in +reverse bit ordering for example a value of 0xC400000000000000 +indicates bits 0, 1, and 5 are valid. + +Health Bitmap Flags: + ++------+-----------------------------------------------------------------------+ +| Bit | Definition | ++======+=======================================================================+ +| 00 | PMEM device is unable to persist memory contents. | +| | If the system is powered down, nothing will be saved. | ++------+-----------------------------------------------------------------------+ +| 01 | PMEM device failed to persist memory contents. Either contents were | +| | not saved successfully on power down or were not restored properly on | +| | power up. | ++------+-----------------------------------------------------------------------+ +| 02 | PMEM device contents are persisted from previous IPL. The data from | +| | the last boot were successfully restored. | ++------+-----------------------------------------------------------------------+ +| 03 | PMEM device contents are not persisted from previous IPL. There was no| +| | data to restore from the last boot. | ++------+-----------------------------------------------------------------------+ +| 04 | PMEM device memory life remaining is critically low | ++------+-----------------------------------------------------------------------+ +| 05 | PMEM device will be garded off next IPL due to failure | ++------+-----------------------------------------------------------------------+ +| 06 | PMEM device contents cannot persist due to current platform health | +| | status. A hardware failure may prevent data from being saved or | +| | restored. | ++------+-----------------------------------------------------------------------+ +| 07 | PMEM device is unable to persist memory contents in certain conditions| ++------+-----------------------------------------------------------------------+ +| 08 | PMEM device is encrypted | ++------+-----------------------------------------------------------------------+ +| 09 | PMEM device has successfully completed a requested erase or secure | +| | erase procedure. | ++------+-----------------------------------------------------------------------+ +|10:63 | Reserved / Unused | ++------+-----------------------------------------------------------------------+ **H_SCM_PERFORMANCE_STATS** diff --git a/Documentation/powerpc/syscall64-abi.rst b/Documentation/powerpc/syscall64-abi.rst index e49f69f941b9..46caaadbb029 100644 --- a/Documentation/powerpc/syscall64-abi.rst +++ b/Documentation/powerpc/syscall64-abi.rst @@ -5,6 +5,15 @@ Power Architecture 64-bit Linux system call ABI syscall ======= +Invocation +---------- +The syscall is made with the sc instruction, and returns with execution +continuing at the instruction following the sc instruction. + +If PPC_FEATURE2_SCV appears in the AT_HWCAP2 ELF auxiliary vector, the +scv 0 instruction is an alternative that may provide better performance, +with some differences to calling sequence. + syscall calling sequence\ [1]_ matches the Power Architecture 64-bit ELF ABI specification C function calling sequence, including register preservation rules, with the following differences. @@ -12,16 +21,23 @@ rules, with the following differences. .. [1] Some syscalls (typically low-level management functions) may have different calling sequences (e.g., rt_sigreturn). -Parameters and return value ---------------------------- +Parameters +---------- The system call number is specified in r0. There is a maximum of 6 integer parameters to a syscall, passed in r3-r8. -Both a return value and a return error code are returned. cr0.SO is the return -error code, and r3 is the return value or error code. When cr0.SO is clear, -the syscall succeeded and r3 is the return value. When cr0.SO is set, the -syscall failed and r3 is the error code that generally corresponds to errno. +Return value +------------ +- For the sc instruction, both a value and an error condition are returned. + cr0.SO is the error condition, and r3 is the return value. When cr0.SO is + clear, the syscall succeeded and r3 is the return value. When cr0.SO is set, + the syscall failed and r3 is the error value (that normally corresponds to + errno). + +- For the scv 0 instruction, the return value indicates failure if it is + -4095..-1 (i.e., it is >= -MAX_ERRNO (-4095) as an unsigned comparison), + in which case the error value is the negated return value. Stack ----- @@ -34,22 +50,23 @@ Register preservation rules match the ELF ABI calling sequence with the following differences: =========== ============= ======================================== +--- For the sc instruction, differences with the ELF ABI --- r0 Volatile (System call number.) r3 Volatile (Parameter 1, and return value.) r4-r8 Volatile (Parameters 2-6.) -cr0 Volatile (cr0.SO is the return error condition) +cr0 Volatile (cr0.SO is the return error condition.) cr1, cr5-7 Nonvolatile lr Nonvolatile + +--- For the scv 0 instruction, differences with the ELF ABI --- +r0 Volatile (System call number.) +r3 Volatile (Parameter 1, and return value.) +r4-r8 Volatile (Parameters 2-6.) =========== ============= ======================================== All floating point and vector data registers as well as control and status registers are nonvolatile. -Invocation ----------- -The syscall is performed with the sc instruction, and returns with execution -continuing at the instruction following the sc instruction. - Transactional Memory -------------------- Syscall behavior can change if the processor is in transactional or suspended @@ -75,6 +92,7 @@ auxiliary vector. returning to the caller. This case is not well defined or supported, so this behavior should not be relied upon. +scv 0 syscalls will always behave as PPC_FEATURE2_HTM_NOSC. vsyscall ======== diff --git a/Documentation/powerpc/vas-api.rst b/Documentation/powerpc/vas-api.rst index 1217c2f1595e..90c50ed839f3 100644 --- a/Documentation/powerpc/vas-api.rst +++ b/Documentation/powerpc/vas-api.rst @@ -43,7 +43,7 @@ engine for this process. Once a connection is established, the application should use the mmap() system call to map the hardware address of engine's request queue into the application's virtual address space. -The application can then submit one or more requests to the the engine by +The application can then submit one or more requests to the engine by using copy/paste instructions and pasting the CRBs to the virtual address (aka paste_address) returned by mmap(). User space can close the established connection or send window by closing the file descriptior @@ -87,6 +87,7 @@ Applications may chose a specific instance of the NX co-processor using the vas_id field in the VAS_TX_WIN_OPEN ioctl as detailed below. A userspace library libnxz is available here but still in development: + https://github.com/abalib/power-gzip Applications that use inflate / deflate calls can link with libnxz @@ -110,6 +111,7 @@ Applications should use the VAS_TX_WIN_OPEN ioctl as follows to establish a connection with NX co-processor engine: :: + struct vas_tx_win_open_attr { __u32 version; __s16 vas_id; /* specific instance of vas or -1 @@ -119,8 +121,10 @@ a connection with NX co-processor engine: __u64 reserved2[6]; }; - version: The version field must be currently set to 1. - vas_id: If '-1' is passed, kernel will make a best-effort attempt + version: + The version field must be currently set to 1. + vas_id: + If '-1' is passed, kernel will make a best-effort attempt to assign an optimal instance of NX for the process. To select the specific VAS instance, refer "Discovery of available VAS engines" section below. @@ -129,7 +133,8 @@ a connection with NX co-processor engine: and must be set to 0. The attributes attr for the VAS_TX_WIN_OPEN ioctl are defined as - follows: + follows:: + #define VAS_MAGIC 'v' #define VAS_TX_WIN_OPEN _IOW(VAS_MAGIC, 1, struct vas_tx_win_open_attr) @@ -141,6 +146,8 @@ a connection with NX co-processor engine: returns -1 and sets the errno variable to indicate the error. Error conditions: + + ====== ================================================ EINVAL fd does not refer to a valid VAS device. EINVAL Invalid vas ID EINVAL version is not set with proper value @@ -149,6 +156,7 @@ a connection with NX co-processor engine: ENOSPC System has too many active windows (connections) opened EINVAL reserved fields are not set to 0. + ====== ================================================ See the ioctl(2) man page for more details, error codes and restrictions. @@ -158,11 +166,13 @@ mmap() NX-GZIP device The mmap() system call for a NX-GZIP device fd returns a paste_address that the application can use to copy/paste its CRB to the hardware engines. + :: paste_addr = mmap(addr, size, prot, flags, fd, offset); Only restrictions on mmap for a NX-GZIP device fd are: + * size should be PAGE_SIZE * offset parameter should be 0ULL @@ -170,10 +180,12 @@ that the application can use to copy/paste its CRB to the hardware engines. In addition to the error conditions listed on the mmap(2) man page, can also fail with one of the following error codes: + ====== ============================================= EINVAL fd is not associated with an open window (i.e mmap() does not follow a successful call to the VAS_TX_WIN_OPEN ioctl). EINVAL offset field is not 0ULL. + ====== ============================================= Discovery of available VAS engines ================================== @@ -210,10 +222,10 @@ In case if NX encounters translation error (called NX page fault) on CSB address or any request buffer, raises an interrupt on the CPU to handle the fault. Page fault can happen if an application passes invalid addresses or request buffers are not in memory. The operating system handles the fault by -updating CSB with the following data: +updating CSB with the following data:: csb.flags = CSB_V; - csb.cc = CSB_CC_TRANSLATION; + csb.cc = CSB_CC_FAULT_ADDRESS; csb.ce = CSB_CE_TERMINATION; csb.address = fault_address; @@ -223,7 +235,7 @@ the application can resend this request to NX. If the OS can not update CSB due to invalid CSB address, sends SEGV signal to the process who opened the send window on which the original request was -issued. This signal returns with the following siginfo struct: +issued. This signal returns with the following siginfo struct:: siginfo.si_signo = SIGSEGV; siginfo.si_errno = EFAULT; @@ -248,6 +260,7 @@ Simple example ============== :: + int use_nx_gzip() { int rc, fd; diff --git a/Documentation/powerpc/vcpudispatch_stats.txt b/Documentation/powerpc/vcpudispatch_stats.rst index e21476bfd78c..5704657a5987 100644 --- a/Documentation/powerpc/vcpudispatch_stats.txt +++ b/Documentation/powerpc/vcpudispatch_stats.rst @@ -1,5 +1,8 @@ -VCPU Dispatch Statistics: -========================= +.. SPDX-License-Identifier: GPL-2.0 + +======================== +VCPU Dispatch Statistics +======================== For Shared Processor LPARs, the POWER Hypervisor maintains a relatively static mapping of the LPAR processors (vcpus) to physical processor @@ -20,25 +23,29 @@ The statistics themselves are available by reading the procfs file a vcpu as represented by the first field, followed by 8 numbers. The first number corresponds to: + 1. total vcpu dispatches since the beginning of statistics collection The next 4 numbers represent vcpu dispatch dispersions: + 2. number of times this vcpu was dispatched on the same processor as last time 3. number of times this vcpu was dispatched on a different processor core as last time, but within the same chip 4. number of times this vcpu was dispatched on a different chip 5. number of times this vcpu was dispatches on a different socket/drawer -(next numa boundary) + (next numa boundary) The final 3 numbers represent statistics in relation to the home node of the vcpu: + 6. number of times this vcpu was dispatched in its home node (chip) 7. number of times this vcpu was dispatched in a different node 8. number of times this vcpu was dispatched in a node further away (numa -distance) + distance) + +An example output:: -An example output: $ sudo cat /proc/powerpc/vcpudispatch_stats cpu0 6839 4126 2683 30 0 6821 18 0 cpu1 2515 1274 1229 12 0 2509 6 0 diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst index b21b5b245d13..3588f48841eb 100644 --- a/Documentation/process/2.Process.rst +++ b/Documentation/process/2.Process.rst @@ -295,7 +295,7 @@ mainline get there via -mm. The current -mm patch is available in the "mmotm" (-mm of the moment) directory at: - http://www.ozlabs.org/~akpm/mmotm/ + https://www.ozlabs.org/~akpm/mmotm/ Use of the MMOTM tree is likely to be a frustrating experience, though; there is a definite chance that it will not even compile. @@ -306,7 +306,7 @@ the mainline is expected to look like after the next merge window closes. Linux-next trees are announced on the linux-kernel and linux-next mailing lists when they are assembled; they can be downloaded from: - http://www.kernel.org/pub/linux/kernel/next/ + https://www.kernel.org/pub/linux/kernel/next/ Linux-next has become an integral part of the kernel development process; all patches merged during a given merge window should really have found @@ -365,21 +365,21 @@ to keep up with what other developers (and the mainline) are doing. Git is now packaged by almost all Linux distributions. There is a home page at: - http://git-scm.com/ + https://git-scm.com/ That page has pointers to documentation and tutorials. Among the kernel developers who do not use git, the most popular choice is almost certainly Mercurial: - http://www.selenic.com/mercurial/ + https://www.selenic.com/mercurial/ Mercurial shares many features with git, but it provides an interface which many find easier to use. The other tool worth knowing about is Quilt: - http://savannah.nongnu.org/projects/quilt/ + https://savannah.nongnu.org/projects/quilt/ Quilt is a patch management system, rather than a source code management system. It does not track history over time; it is, instead, oriented @@ -494,7 +494,7 @@ Andrew Morton gives this advice for aspiring kernel developers with others on getting things fixed up (this can require persistence!) but that's fine - it's a part of kernel development. -(http://lwn.net/Articles/283982/). +(https://lwn.net/Articles/283982/). In the absence of obvious problems to fix, developers are advised to look at the current lists of regressions and open bugs in general. There is diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst index 13dd893c9f88..c27e59d2f702 100644 --- a/Documentation/process/4.Coding.rst +++ b/Documentation/process/4.Coding.rst @@ -210,7 +210,7 @@ breaks? The best answer to this question was expressed by Linus in July, progress at all. Is it two steps forwards, one step back, or one step forward and two steps back? -(http://lwn.net/Articles/243460/). +(https://lwn.net/Articles/243460/). An especially unwelcome type of regression is any sort of change to the user-space ABI. Once an interface has been exported to user space, it must @@ -323,7 +323,7 @@ other architectures. If you do not happen to have an S/390 system or a Blackfin development board handy, you can still perform the compilation step. A large set of cross compilers for x86 systems can be found at - http://www.kernel.org/pub/tools/crosstool/ + https://www.kernel.org/pub/tools/crosstool/ Some time spent installing and using these compilers will help avoid embarrassment later. diff --git a/Documentation/process/botching-up-ioctls.rst b/Documentation/process/botching-up-ioctls.rst index 2d4829b2fb09..ba4667ab396b 100644 --- a/Documentation/process/botching-up-ioctls.rst +++ b/Documentation/process/botching-up-ioctls.rst @@ -2,7 +2,7 @@ (How to avoid) Botching up ioctls ================================= -From: http://blog.ffwll.ch/2013/11/botching-up-ioctls.html +From: https://blog.ffwll.ch/2013/11/botching-up-ioctls.html By: Daniel Vetter, Copyright © 2013 Intel Corporation diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 5cfb54c2aaa6..ee741763a3fc 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -29,7 +29,7 @@ you probably needn't concern yourself with pcmciautils. ====================== =============== ======================================== Program Minimal version Command to check the version ====================== =============== ======================================== -GNU C 4.8 gcc --version +GNU C 4.9 gcc --version GNU make 3.81 make --version binutils 2.23 ld -v flex 2.5.35 flex --version @@ -129,7 +129,7 @@ Architectural changes --------------------- DevFS has been obsoleted in favour of udev -(http://www.kernel.org/pub/linux/utils/kernel/hotplug/) +(https://www.kernel.org/pub/linux/utils/kernel/hotplug/) 32-bit UID support is now in place. Have fun! @@ -421,7 +421,7 @@ Intel P6 microcode udev ---- -- <http://www.freedesktop.org/software/systemd/man/udev.html> +- <https://www.freedesktop.org/software/systemd/man/udev.html> FUSE ---- @@ -474,4 +474,4 @@ Kernel documentation Sphinx ------ -- <http://www.sphinx-doc.org/> +- <https://www.sphinx-doc.org/> diff --git a/Documentation/process/clang-format.rst b/Documentation/process/clang-format.rst index 6710c0707721..82676e5a7c6e 100644 --- a/Documentation/process/clang-format.rst +++ b/Documentation/process/clang-format.rst @@ -32,7 +32,7 @@ Linux distributions for a long time. Search for ``clang-format`` in your repositories. Otherwise, you can either download pre-built LLVM/clang binaries or build the source code from: - http://releases.llvm.org/download.html + https://releases.llvm.org/download.html See more information about the tool at: diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 2657a55c6f12..98227226c4e5 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -319,6 +319,26 @@ If you are afraid to mix up your local variable names, you have another problem, which is called the function-growth-hormone-imbalance syndrome. See chapter 6 (Functions). +For symbol names and documentation, avoid introducing new usage of +'master / slave' (or 'slave' independent of 'master') and 'blacklist / +whitelist'. + +Recommended replacements for 'master / slave' are: + '{primary,main} / {secondary,replica,subordinate}' + '{initiator,requester} / {target,responder}' + '{controller,host} / {device,worker,proxy}' + 'leader / follower' + 'director / performer' + +Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist' + 'blocklist / passlist' + +Exceptions for introducing new usage is to maintain a userspace ABI/API, +or when updating code for an existing (as of 2020) hardware or protocol +specification that mandates those terms. For new specifications +translate specification usage of the terminology to the kernel coding +standard where possible. 5) Typedefs ----------- @@ -1129,7 +1149,7 @@ Addison-Wesley, Inc., 1999. ISBN 0-201-61586-X. GNU manuals - where in compliance with K&R and this text - for cpp, gcc, -gcc internals and indent, all available from http://www.gnu.org/manual/ +gcc internals and indent, all available from https://www.gnu.org/manual/ WG14 is the international standardization working group for the programming language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index 652e2aa02a66..4a9aa4f0681e 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -51,6 +51,24 @@ to make sure their systems do not continue running in the face of "unreachable" conditions. (For example, see commits like `this one <https://git.kernel.org/linus/d4689846881d160a4d12a514e991a740bcb5d65a>`_.) +uninitialized_var() +------------------- +For any compiler warnings about uninitialized variables, just add +an initializer. Using the uninitialized_var() macro (or similar +warning-silencing tricks) is dangerous as it papers over `real bugs +<https://lore.kernel.org/lkml/20200603174714.192027-1-glider@google.com/>`_ +(or can in the future), and suppresses unrelated compiler warnings +(e.g. "unused variable"). If the compiler thinks it is uninitialized, +either simply initialize the variable or make compiler changes. Keep in +mind that in most cases, if an initialization is obviously redundant, +the compiler's dead-store elimination pass will make sure there are no +needless variable writes. + +As Linus has said, this macro +`must <https://lore.kernel.org/lkml/CA+55aFw+Vbj0i=1TGqCR5vQkCzWJ0QxK6CernOU6eedsudAixw@mail.gmail.com/>`_ +`be <https://lore.kernel.org/lkml/CA+55aFwgbgqhbp1fkxvRKEpzyR5J8n1vKT1VZdz9knmPuXhOeg@mail.gmail.com/>`_ +`removed <https://lore.kernel.org/lkml/CA+55aFz2500WfbKXAx8s67wrm9=yVJu65TpLgN_ybYNv0VEOKA@mail.gmail.com/>`_. + open-coded arithmetic in allocator arguments -------------------------------------------- Dynamic size calculations (especially multiplication) should not be @@ -85,6 +103,11 @@ Instead, use the helper:: header = kzalloc(struct_size(header, item, count), GFP_KERNEL); +.. note:: If you are using struct_size() on a structure containing a zero-length + or a one-element array as a trailing array member, please refactor such + array usage and switch to a `flexible array member + <#zero-length-and-one-element-arrays>`_ instead. + See array_size(), array3_size(), and struct_size(), for more details as well as the related check_add_overflow() and check_mul_overflow() family of functions. @@ -200,3 +223,116 @@ All switch/case blocks must end in one of: * continue; * goto <label>; * return [expression]; + +Zero-length and one-element arrays +---------------------------------- +There is a regular need in the kernel to provide a way to declare having +a dynamically sized set of trailing elements in a structure. Kernel code +should always use `"flexible array members" <https://en.wikipedia.org/wiki/Flexible_array_member>`_ +for these cases. The older style of one-element or zero-length arrays should +no longer be used. + +In older C code, dynamically sized trailing elements were done by specifying +a one-element array at the end of a structure:: + + struct something { + size_t count; + struct foo items[1]; + }; + +This led to fragile size calculations via sizeof() (which would need to +remove the size of the single trailing element to get a correct size of +the "header"). A `GNU C extension <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_ +was introduced to allow for zero-length arrays, to avoid these kinds of +size problems:: + + struct something { + size_t count; + struct foo items[0]; + }; + +But this led to other problems, and didn't solve some problems shared by +both styles, like not being able to detect when such an array is accidentally +being used _not_ at the end of a structure (which could happen directly, or +when such a struct was in unions, structs of structs, etc). + +C99 introduced "flexible array members", which lacks a numeric size for +the array declaration entirely:: + + struct something { + size_t count; + struct foo items[]; + }; + +This is the way the kernel expects dynamically sized trailing elements +to be declared. It allows the compiler to generate errors when the +flexible array does not occur last in the structure, which helps to prevent +some kind of `undefined behavior +<https://git.kernel.org/linus/76497732932f15e7323dc805e8ea8dc11bb587cf>`_ +bugs from being inadvertently introduced to the codebase. It also allows +the compiler to correctly analyze array sizes (via sizeof(), +`CONFIG_FORTIFY_SOURCE`, and `CONFIG_UBSAN_BOUNDS`). For instance, +there is no mechanism that warns us that the following application of the +sizeof() operator to a zero-length array always results in zero:: + + struct something { + size_t count; + struct foo items[0]; + }; + + struct something *instance; + + instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL); + instance->count = count; + + size = sizeof(instance->items) * instance->count; + memcpy(instance->items, source, size); + +At the last line of code above, ``size`` turns out to be ``zero``, when one might +have thought it represents the total size in bytes of the dynamic memory recently +allocated for the trailing array ``items``. Here are a couple examples of this +issue: `link 1 +<https://git.kernel.org/linus/f2cd32a443da694ac4e28fbf4ac6f9d5cc63a539>`_, +`link 2 +<https://git.kernel.org/linus/ab91c2a89f86be2898cee208d492816ec238b2cf>`_. +Instead, `flexible array members have incomplete type, and so the sizeof() +operator may not be applied <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_, +so any misuse of such operators will be immediately noticed at build time. + +With respect to one-element arrays, one has to be acutely aware that `such arrays +occupy at least as much space as a single object of the type +<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_, +hence they contribute to the size of the enclosing structure. This is prone +to error every time people want to calculate the total size of dynamic memory +to allocate for a structure containing an array of this kind as a member:: + + struct something { + size_t count; + struct foo items[1]; + }; + + struct something *instance; + + instance = kmalloc(struct_size(instance, items, count - 1), GFP_KERNEL); + instance->count = count; + + size = sizeof(instance->items) * instance->count; + memcpy(instance->items, source, size); + +In the example above, we had to remember to calculate ``count - 1`` when using +the struct_size() helper, otherwise we would have --unintentionally-- allocated +memory for one too many ``items`` objects. The cleanest and least error-prone way +to implement this is through the use of a `flexible array member`:: + + struct something { + size_t count; + struct foo items[]; + }; + + struct something *instance; + + instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL); + instance->count = count; + + size = sizeof(instance->items[0]) * instance->count; + memcpy(instance->items, source, size); diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index 70791e153de1..20c9e07e09a4 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -597,7 +597,7 @@ For more details on what this should all look like, please see the ChangeLog section of the document: "The Perfect Patch" - http://www.ozlabs.org/~akpm/stuff/tpp.txt + https://www.ozlabs.org/~akpm/stuff/tpp.txt All of these things are sometimes very hard to do. It can take years to diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index f07c9250c3ac..dd231ffc8422 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -32,7 +32,7 @@ Below are the essential guides that every developer should read. kernel-enforcement-statement kernel-driver-statement -Other guides to the community that are of interest to most developers are: +Other guides to the community that are of interest to most developers are: .. toctree:: :maxdepth: 1 @@ -61,7 +61,7 @@ lack of a better place. botching-up-ioctls clang-format ../riscv/patch-acceptance - unaligned-memory-access + ../core-api/unaligned-memory-access .. only:: subproject and html diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index 9d6d0ac4fca9..64786e50026c 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -98,7 +98,7 @@ On-line docs * Title: **Linux Device Drivers, Third Edition** :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman - :URL: http://lwn.net/Kernel/LDD3/ + :URL: https://lwn.net/Kernel/LDD3/ :Date: 2005 :Description: A 600-page book covering the (2.6.10) driver programming API and kernel hacking in general. Available under the @@ -129,7 +129,7 @@ On-line docs * Title: **Linux Kernel Module Programming Guide** :Author: Ori Pomerantz. - :URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html + :URL: https://tldp.org/LDP/lkmpg/2.6/html/index.html :Date: 2001 :Keywords: modules, GPL book, /proc, ioctls, system calls, interrupt handlers . @@ -244,7 +244,7 @@ On-line docs * Title: **I/O Event Handling Under Linux** :Author: Richard Gooch. - :URL: http://web.mit.edu/~yandros/doc/io-events.html + :URL: https://web.mit.edu/~yandros/doc/io-events.html :Date: 1999 :Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness event queues. @@ -295,7 +295,7 @@ On-line docs * Title: **Design and Implementation of the Second Extended Filesystem** :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. - :URL: http://web.mit.edu/tytso/www/linux/ext2intro.html + :URL: https://web.mit.edu/tytso/www/linux/ext2intro.html :Date: 1998 :Keywords: ext2, linux fs history, inode, directory, link, devices, VFS, physical structure, performance, benchmarks, ext2fs library, @@ -322,7 +322,7 @@ On-line docs * Title: **Linux Kernel Hackers' Guide** :Author: Michael K. Johnson. - :URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html + :URL: https://www.tldp.org/LDP/khg/HyperNews/get/khg.html :Date: 1997 :Keywords: device drivers, files, VFS, kernel interface, character vs block devices, hardware interrupts, scsi, DMA, access to user memory, @@ -375,7 +375,7 @@ On-line docs * Title: **Dissecting Interrupts and Browsing DMA** :Author: Alessandro Rubini and Georg v. Zezschwitz. - :URL: http://www.linuxjournal.com/article.php?sid=1222 + :URL: https://www.linuxjournal.com/article.php?sid=1222 :Date: 1996 :Keywords: interrupts, irqs, DMA, bottom halves, task queues. :Description: Linux Journal Kernel Korner article. @@ -391,7 +391,7 @@ On-line docs * Title: **Device Drivers Concluded** :Author: Georg v. Zezschwitz. - :URL: http://www.linuxjournal.com/article.php?sid=1287 + :URL: https://www.linuxjournal.com/article.php?sid=1287 :Date: 1996 :Keywords: address spaces, pages, pagination, page management, demand loading, swapping, memory protection, memory mapping, mmap, @@ -405,7 +405,7 @@ On-line docs * Title: **Network Buffers And Memory Management** :Author: Alan Cox. - :URL: http://www.linuxjournal.com/article.php?sid=1312 + :URL: https://www.linuxjournal.com/article.php?sid=1312 :Date: 1996 :Keywords: sk_buffs, network devices, protocol/link layer variables, network devices flags, transmit, receive, @@ -418,7 +418,7 @@ On-line docs * Title: **Analysis of the Ext2fs structure** :Author: Louis-Dominique Dubeau. - :URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ + :URL: https://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ :Date: 1994 :Keywords: ext2, filesystem, ext2fs. :Description: Description of ext2's blocks, directories, inodes, @@ -480,7 +480,7 @@ Published books :ISBN: 0-596-00590-3 :Notes: Further information in http://www.oreilly.com/catalog/linuxdrive3/ - PDF format, URL: http://lwn.net/Kernel/LDD3/ + PDF format, URL: https://lwn.net/Kernel/LDD3/ * Title: **Linux Kernel Internals** @@ -561,7 +561,7 @@ Miscellaneous * Name: **Linux Weekly News** - :URL: http://lwn.net + :URL: https://lwn.net :Keywords: latest kernel news. :Description: The title says it all. There's a fixed kernel section summarizing developers' work, bug fixes, new features and versions @@ -570,7 +570,7 @@ Miscellaneous * Name: **The home page of Linux-MM** :Author: The Linux-MM team. - :URL: http://linux-mm.org/ + :URL: https://linux-mm.org/ :Keywords: memory management, Linux-MM, mm patches, TODO, docs, mailing list. :Description: Site devoted to Linux Memory Management development. @@ -579,7 +579,7 @@ Miscellaneous * Name: **Kernel Newbies IRC Channel and Website** - :URL: http://www.kernelnewbies.org + :URL: https://www.kernelnewbies.org :Keywords: IRC, newbies, channel, asking doubts. :Description: #kernelnewbies on irc.oftc.net. #kernelnewbies is an IRC network dedicated to the 'newbie' @@ -605,4 +605,4 @@ Miscellaneous Document last updated on Tue 2016-Sep-20 This document is based on: - http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html + https://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst index 17db11b7ed48..8f8f1fee92b8 100644 --- a/Documentation/process/maintainer-pgp-guide.rst +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -462,7 +462,7 @@ geographical region, and open/proprietary hardware considerations. .. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6 .. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nitrokey-pro-2-3 .. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/ -.. _Gnuk: http://www.fsij.org/doc-gnuk/ +.. _Gnuk: https://www.fsij.org/doc-gnuk/ .. _`LWN has a good review`: https://lwn.net/Articles/736231/ .. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst index 1acaa14903d6..74b35bfc6623 100644 --- a/Documentation/process/submitting-drivers.rst +++ b/Documentation/process/submitting-drivers.rst @@ -5,8 +5,8 @@ Submitting Drivers For The Linux Kernel This document is intended to explain how to submit device drivers to the various kernel trees. Note that if you are interested in video card drivers -you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org -(http://x.org/) instead. +you should probably talk to XFree86 (https://www.xfree86.org/) and/or X.Org +(https://x.org/) instead. .. note:: @@ -25,7 +25,7 @@ Allocating Device Numbers Major and minor numbers for block and character devices are allocated by the Linux assigned name and number authority (currently this is -Torben Mathiasen). The site is http://www.lanana.org/. This +Torben Mathiasen). The site is https://www.lanana.org/. This also deals with allocating numbers for devices that are not going to be submitted to the mainstream kernel. See :ref:`Documentation/admin-guide/devices.rst <admin_devices>` @@ -155,30 +155,30 @@ Linux kernel master tree: where *country_code* == your country code, such as **us**, **uk**, **fr**, etc. - http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git + https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git Linux kernel mailing list: linux-kernel@vger.kernel.org [mail majordomo@vger.kernel.org to subscribe] Linux Device Drivers, Third Edition (covers 2.6.10): - http://lwn.net/Kernel/LDD3/ (free version) + https://lwn.net/Kernel/LDD3/ (free version) LWN.net: - Weekly summary of kernel development activity - http://lwn.net/ + Weekly summary of kernel development activity - https://lwn.net/ 2.6 API changes: - http://lwn.net/Articles/2.6-kernel-api/ + https://lwn.net/Articles/2.6-kernel-api/ Porting drivers from prior kernels to 2.6: - http://lwn.net/Articles/driver-porting/ + https://lwn.net/Articles/driver-porting/ KernelNewbies: Documentation and assistance for new kernel programmers - http://kernelnewbies.org/ + https://kernelnewbies.org/ Linux USB project: http://www.linux-usb.org/ @@ -187,7 +187,7 @@ How to NOT write kernel driver by Arjan van de Ven: http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf Kernel Janitor: - http://kernelnewbies.org/KernelJanitors + https://kernelnewbies.org/KernelJanitors GIT, Fast Version Control System: - http://git-scm.com/ + https://git-scm.com/ diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 1699b7f8e63a..5219bf3cddfc 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -94,7 +94,7 @@ individual patches which modify things in logical stages; see very important if you want your patch accepted. If you're using ``git``, ``git rebase -i`` can help you with this process. If -you're not using ``git``, ``quilt`` <http://savannah.nongnu.org/projects/quilt> +you're not using ``git``, ``quilt`` <https://savannah.nongnu.org/projects/quilt> is another popular alternative. .. _describe_changes: @@ -196,6 +196,11 @@ outputting the above style in the ``git log`` or ``git show`` commands:: [pretty] fixes = Fixes: %h (\"%s\") +An example call:: + + $ git log -1 --pretty=fixes 54a4f0239f2e + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") + .. _split_changes: 3) Separate your changes @@ -892,7 +897,7 @@ References ---------- Andrew Morton, "The perfect patch" (tpp). - <http://www.ozlabs.org/~akpm/stuff/tpp.txt> + <https://www.ozlabs.org/~akpm/stuff/tpp.txt> Jeff Garzik, "Linux kernel patch submission format". <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> diff --git a/Documentation/s390/monreader.rst b/Documentation/s390/monreader.rst index 1e857575c113..21cdfb699b49 100644 --- a/Documentation/s390/monreader.rst +++ b/Documentation/s390/monreader.rst @@ -146,7 +146,7 @@ start offset relative to a 4K page (frame) boundary. See "Appendix A: `*MONITOR`" in the "z/VM Performance" document for a description of the monitor control element layout. The layout of the monitor records can -be found here (z/VM 5.1): http://www.vm.ibm.com/pubs/mon510/index.html +be found here (z/VM 5.1): https://www.vm.ibm.com/pubs/mon510/index.html The layout of the data stream provided by the monreader device is as follows:: diff --git a/Documentation/s390/s390dbf.rst b/Documentation/s390/s390dbf.rst index cdb36842b898..af8bdc3629e7 100644 --- a/Documentation/s390/s390dbf.rst +++ b/Documentation/s390/s390dbf.rst @@ -67,7 +67,7 @@ corresponding component. The debugfs normally should be mounted to The content of the directories are files which represent different views to the debug log. Each component can decide which views should be used through registering them with the function :c:func:`debug_register_view()`. -Predefined views for hex/ascii, sprintf and raw binary data are provided. +Predefined views for hex/ascii and sprintf data are provided. It is also possible to define other views. The content of a view can be inspected simply by reading the corresponding debugfs file. @@ -119,8 +119,6 @@ Predefined views: extern struct debug_view debug_hex_ascii_view; - extern struct debug_view debug_raw_view; - extern struct debug_view debug_sprintf_view; Examples @@ -129,7 +127,7 @@ Examples .. code-block:: c /* - * hex_ascii- + raw-view Example + * hex_ascii-view Example */ #include <linux/init.h> @@ -143,7 +141,6 @@ Examples debug_info = debug_register("test", 1, 4, 4 ); debug_register_view(debug_info, &debug_hex_ascii_view); - debug_register_view(debug_info, &debug_raw_view); debug_text_event(debug_info, 4 , "one "); debug_int_exception(debug_info, 4, 4711); @@ -201,7 +198,7 @@ debugfs-files: Example:: > ls /sys/kernel/debug/s390dbf/dasd - flush hex_ascii level pages raw + flush hex_ascii level pages > 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 @@ -298,10 +295,9 @@ order to see the debug entries well formatted. Predefined Views ---------------- -There are three predefined views: hex_ascii, raw and sprintf. +There are two predefined views: hex_ascii and sprintf. The hex_ascii view shows the data field in hex and ascii representation (e.g. ``45 43 4b 44 | ECKD``). -The raw view returns a bytestream as the debug areas are stored in memory. The sprintf view formats the debug entries in the same way as the sprintf function would do. The sprintf event/exception functions write to the @@ -334,11 +330,6 @@ The format of the hex_ascii and sprintf view is as follows: - Return Address to caller - data field -The format of the raw view is: - -- Header as described in debug.h -- datafield - A typical line of the hex_ascii view will look like the following (first line is only for explanation and will not be displayed when 'cating' the view):: diff --git a/Documentation/s390/vfio-ap.rst b/Documentation/s390/vfio-ap.rst index 367e27ec3c50..e15436599086 100644 --- a/Documentation/s390/vfio-ap.rst +++ b/Documentation/s390/vfio-ap.rst @@ -361,7 +361,7 @@ matrix device. assign_domain / unassign_domain: Write-only attributes for assigning/unassigning an AP usage domain to/from the mediated matrix device. To assign/unassign a domain, the domain - number of the the usage domain is echoed to the respective attribute + number of the usage domain is echoed to the respective attribute file. matrix: A read-only file for displaying the APQNs derived from the cross product diff --git a/Documentation/scheduler/index.rst b/Documentation/scheduler/index.rst index 69074e5de9c4..88900aabdbf7 100644 --- a/Documentation/scheduler/index.rst +++ b/Documentation/scheduler/index.rst @@ -12,6 +12,7 @@ Linux Scheduler sched-deadline sched-design-CFS sched-domains + sched-capacity sched-energy sched-nice-design sched-rt-group diff --git a/Documentation/scheduler/sched-capacity.rst b/Documentation/scheduler/sched-capacity.rst new file mode 100644 index 000000000000..00bf0d011e2a --- /dev/null +++ b/Documentation/scheduler/sched-capacity.rst @@ -0,0 +1,439 @@ +========================= +Capacity Aware Scheduling +========================= + +1. CPU Capacity +=============== + +1.1 Introduction +---------------- + +Conventional, homogeneous SMP platforms are composed of purely identical +CPUs. Heterogeneous platforms on the other hand are composed of CPUs with +different performance characteristics - on such platforms, not all CPUs can be +considered equal. + +CPU capacity is a measure of the performance a CPU can reach, normalized against +the most performant CPU in the system. Heterogeneous systems are also called +asymmetric CPU capacity systems, as they contain CPUs of different capacities. + +Disparity in maximum attainable performance (IOW in maximum CPU capacity) stems +from two factors: + +- not all CPUs may have the same microarchitecture (µarch). +- with Dynamic Voltage and Frequency Scaling (DVFS), not all CPUs may be + physically able to attain the higher Operating Performance Points (OPP). + +Arm big.LITTLE systems are an example of both. The big CPUs are more +performance-oriented than the LITTLE ones (more pipeline stages, bigger caches, +smarter predictors, etc), and can usually reach higher OPPs than the LITTLE ones +can. + +CPU performance is usually expressed in Millions of Instructions Per Second +(MIPS), which can also be expressed as a given amount of instructions attainable +per Hz, leading to:: + + capacity(cpu) = work_per_hz(cpu) * max_freq(cpu) + +1.2 Scheduler terms +------------------- + +Two different capacity values are used within the scheduler. A CPU's +``capacity_orig`` is its maximum attainable capacity, i.e. its maximum +attainable performance level. A CPU's ``capacity`` is its ``capacity_orig`` to +which some loss of available performance (e.g. time spent handling IRQs) is +subtracted. + +Note that a CPU's ``capacity`` is solely intended to be used by the CFS class, +while ``capacity_orig`` is class-agnostic. The rest of this document will use +the term ``capacity`` interchangeably with ``capacity_orig`` for the sake of +brevity. + +1.3 Platform examples +--------------------- + +1.3.1 Identical OPPs +~~~~~~~~~~~~~~~~~~~~ + +Consider an hypothetical dual-core asymmetric CPU capacity system where + +- work_per_hz(CPU0) = W +- work_per_hz(CPU1) = W/2 +- all CPUs are running at the same fixed frequency + +By the above definition of capacity: + +- capacity(CPU0) = C +- capacity(CPU1) = C/2 + +To draw the parallel with Arm big.LITTLE, CPU0 would be a big while CPU1 would +be a LITTLE. + +With a workload that periodically does a fixed amount of work, you will get an +execution trace like so:: + + CPU0 work ^ + | ____ ____ ____ + | | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + + CPU1 work ^ + | _________ _________ ____ + | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + +CPU0 has the highest capacity in the system (C), and completes a fixed amount of +work W in T units of time. On the other hand, CPU1 has half the capacity of +CPU0, and thus only completes W/2 in T. + +1.3.2 Different max OPPs +~~~~~~~~~~~~~~~~~~~~~~~~ + +Usually, CPUs of different capacity values also have different maximum +OPPs. Consider the same CPUs as above (i.e. same work_per_hz()) with: + +- max_freq(CPU0) = F +- max_freq(CPU1) = 2/3 * F + +This yields: + +- capacity(CPU0) = C +- capacity(CPU1) = C/3 + +Executing the same workload as described in 1.3.1, which each CPU running at its +maximum frequency results in:: + + CPU0 work ^ + | ____ ____ ____ + | | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + + workload on CPU1 + CPU1 work ^ + | ______________ ______________ ____ + | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + +1.4 Representation caveat +------------------------- + +It should be noted that having a *single* value to represent differences in CPU +performance is somewhat of a contentious point. The relative performance +difference between two different µarchs could be X% on integer operations, Y% on +floating point operations, Z% on branches, and so on. Still, results using this +simple approach have been satisfactory for now. + +2. Task utilization +=================== + +2.1 Introduction +---------------- + +Capacity aware scheduling requires an expression of a task's requirements with +regards to CPU capacity. Each scheduler class can express this differently, and +while task utilization is specific to CFS, it is convenient to describe it here +in order to introduce more generic concepts. + +Task utilization is a percentage meant to represent the throughput requirements +of a task. A simple approximation of it is the task's duty cycle, i.e.:: + + task_util(p) = duty_cycle(p) + +On an SMP system with fixed frequencies, 100% utilization suggests the task is a +busy loop. Conversely, 10% utilization hints it is a small periodic task that +spends more time sleeping than executing. Variable CPU frequencies and +asymmetric CPU capacities complexify this somewhat; the following sections will +expand on these. + +2.2 Frequency invariance +------------------------ + +One issue that needs to be taken into account is that a workload's duty cycle is +directly impacted by the current OPP the CPU is running at. Consider running a +periodic workload at a given frequency F:: + + CPU work ^ + | ____ ____ ____ + | | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + +This yields duty_cycle(p) == 25%. + +Now, consider running the *same* workload at frequency F/2:: + + CPU work ^ + | _________ _________ ____ + | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + +This yields duty_cycle(p) == 50%, despite the task having the exact same +behaviour (i.e. executing the same amount of work) in both executions. + +The task utilization signal can be made frequency invariant using the following +formula:: + + task_util_freq_inv(p) = duty_cycle(p) * (curr_frequency(cpu) / max_frequency(cpu)) + +Applying this formula to the two examples above yields a frequency invariant +task utilization of 25%. + +2.3 CPU invariance +------------------ + +CPU capacity has a similar effect on task utilization in that running an +identical workload on CPUs of different capacity values will yield different +duty cycles. + +Consider the system described in 1.3.2., i.e.:: + +- capacity(CPU0) = C +- capacity(CPU1) = C/3 + +Executing a given periodic workload on each CPU at their maximum frequency would +result in:: + + CPU0 work ^ + | ____ ____ ____ + | | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + + CPU1 work ^ + | ______________ ______________ ____ + | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + +IOW, + +- duty_cycle(p) == 25% if p runs on CPU0 at its maximum frequency +- duty_cycle(p) == 75% if p runs on CPU1 at its maximum frequency + +The task utilization signal can be made CPU invariant using the following +formula:: + + task_util_cpu_inv(p) = duty_cycle(p) * (capacity(cpu) / max_capacity) + +with ``max_capacity`` being the highest CPU capacity value in the +system. Applying this formula to the above example above yields a CPU +invariant task utilization of 25%. + +2.4 Invariant task utilization +------------------------------ + +Both frequency and CPU invariance need to be applied to task utilization in +order to obtain a truly invariant signal. The pseudo-formula for a task +utilization that is both CPU and frequency invariant is thus, for a given +task p:: + + curr_frequency(cpu) capacity(cpu) + task_util_inv(p) = duty_cycle(p) * ------------------- * ------------- + max_frequency(cpu) max_capacity + +In other words, invariant task utilization describes the behaviour of a task as +if it were running on the highest-capacity CPU in the system, running at its +maximum frequency. + +Any mention of task utilization in the following sections will imply its +invariant form. + +2.5 Utilization estimation +-------------------------- + +Without a crystal ball, task behaviour (and thus task utilization) cannot +accurately be predicted the moment a task first becomes runnable. The CFS class +maintains a handful of CPU and task signals based on the Per-Entity Load +Tracking (PELT) mechanism, one of those yielding an *average* utilization (as +opposed to instantaneous). + +This means that while the capacity aware scheduling criteria will be written +considering a "true" task utilization (using a crystal ball), the implementation +will only ever be able to use an estimator thereof. + +3. Capacity aware scheduling requirements +========================================= + +3.1 CPU capacity +---------------- + +Linux cannot currently figure out CPU capacity on its own, this information thus +needs to be handed to it. Architectures must define arch_scale_cpu_capacity() +for that purpose. + +The arm and arm64 architectures directly map this to the arch_topology driver +CPU scaling data, which is derived from the capacity-dmips-mhz CPU binding; see +Documentation/devicetree/bindings/arm/cpu-capacity.txt. + +3.2 Frequency invariance +------------------------ + +As stated in 2.2, capacity-aware scheduling requires a frequency-invariant task +utilization. Architectures must define arch_scale_freq_capacity(cpu) for that +purpose. + +Implementing this function requires figuring out at which frequency each CPU +have been running at. One way to implement this is to leverage hardware counters +whose increment rate scale with a CPU's current frequency (APERF/MPERF on x86, +AMU on arm64). Another is to directly hook into cpufreq frequency transitions, +when the kernel is aware of the switched-to frequency (also employed by +arm/arm64). + +4. Scheduler topology +===================== + +During the construction of the sched domains, the scheduler will figure out +whether the system exhibits asymmetric CPU capacities. Should that be the +case: + +- The sched_asym_cpucapacity static key will be enabled. +- The SD_ASYM_CPUCAPACITY flag will be set at the lowest sched_domain level that + spans all unique CPU capacity values. + +The sched_asym_cpucapacity static key is intended to guard sections of code that +cater to asymmetric CPU capacity systems. Do note however that said key is +*system-wide*. Imagine the following setup using cpusets:: + + capacity C/2 C + ________ ________ + / \ / \ + CPUs 0 1 2 3 4 5 6 7 + \__/ \______________/ + cpusets cs0 cs1 + +Which could be created via: + +.. code-block:: sh + + mkdir /sys/fs/cgroup/cpuset/cs0 + echo 0-1 > /sys/fs/cgroup/cpuset/cs0/cpuset.cpus + echo 0 > /sys/fs/cgroup/cpuset/cs0/cpuset.mems + + mkdir /sys/fs/cgroup/cpuset/cs1 + echo 2-7 > /sys/fs/cgroup/cpuset/cs1/cpuset.cpus + echo 0 > /sys/fs/cgroup/cpuset/cs1/cpuset.mems + + echo 0 > /sys/fs/cgroup/cpuset/cpuset.sched_load_balance + +Since there *is* CPU capacity asymmetry in the system, the +sched_asym_cpucapacity static key will be enabled. However, the sched_domain +hierarchy of CPUs 0-1 spans a single capacity value: SD_ASYM_CPUCAPACITY isn't +set in that hierarchy, it describes an SMP island and should be treated as such. + +Therefore, the 'canonical' pattern for protecting codepaths that cater to +asymmetric CPU capacities is to: + +- Check the sched_asym_cpucapacity static key +- If it is enabled, then also check for the presence of SD_ASYM_CPUCAPACITY in + the sched_domain hierarchy (if relevant, i.e. the codepath targets a specific + CPU or group thereof) + +5. Capacity aware scheduling implementation +=========================================== + +5.1 CFS +------- + +5.1.1 Capacity fitness +~~~~~~~~~~~~~~~~~~~~~~ + +The main capacity scheduling criterion of CFS is:: + + task_util(p) < capacity(task_cpu(p)) + +This is commonly called the capacity fitness criterion, i.e. CFS must ensure a +task "fits" on its CPU. If it is violated, the task will need to achieve more +work than what its CPU can provide: it will be CPU-bound. + +Furthermore, uclamp lets userspace specify a minimum and a maximum utilization +value for a task, either via sched_setattr() or via the cgroup interface (see +Documentation/admin-guide/cgroup-v2.rst). As its name imply, this can be used to +clamp task_util() in the previous criterion. + +5.1.2 Wakeup CPU selection +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CFS task wakeup CPU selection follows the capacity fitness criterion described +above. On top of that, uclamp is used to clamp the task utilization values, +which lets userspace have more leverage over the CPU selection of CFS +tasks. IOW, CFS wakeup CPU selection searches for a CPU that satisfies:: + + clamp(task_util(p), task_uclamp_min(p), task_uclamp_max(p)) < capacity(cpu) + +By using uclamp, userspace can e.g. allow a busy loop (100% utilization) to run +on any CPU by giving it a low uclamp.max value. Conversely, it can force a small +periodic task (e.g. 10% utilization) to run on the highest-performance CPUs by +giving it a high uclamp.min value. + +.. note:: + + Wakeup CPU selection in CFS can be eclipsed by Energy Aware Scheduling + (EAS), which is described in Documentation/scheduling/sched-energy.rst. + +5.1.3 Load balancing +~~~~~~~~~~~~~~~~~~~~ + +A pathological case in the wakeup CPU selection occurs when a task rarely +sleeps, if at all - it thus rarely wakes up, if at all. Consider:: + + w == wakeup event + + capacity(CPU0) = C + capacity(CPU1) = C / 3 + + workload on CPU0 + CPU work ^ + | _________ _________ ____ + | | | | | | + +----+----+----+----+----+----+----+----+----+----+-> time + w w w + + workload on CPU1 + CPU work ^ + | ____________________________________________ + | | + +----+----+----+----+----+----+----+----+----+----+-> + w + +This workload should run on CPU0, but if the task either: + +- was improperly scheduled from the start (inaccurate initial + utilization estimation) +- was properly scheduled from the start, but suddenly needs more + processing power + +then it might become CPU-bound, IOW ``task_util(p) > capacity(task_cpu(p))``; +the CPU capacity scheduling criterion is violated, and there may not be any more +wakeup event to fix this up via wakeup CPU selection. + +Tasks that are in this situation are dubbed "misfit" tasks, and the mechanism +put in place to handle this shares the same name. Misfit task migration +leverages the CFS load balancer, more specifically the active load balance part +(which caters to migrating currently running tasks). When load balance happens, +a misfit active load balance will be triggered if a misfit task can be migrated +to a CPU with more capacity than its current one. + +5.2 RT +------ + +5.2.1 Wakeup CPU selection +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +RT task wakeup CPU selection searches for a CPU that satisfies:: + + task_uclamp_min(p) <= capacity(task_cpu(cpu)) + +while still following the usual priority constraints. If none of the candidate +CPUs can satisfy this capacity criterion, then strict priority based scheduling +is followed and CPU capacities are ignored. + +5.3 DL +------ + +5.3.1 Wakeup CPU selection +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +DL task wakeup CPU selection searches for a CPU that satisfies:: + + task_bandwidth(p) < capacity(task_cpu(p)) + +while still respecting the usual bandwidth and deadline constraints. If +none of the candidate CPUs can satisfy this capacity criterion, then the +task will remain on its current CPU. diff --git a/Documentation/scheduler/sched-energy.rst b/Documentation/scheduler/sched-energy.rst index 9580c57a52bc..78f850778982 100644 --- a/Documentation/scheduler/sched-energy.rst +++ b/Documentation/scheduler/sched-energy.rst @@ -331,16 +331,8 @@ asymmetric CPU topologies for now. This requirement is checked at run-time by looking for the presence of the SD_ASYM_CPUCAPACITY flag when the scheduling domains are built. -The flag is set/cleared automatically by the scheduler topology code whenever -there are CPUs with different capacities in a root domain. The capacities of -CPUs are provided by arch-specific code through the arch_scale_cpu_capacity() -callback. As an example, arm and arm64 share an implementation of this callback -which uses a combination of CPUFreq data and device-tree bindings to compute the -capacity of CPUs (see drivers/base/arch_topology.c for more details). - -So, in order to use EAS on your platform your architecture must implement the -arch_scale_cpu_capacity() callback, and some of the CPUs must have a lower -capacity than others. +See Documentation/sched/sched-capacity.rst for requirements to be met for this +flag to be set in the sched_domain hierarchy. Please note that EAS is not fundamentally incompatible with SMP, but no significant savings on SMP platforms have been observed yet. This restriction diff --git a/Documentation/scsi/advansys.rst b/Documentation/scsi/advansys.rst index e0367e179696..7ea12b100ff4 100644 --- a/Documentation/scsi/advansys.rst +++ b/Documentation/scsi/advansys.rst @@ -125,7 +125,7 @@ The following constants can be defined in the source file. c. klogd is started with the appropriate -c parameter (e.g. klogd -c 8) - This will cause printk() messages to be be displayed on the + This will cause printk() messages to be displayed on the current console. Refer to the klogd(8) and syslogd(8) man pages for details. diff --git a/Documentation/scsi/scsi-parameters.rst b/Documentation/scsi/scsi-parameters.rst index 9aba897c97ac..e5f68b431f5c 100644 --- a/Documentation/scsi/scsi-parameters.rst +++ b/Documentation/scsi/scsi-parameters.rst @@ -94,7 +94,7 @@ parameters may be changed at runtime by the command (/proc/sys/dev/scsi/logging_level). There is also a nice 'scsi_logging_level' script in the S390-tools package, available for download at - http://www-128.ibm.com/developerworks/linux/linux390/s390-tools-1.5.4.html + https://github.com/ibm-s390-tools/s390-tools/blob/master/scripts/scsi_logging_level scsi_mod.scan= [SCSI] sync (default) scans SCSI busses as they are discovered. async scans them in kernel threads, diff --git a/Documentation/security/credentials.rst b/Documentation/security/credentials.rst index 282e79feee6a..d9387209d143 100644 --- a/Documentation/security/credentials.rst +++ b/Documentation/security/credentials.rst @@ -453,9 +453,9 @@ still at this point. When replacing the group list, the new list must be sorted before it is added to the credential, as a binary search is used to test for -membership. In practice, this means :c:func:`groups_sort` should be -called before :c:func:`set_groups` or :c:func:`set_current_groups`. -:c:func:`groups_sort)` must not be called on a ``struct group_list`` which +membership. In practice, this means groups_sort() should be +called before set_groups() or set_current_groups(). +groups_sort() must not be called on a ``struct group_list`` which is shared as it may permute elements as part of the sorting process even if the array is already sorted. @@ -548,6 +548,10 @@ pointer will not change over the lifetime of the file struct, and nor will the contents of the cred struct pointed to, barring the exceptions listed above (see the Task Credentials section). +To avoid "confused deputy" privilege escalation attacks, access control checks +during subsequent operations on an opened file should use these credentials +instead of "current"'s credentials, as the file may have been passed to a more +privileged process. Overriding the VFS's Use of Credentials ======================================= diff --git a/Documentation/security/keys/core.rst b/Documentation/security/keys/core.rst index cdc42ccc12e4..aa0081685ee1 100644 --- a/Documentation/security/keys/core.rst +++ b/Documentation/security/keys/core.rst @@ -912,7 +912,7 @@ The keyctl syscall functions are: One application of restricted keyrings is to verify X.509 certificate chains or individual certificate signatures using the asymmetric key type. - See Documentation/crypto/asymmetric-keys.txt for specific restrictions + See Documentation/crypto/asymmetric-keys.rst for specific restrictions applicable to the asymmetric key type. diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst index 50ac8bcd6970..9483a7425ad5 100644 --- a/Documentation/security/keys/trusted-encrypted.rst +++ b/Documentation/security/keys/trusted-encrypted.rst @@ -200,7 +200,7 @@ Load an encrypted key "evm" from saved blob:: 24717c64 5972dcb82ab2dde83376d82b2e3c09ffc Other uses for trusted and encrypted keys, such as for disk and file encryption -are anticipated. In particular the new format 'ecryptfs' has been defined in +are anticipated. In particular the new format 'ecryptfs' has been defined in order to use encrypted keys to mount an eCryptfs filesystem. More details about the usage can be found in the file ``Documentation/security/keys/ecryptfs.rst``. diff --git a/Documentation/sh/index.rst b/Documentation/sh/index.rst index bc8db7ba894a..b5933fd399f3 100644 --- a/Documentation/sh/index.rst +++ b/Documentation/sh/index.rst @@ -4,6 +4,12 @@ SuperH Interfaces Guide :Author: Paul Mundt +.. toctree:: + :maxdepth: 1 + + new-machine + register-banks + Memory Management ================= @@ -16,18 +22,6 @@ Store Queue API .. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c :export: -SH-5 ----- - -TLB Interfaces -~~~~~~~~~~~~~~ - -.. kernel-doc:: arch/sh/mm/tlb-sh5.c - :internal: - -.. kernel-doc:: arch/sh/include/asm/tlb_64.h - :internal: - Machine Specific Interfaces =========================== diff --git a/Documentation/sh/new-machine.txt b/Documentation/sh/new-machine.rst index e0961a66130b..e501c52b3b30 100644 --- a/Documentation/sh/new-machine.txt +++ b/Documentation/sh/new-machine.rst @@ -1,6 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 - Adding a new board to LinuxSH - ================================ +============================= +Adding a new board to LinuxSH +============================= Paul Mundt <lethal@linux-sh.org> @@ -19,65 +21,67 @@ include/asm-sh/. For the new kernel, things are broken out by board type, companion chip type, and CPU type. Looking at a tree view of this directory hierarchy looks like the following: -Board-specific code: - -. -|-- arch -| `-- sh -| `-- boards -| |-- adx -| | `-- board-specific files -| |-- bigsur -| | `-- board-specific files -| | -| ... more boards here ... -| -`-- include - `-- asm-sh - |-- adx - | `-- board-specific headers - |-- bigsur - | `-- board-specific headers - | - .. more boards here ... - -Next, for companion chips: -. -`-- arch - `-- sh - `-- cchips - `-- hd6446x - `-- hd64461 - `-- cchip-specific files +Board-specific code:: + + . + |-- arch + | `-- sh + | `-- boards + | |-- adx + | | `-- board-specific files + | |-- bigsur + | | `-- board-specific files + | | + | ... more boards here ... + | + `-- include + `-- asm-sh + |-- adx + | `-- board-specific headers + |-- bigsur + | `-- board-specific headers + | + .. more boards here ... + +Next, for companion chips:: + + . + `-- arch + `-- sh + `-- cchips + `-- hd6446x + `-- hd64461 + `-- cchip-specific files ... and so on. Headers for the companion chips are treated the same way as board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the hd64461-specific headers. -Finally, CPU family support is also abstracted: -. -|-- arch -| `-- sh -| |-- kernel -| | `-- cpu -| | |-- sh2 -| | | `-- SH-2 generic files -| | |-- sh3 -| | | `-- SH-3 generic files -| | `-- sh4 -| | `-- SH-4 generic files -| `-- mm -| `-- This is also broken out per CPU family, so each family can -| have their own set of cache/tlb functions. -| -`-- include - `-- asm-sh - |-- cpu-sh2 - | `-- SH-2 specific headers - |-- cpu-sh3 - | `-- SH-3 specific headers - `-- cpu-sh4 - `-- SH-4 specific headers +Finally, CPU family support is also abstracted:: + + . + |-- arch + | `-- sh + | |-- kernel + | | `-- cpu + | | |-- sh2 + | | | `-- SH-2 generic files + | | |-- sh3 + | | | `-- SH-3 generic files + | | `-- sh4 + | | `-- SH-4 generic files + | `-- mm + | `-- This is also broken out per CPU family, so each family can + | have their own set of cache/tlb functions. + | + `-- include + `-- asm-sh + |-- cpu-sh2 + | `-- SH-2 specific headers + |-- cpu-sh3 + | `-- SH-3 specific headers + `-- cpu-sh4 + `-- SH-4 specific headers It should be noted that CPU subtypes are _not_ abstracted. Thus, these still need to be dealt with by the CPU family specific code. @@ -110,33 +114,33 @@ arch/sh/boards and the include/asm-sh/ hierarchy. In order to better explain this, we use some examples for adding an imaginary board. For setup code, we're required at the very least to provide definitions for get_system_type() and platform_setup(). For our imaginary board, this -might look something like: +might look something like:: -/* - * arch/sh/boards/vapor/setup.c - Setup code for imaginary board - */ -#include <linux/init.h> + /* + * arch/sh/boards/vapor/setup.c - Setup code for imaginary board + */ + #include <linux/init.h> -const char *get_system_type(void) -{ - return "FooTech Vaporboard"; -} + const char *get_system_type(void) + { + return "FooTech Vaporboard"; + } -int __init platform_setup(void) -{ - /* - * If our hardware actually existed, we would do real - * setup here. Though it's also sane to leave this empty - * if there's no real init work that has to be done for - * this board. - */ + int __init platform_setup(void) + { + /* + * If our hardware actually existed, we would do real + * setup here. Though it's also sane to leave this empty + * if there's no real init work that has to be done for + * this board. + */ - /* Start-up imaginary PCI ... */ + /* Start-up imaginary PCI ... */ - /* And whatever else ... */ + /* And whatever else ... */ - return 0; -} + return 0; + } Our new imaginary board will also have to tie into the machvec in order for it to be of any use. @@ -172,16 +176,16 @@ sufficient. vector. Note that these prototypes are generated automatically by setting - __IO_PREFIX to something sensible. A typical example would be: + __IO_PREFIX to something sensible. A typical example would be:: #define __IO_PREFIX vapor - #include <asm/io_generic.h> + #include <asm/io_generic.h> somewhere in the board-specific header. Any boards being ported that still have a legacy io.h should remove it entirely and switch to the new model. - Add machine vector definitions to the board's setup.c. At a bare minimum, - this must be defined as something like: + this must be defined as something like:: struct sh_machine_vector mv_vapor __initmv = { .mv_name = "vapor", @@ -202,20 +206,20 @@ Large portions of the build system are now entirely dynamic, and merely require the proper entry here and there in order to get things done. The first thing to do is to add an entry to arch/sh/Kconfig, under the -"System type" menu: +"System type" menu:: -config SH_VAPOR - bool "Vapor" - help - select Vapor if configuring for a FooTech Vaporboard. + config SH_VAPOR + bool "Vapor" + help + select Vapor if configuring for a FooTech Vaporboard. next, this has to be added into arch/sh/Makefile. All boards require a machdir-y entry in order to be built. This entry needs to be the name of the board directory as it appears in arch/sh/boards, even if it is in a sub-directory (in which case, all parent directories below arch/sh/boards/ -need to be listed). For our new board, this entry can look like: +need to be listed). For our new board, this entry can look like:: -machdir-$(CONFIG_SH_VAPOR) += vapor + machdir-$(CONFIG_SH_VAPOR) += vapor provided that we've placed everything in the arch/sh/boards/vapor/ directory. @@ -230,7 +234,7 @@ This is done by adding an entry to the end of the arch/sh/tools/mach-types list. The method for doing this is self explanatory, and so we won't waste space restating it here. After this is done, you will be able to use implicit checks for your board if you need this somewhere throughout the -common code, such as: +common code, such as:: /* Make sure we're on the FooTech Vaporboard */ if (!mach_is_vapor()) @@ -253,16 +257,19 @@ build target, and it will be implicitly listed as such in the help text. Looking at the 'make help' output, you should now see something like: Architecture specific targets (sh): - zImage - Compressed kernel image (arch/sh/boot/zImage) - adx_defconfig - Build for adx - cqreek_defconfig - Build for cqreek - dreamcast_defconfig - Build for dreamcast -... - vapor_defconfig - Build for vapor -which then allows you to do: + ======================= ============================================= + zImage Compressed kernel image (arch/sh/boot/zImage) + adx_defconfig Build for adx + cqreek_defconfig Build for cqreek + dreamcast_defconfig Build for dreamcast + ... + vapor_defconfig Build for vapor + ======================= ============================================= -$ make ARCH=sh CROSS_COMPILE=sh4-linux- vapor_defconfig vmlinux +which then allows you to do:: + + $ make ARCH=sh CROSS_COMPILE=sh4-linux- vapor_defconfig vmlinux which will in turn copy the defconfig for this board, run it through oldconfig (prompting you for any new options since the time of creation), diff --git a/Documentation/sh/register-banks.txt b/Documentation/sh/register-banks.rst index a6719f2f6594..2bef5c8fcbbc 100644 --- a/Documentation/sh/register-banks.txt +++ b/Documentation/sh/register-banks.rst @@ -1,5 +1,8 @@ - Notes on register bank usage in the kernel - ========================================== +.. SPDX-License-Identifier: GPL-2.0 + +========================================== +Notes on register bank usage in the kernel +========================================== Introduction ------------ @@ -23,11 +26,15 @@ Presently the kernel uses several of these registers. - r0_bank, r1_bank (referenced as k0 and k1, used for scratch registers when doing exception handling). + - r2_bank (used to track the EXPEVT/INTEVT code) + - Used by do_IRQ() and friends for doing irq mapping based off of the interrupt exception vector jump table offset + - r6_bank (global interrupt mask) + - The SR.IMASK interrupt handler makes use of this to set the interrupt priority level (used by local_irq_enable()) - - r7_bank (current) + - r7_bank (current) diff --git a/Documentation/sound/alsa-configuration.rst b/Documentation/sound/alsa-configuration.rst index 72f97d4b01a7..c755b1c5e16f 100644 --- a/Documentation/sound/alsa-configuration.rst +++ b/Documentation/sound/alsa-configuration.rst @@ -309,7 +309,7 @@ pcifix This module supports all ADB PCM channels, ac97 mixer, SPDIF, hardware EQ, mpu401, gameport. A3D and wavetable support are still in development. Development and reverse engineering work is being coordinated at -http://savannah.nongnu.org/projects/openvortex/ +https://savannah.nongnu.org/projects/openvortex/ SPDIF output has a copy of the AC97 codec output, unless you use the ``spdif`` pcm device, which allows raw data passthru. The hardware EQ hardware and SPDIF is only present in the Vortex2 and @@ -1575,7 +1575,7 @@ See Documentation/sound/cards/multisound.sh for important information about this driver. Note that it has been discontinued, but the Voyetra Turtle Beach knowledge base entry for it is still available at -http://www.turtlebeach.com +https://www.turtlebeach.com Module snd-msnd-pinnacle ------------------------ @@ -2703,4 +2703,4 @@ Kernel Bugzilla ALSA Developers ML mailto:alsa-devel@alsa-project.org alsa-info.sh script - http://www.alsa-project.org/alsa-info.sh + https://www.alsa-project.org/alsa-info.sh diff --git a/Documentation/sound/cards/audigy-mixer.rst b/Documentation/sound/cards/audigy-mixer.rst index 86213234435f..998f76e19cdd 100644 --- a/Documentation/sound/cards/audigy-mixer.rst +++ b/Documentation/sound/cards/audigy-mixer.rst @@ -331,7 +331,7 @@ WO 9901953 (A1) Execution and Audio Data Sequencing (Jan. 14, 1999) -US Patents (http://www.uspto.gov/) +US Patents (https://www.uspto.gov/) ---------------------------------- US 5925841 diff --git a/Documentation/sound/cards/sb-live-mixer.rst b/Documentation/sound/cards/sb-live-mixer.rst index bcb62fc99bbb..eccb0f0ffd0f 100644 --- a/Documentation/sound/cards/sb-live-mixer.rst +++ b/Documentation/sound/cards/sb-live-mixer.rst @@ -336,7 +336,7 @@ WO 9901953 (A1) Execution and Audio Data Sequencing (Jan. 14, 1999) -US Patents (http://www.uspto.gov/) +US Patents (https://www.uspto.gov/) ---------------------------------- US 5925841 diff --git a/Documentation/sound/designs/compress-offload.rst b/Documentation/sound/designs/compress-offload.rst index ad4bfbdacc83..935f325dbc77 100644 --- a/Documentation/sound/designs/compress-offload.rst +++ b/Documentation/sound/designs/compress-offload.rst @@ -151,6 +151,57 @@ Modifications include: - Addition of encoding options when required (derived from OpenMAX IL) - Addition of rateControlSupported (missing in OpenMAX AL) +State Machine +============= + +The compressed audio stream state machine is described below :: + + +----------+ + | | + | OPEN | + | | + +----------+ + | + | + | compr_set_params() + | + v + compr_free() +----------+ + +------------------------------------| | + | | SETUP | + | +-------------------------| |<-------------------------+ + | | compr_write() +----------+ | + | | ^ | + | | | compr_drain_notify() | + | | | or | + | | | compr_stop() | + | | | | + | | +----------+ | + | | | | | + | | | DRAIN | | + | | | | | + | | +----------+ | + | | ^ | + | | | | + | | | compr_drain() | + | | | | + | v | | + | +----------+ +----------+ | + | | | compr_start() | | compr_stop() | + | | PREPARE |------------------->| RUNNING |--------------------------+ + | | | | | | + | +----------+ +----------+ | + | | | ^ | + | |compr_free() | | | + | | compr_pause() | | compr_resume() | + | | | | | + | v v | | + | +----------+ +----------+ | + | | | | | compr_stop() | + +--->| FREE | | PAUSE |---------------------------+ + | | | | + +----------+ +----------+ + Gapless Playback ================ @@ -199,6 +250,38 @@ Sequence flow for gapless would be: (note: order for partial_drain and write for next track can be reversed as well) +Gapless Playback SM +=================== + +For Gapless, we move from running state to partial drain and back, along +with setting of meta_data and signalling for next track :: + + + +----------+ + compr_drain_notify() | | + +------------------------>| RUNNING | + | | | + | +----------+ + | | + | | + | | compr_next_track() + | | + | V + | +----------+ + | | | + | |NEXT_TRACK| + | | | + | +----------+ + | | + | | + | | compr_partial_drain() + | | + | V + | +----------+ + | | | + +------------------------ | PARTIAL_ | + | DRAIN | + +----------+ Not supported ============= diff --git a/Documentation/sound/designs/procfile.rst b/Documentation/sound/designs/procfile.rst index 29a466851fd2..e9f7e0cbdc5f 100644 --- a/Documentation/sound/designs/procfile.rst +++ b/Documentation/sound/designs/procfile.rst @@ -91,7 +91,7 @@ PCM Proc Files ``card*/pcm*/xrun_debug`` This file appears when ``CONFIG_SND_DEBUG=y`` and - ``CONFIG_PCM_XRUN_DEBUG=y``. + ``CONFIG_SND_PCM_XRUN_DEBUG=y``. This shows the status of xrun (= buffer overrun/xrun) and invalid PCM position debug/check of ALSA PCM middle layer. It takes an integer value, can be changed by writing to this diff --git a/Documentation/sound/hd-audio/notes.rst b/Documentation/sound/hd-audio/notes.rst index 0f3109d9abc8..cf4d7158af78 100644 --- a/Documentation/sound/hd-audio/notes.rst +++ b/Documentation/sound/hd-audio/notes.rst @@ -42,7 +42,7 @@ If you are interested in the deep debugging of HD-audio, read the HD-audio specification at first. The specification is found on Intel's web page, for example: -* http://www.intel.com/standards/hdaudio/ +* https://www.intel.com/standards/hdaudio/ HD-Audio Controller @@ -728,7 +728,7 @@ version can be found on git repository: The script can be fetched directly from the following URL, too: -* http://www.alsa-project.org/alsa-info.sh +* https://www.alsa-project.org/alsa-info.sh Run this script as root, and it will gather the important information such as the module lists, module parameters, proc file contents @@ -818,7 +818,7 @@ proc-compatible output. The hda-analyzer: -* http://git.alsa-project.org/?p=alsa.git;a=tree;f=hda-analyzer +* https://git.alsa-project.org/?p=alsa.git;a=tree;f=hda-analyzer is a part of alsa.git repository in alsa-project.org: diff --git a/Documentation/sound/kernel-api/alsa-driver-api.rst b/Documentation/sound/kernel-api/alsa-driver-api.rst index 14cd138989e3..c8cc651eccf7 100644 --- a/Documentation/sound/kernel-api/alsa-driver-api.rst +++ b/Documentation/sound/kernel-api/alsa-driver-api.rst @@ -99,7 +99,7 @@ ASoC Core API .. kernel-doc:: include/sound/soc.h .. kernel-doc:: sound/soc/soc-core.c .. kernel-doc:: sound/soc/soc-devres.c -.. kernel-doc:: sound/soc/soc-io.c +.. kernel-doc:: sound/soc/soc-component.c .. kernel-doc:: sound/soc/soc-pcm.c .. kernel-doc:: sound/soc/soc-ops.c .. kernel-doc:: sound/soc/soc-compress.c diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst index fa4968817696..aa9d5ab183d2 100644 --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst @@ -3579,7 +3579,7 @@ dependent on the bus. For normal devices, pass the device pointer ``SNDRV_DMA_TYPE_DEV`` type. For the continuous buffer unrelated to the bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type. You can pass NULL to the device pointer in that case, which is the -default mode implying to allocate with ``GFP_KRENEL`` flag. +default mode implying to allocate with ``GFP_KERNEL`` flag. If you need a different GFP flag, you can pass it by encoding the flag into the device pointer via a special macro :c:func:`snd_dma_continuous_data()`. diff --git a/Documentation/sound/soc/dai.rst b/Documentation/sound/soc/dai.rst index 2e99183a7a47..009b07e5a0f3 100644 --- a/Documentation/sound/soc/dai.rst +++ b/Documentation/sound/soc/dai.rst @@ -17,7 +17,7 @@ frame (FRAME) (usually 48kHz) is always driven by the controller. Each AC97 frame is 21uS long and is divided into 13 time slots. The AC97 specification can be found at : -http://www.intel.com/p/en_US/business/design +https://www.intel.com/p/en_US/business/design I2S diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl index c518050ffc3f..00a69aceff44 100755 --- a/Documentation/sphinx/parse-headers.pl +++ b/Documentation/sphinx/parse-headers.pl @@ -393,7 +393,7 @@ Report bugs to Mauro Carvalho Chehab <mchehab@kernel.org> Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>. -License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>. +License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. diff --git a/Documentation/spi/spi-sc18is602.rst b/Documentation/spi/spi-sc18is602.rst index 2a31dc722321..4ab9ca346b44 100644 --- a/Documentation/spi/spi-sc18is602.rst +++ b/Documentation/spi/spi-sc18is602.rst @@ -6,7 +6,7 @@ Supported chips: * NXP SI18IS602/602B/603 - Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf + Datasheet: https://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf Author: Guenter Roeck <linux@roeck-us.net> diff --git a/Documentation/crc32.txt b/Documentation/staging/crc32.rst index 8a6860f33b4e..8a6860f33b4e 100644 --- a/Documentation/crc32.txt +++ b/Documentation/staging/crc32.rst diff --git a/Documentation/staging/index.rst b/Documentation/staging/index.rst new file mode 100644 index 000000000000..abd0d18254d2 --- /dev/null +++ b/Documentation/staging/index.rst @@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Unsorted Documentation +====================== + +.. toctree:: + :maxdepth: 2 + + crc32 + lzo + remoteproc + rpmsg + speculation + static-keys + tee + xz + +Atomic Types +============ + +.. raw:: latex + + \footnotesize + +.. include:: ../atomic_t.txt + :literal: + +.. raw:: latex + + \normalsize + +Atomic bitops +============= + +.. raw:: latex + + \footnotesize + +.. include:: ../atomic_bitops.txt + :literal: + +.. raw:: latex + + \normalsize + +Memory Barriers +=============== + +.. raw:: latex + + \footnotesize + +.. include:: ../memory-barriers.txt + :literal: + +.. raw:: latex + + \normalsize diff --git a/Documentation/lzo.txt b/Documentation/staging/lzo.rst index f65b51523014..f65b51523014 100644 --- a/Documentation/lzo.txt +++ b/Documentation/staging/lzo.rst diff --git a/Documentation/remoteproc.txt b/Documentation/staging/remoteproc.rst index 2be1147256e0..9cccd3dd6a4b 100644 --- a/Documentation/remoteproc.txt +++ b/Documentation/staging/remoteproc.rst @@ -22,7 +22,7 @@ for remote processors that supports this kind of communication. This way, platform-specific remoteproc drivers only need to provide a few low-level handlers, and then all rpmsg drivers will then just work (for more information about the virtio-based rpmsg bus and its drivers, -please read Documentation/rpmsg.txt). +please read Documentation/staging/rpmsg.rst). Registration of other types of virtio devices is now also possible. Firmwares just need to publish what kind of virtio devices do they support, and then remoteproc will add those devices. This makes it possible to reuse the diff --git a/Documentation/rpmsg.txt b/Documentation/staging/rpmsg.rst index 24b7a9e1a5f9..24b7a9e1a5f9 100644 --- a/Documentation/rpmsg.txt +++ b/Documentation/staging/rpmsg.rst diff --git a/Documentation/speculation.txt b/Documentation/staging/speculation.rst index 50d7ea857cff..8045d99bcf12 100644 --- a/Documentation/speculation.txt +++ b/Documentation/staging/speculation.rst @@ -1,10 +1,12 @@ -This document explains potential effects of speculation, and how undesirable -effects can be mitigated portably using common APIs. - =========== Speculation =========== +This document explains potential effects of speculation, and how undesirable +effects can be mitigated portably using common APIs. + +------------------------------------------------------------------------------ + To improve performance and minimize average latencies, many contemporary CPUs employ speculative execution techniques such as branch prediction, performing work which may be discarded at a later stage. diff --git a/Documentation/static-keys.txt b/Documentation/staging/static-keys.rst index 38290b9f25eb..38290b9f25eb 100644 --- a/Documentation/static-keys.txt +++ b/Documentation/staging/static-keys.rst diff --git a/Documentation/tee.txt b/Documentation/staging/tee.rst index c8fad81c4563..4d4b5f889603 100644 --- a/Documentation/tee.txt +++ b/Documentation/staging/tee.rst @@ -53,6 +53,70 @@ clients, forward them to the TEE and send back the results. In the case of supplicants the communication goes in the other direction, the TEE sends requests to the supplicant which then sends back the result. +The TEE kernel interface +======================== + +Kernel provides a TEE bus infrastructure where a Trusted Application is +represented as a device identified via Universally Unique Identifier (UUID) and +client drivers register a table of supported device UUIDs. + +TEE bus infrastructure registers following APIs: + +match(): + iterates over the client driver UUID table to find a corresponding + match for device UUID. If a match is found, then this particular device is + probed via corresponding probe API registered by the client driver. This + process happens whenever a device or a client driver is registered with TEE + bus. + +uevent(): + notifies user-space (udev) whenever a new device is registered on + TEE bus for auto-loading of modularized client drivers. + +TEE bus device enumeration is specific to underlying TEE implementation, so it +is left open for TEE drivers to provide corresponding implementation. + +Then TEE client driver can talk to a matched Trusted Application using APIs +listed in include/linux/tee_drv.h. + +TEE client driver example +------------------------- + +Suppose a TEE client driver needs to communicate with a Trusted Application +having UUID: ``ac6a4085-0e82-4c33-bf98-8eb8e118b6c2``, so driver registration +snippet would look like:: + + static const struct tee_client_device_id client_id_table[] = { + {UUID_INIT(0xac6a4085, 0x0e82, 0x4c33, + 0xbf, 0x98, 0x8e, 0xb8, 0xe1, 0x18, 0xb6, 0xc2)}, + {} + }; + + MODULE_DEVICE_TABLE(tee, client_id_table); + + static struct tee_client_driver client_driver = { + .id_table = client_id_table, + .driver = { + .name = DRIVER_NAME, + .bus = &tee_bus_type, + .probe = client_probe, + .remove = client_remove, + }, + }; + + static int __init client_init(void) + { + return driver_register(&client_driver.driver); + } + + static void __exit client_exit(void) + { + driver_unregister(&client_driver.driver); + } + + module_init(client_init); + module_exit(client_exit); + OP-TEE driver ============= @@ -112,6 +176,14 @@ kernel are handled by the kernel driver. Other RPC messages will be forwarded to tee-supplicant without further involvement of the driver, except switching shared memory buffer representation. +OP-TEE device enumeration +------------------------- + +OP-TEE provides a pseudo Trusted Application: drivers/tee/optee/device.c in +order to support device enumeration. In other words, OP-TEE driver invokes this +application to retrieve a list of Trusted Applications which can be registered +as devices on the TEE bus. + AMD-TEE driver ============== @@ -162,6 +234,7 @@ The AMD-TEE driver packages the command buffer payload for processing in TEE. The command buffer format for the different TEE commands can be found in [7]. The TEE commands supported by AMD-TEE Trusted OS are: + * TEE_CMD_ID_LOAD_TA - loads a Trusted Application (TA) binary into TEE environment. * TEE_CMD_ID_UNLOAD_TA - unloads TA binary from TEE environment. diff --git a/Documentation/xz.txt b/Documentation/staging/xz.rst index b2f5ff12a161..b2f5ff12a161 100644 --- a/Documentation/xz.txt +++ b/Documentation/staging/xz.rst diff --git a/Documentation/timers/no_hz.rst b/Documentation/timers/no_hz.rst index 065db217cb04..c4c70e1aada3 100644 --- a/Documentation/timers/no_hz.rst +++ b/Documentation/timers/no_hz.rst @@ -171,8 +171,6 @@ not come for free: slightly differently than those for non-adaptive-tick CPUs. This might in turn perturb load-balancing of real-time tasks. -6. The LB_BIAS scheduler feature is disabled by adaptive ticks. - Although improvements are expected over time, adaptive ticks is quite useful for many types of real-time and compute-intensive applications. However, the drawbacks listed above mean that adaptive ticks should not diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst index 430a16283103..87cf5c010d5d 100644 --- a/Documentation/trace/ftrace.rst +++ b/Documentation/trace/ftrace.rst @@ -34,7 +34,7 @@ Throughout the kernel is hundreds of static event points that can be enabled via the tracefs file system to see what is going on in certain parts of the kernel. -See events.txt for more information. +See events.rst for more information. Implementation Details @@ -376,11 +376,11 @@ of ftrace. Here is a list of some of the key files: kprobe_events: - Enable dynamic trace points. See kprobetrace.txt. + Enable dynamic trace points. See kprobetrace.rst. kprobe_profile: - Dynamic trace points stats. See kprobetrace.txt. + Dynamic trace points stats. See kprobetrace.rst. max_graph_depth: @@ -561,14 +561,14 @@ of ftrace. Here is a list of some of the key files: trace_marker_raw: - This is similar to trace_marker above, but is meant for for binary data + This is similar to trace_marker above, but is meant for binary data to be written to it, where a tool can be used to parse the data from trace_pipe_raw. uprobe_events: Add dynamic tracepoints in programs. - See uprobetracer.txt + See uprobetracer.rst uprobe_profile: @@ -589,19 +589,19 @@ of ftrace. Here is a list of some of the key files: files at various levels that can enable the tracepoints when a "1" is written to them. - See events.txt for more information. + See events.rst for more information. set_event: By echoing in the event into this file, will enable that event. - See events.txt for more information. + See events.rst for more information. available_events: A list of events that can be enabled in tracing. - See events.txt for more information. + See events.rst for more information. timestamp_mode: @@ -1394,7 +1394,7 @@ an example:: => x86_64_start_reservations => x86_64_start_kernel -Here we see that that we had a latency of 16 microseconds (which is +Here we see that we had a latency of 16 microseconds (which is very good). The _raw_spin_lock_irq in run_timer_softirq disabled interrupts. The difference between the 16 and the displayed timestamp 25us occurred because the clock was incremented @@ -1453,7 +1453,7 @@ function-trace, we get a much larger output:: => __blk_run_queue_uncond => __blk_run_queue => blk_queue_bio - => generic_make_request + => submit_bio_noacct => submit_bio => submit_bh => __ext3_get_inode_loc @@ -1738,7 +1738,7 @@ tracers. => __blk_run_queue_uncond => __blk_run_queue => blk_queue_bio - => generic_make_request + => submit_bio_noacct => submit_bio => submit_bh => ext3_bread diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst index eef840043da9..088c8cce738b 100644 --- a/Documentation/trace/histogram-design.rst +++ b/Documentation/trace/histogram-design.rst @@ -780,7 +780,7 @@ same part of the hist_data->fields[] array as normal values:: Moving on to the sched_switch trigger hist_debug output, in addition to the unused wakeup_lat variable, we see a new section displaying variable references. Variable references are displayed in a separate -section because in addition to to being logically separate from +section because in addition to being logically separate from variables and values, they actually live in a separate hist_data array, var_refs[]. @@ -863,7 +863,7 @@ event. The onmatch() action below basically says that whenever we have a sched_switch event, if we have a matching sched_waking event, in this case if we have a pid in the sched_waking histogram that matches the -the next_pid field on this sched_switch event, we retrieve the +next_pid field on this sched_switch event, we retrieve the variables specified in the wakeup_latency() trace action, and use them to generate a new wakeup_latency event into the trace stream. diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst index fa9e1c730f6a..f634b36fd3aa 100644 --- a/Documentation/trace/index.rst +++ b/Documentation/trace/index.rst @@ -9,6 +9,7 @@ Linux Tracing Technologies tracepoint-analysis ftrace ftrace-uses + kprobes kprobetrace uprobetracer tracepoints @@ -19,9 +20,11 @@ Linux Tracing Technologies events-msr mmiotrace histogram + histogram-design boottime-trace hwlat_detector intel_th + ring-buffer-design stm sys-t coresight/index diff --git a/Documentation/kprobes.txt b/Documentation/trace/kprobes.rst index 8baab8832c5b..b757b6dfd3d4 100644 --- a/Documentation/kprobes.txt +++ b/Documentation/trace/kprobes.rst @@ -20,6 +20,7 @@ Kernel Probes (Kprobes) 10. Deprecated Features Appendix A: The kprobes debugfs interface Appendix B: The kprobes sysctl interface + Appendix C: References Concepts: Kprobes and Return Probes ========================================= @@ -710,13 +711,6 @@ Kretprobes Example See samples/kprobes/kretprobe_example.c -For additional information on Kprobes, refer to the following URLs: - -- http://www-106.ibm.com/developerworks/library/l-kprobes.html?ca=dgr-lnxw42Kprobe -- http://www.redhat.com/magazine/005mar05/features/kprobes/ -- http://www-users.cs.umn.edu/~boutcher/kprobes/ -- http://www.linuxsymposium.org/2006/linuxsymposium_procv2.pdf (pages 101-115) - Deprecated Features =================== @@ -799,3 +793,11 @@ Note that this knob *changes* the optimized state. This means that optimized probes (marked [OPTIMIZED]) will be unoptimized ([OPTIMIZED] tag will be removed). If the knob is turned on, they will be optimized again. +References +========== + +For additional information on Kprobes, refer to the following URLs: + +- https://www.ibm.com/developerworks/library/l-kprobes/index.html +- https://www.kernel.org/doc/ols/2006/ols2006v2-pages-109-124.pdf + diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst index cc4c5fc313df..c1709165c553 100644 --- a/Documentation/trace/kprobetrace.rst +++ b/Documentation/trace/kprobetrace.rst @@ -40,7 +40,7 @@ Synopsis of kprobe_events MEMADDR : Address where the probe is inserted. MAXACTIVE : Maximum number of instances of the specified function that can be probed simultaneously, or 0 for the default value - as defined in Documentation/kprobes.txt section 1.3.1. + as defined in Documentation/staging/kprobes.rst section 1.3.1. FETCHARGS : Arguments. Each probe can have up to 128 args. %REG : Fetch register REG diff --git a/Documentation/trace/ring-buffer-design.txt b/Documentation/trace/ring-buffer-design.rst index 2d53c6f25b91..9c8d22a53d6c 100644 --- a/Documentation/trace/ring-buffer-design.txt +++ b/Documentation/trace/ring-buffer-design.rst @@ -1,11 +1,39 @@ - Lockless Ring Buffer Design - =========================== +.. This file is dual-licensed: you can use it either under the terms +.. of the GPL 2.0 or the GFDL 1.2 license, at your option. Note that this +.. dual licensing only applies to this file, and not this project as a +.. whole. +.. +.. a) This file is free software; you can redistribute it and/or +.. modify it under the terms of the GNU General Public License as +.. published by the Free Software Foundation version 2 of +.. the License. +.. +.. This file is distributed in the hope that it will be useful, +.. but WITHOUT ANY WARRANTY; without even the implied warranty of +.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.. GNU General Public License for more details. +.. +.. Or, alternatively, +.. +.. b) Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.2 version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GPL-2.0 OR GFDL-1.2 WITH no-invariant-sections + +=========================== +Lockless Ring Buffer Design +=========================== Copyright 2009 Red Hat Inc. - Author: Steven Rostedt <srostedt@redhat.com> - License: The GNU Free Documentation License, Version 1.2 - (dual licensed under the GPL v2) -Reviewers: Mathieu Desnoyers, Huang Ying, Hidetoshi Seto, + +:Author: Steven Rostedt <srostedt@redhat.com> +:License: The GNU Free Documentation License, Version 1.2 + (dual licensed under the GPL v2) +:Reviewers: Mathieu Desnoyers, Huang Ying, Hidetoshi Seto, and Frederic Weisbecker. @@ -14,37 +42,50 @@ Written for: 2.6.31 Terminology used in this Document --------------------------------- -tail - where new writes happen in the ring buffer. +tail + - where new writes happen in the ring buffer. -head - where new reads happen in the ring buffer. +head + - where new reads happen in the ring buffer. -producer - the task that writes into the ring buffer (same as writer) +producer + - the task that writes into the ring buffer (same as writer) -writer - same as producer +writer + - same as producer -consumer - the task that reads from the buffer (same as reader) +consumer + - the task that reads from the buffer (same as reader) -reader - same as consumer. +reader + - same as consumer. -reader_page - A page outside the ring buffer used solely (for the most part) - by the reader. +reader_page + - A page outside the ring buffer used solely (for the most part) + by the reader. -head_page - a pointer to the page that the reader will use next +head_page + - a pointer to the page that the reader will use next -tail_page - a pointer to the page that will be written to next +tail_page + - a pointer to the page that will be written to next -commit_page - a pointer to the page with the last finished non-nested write. +commit_page + - a pointer to the page with the last finished non-nested write. -cmpxchg - hardware-assisted atomic transaction that performs the following: +cmpxchg + - hardware-assisted atomic transaction that performs the following:: - A = B if previous A == C + A = B if previous A == C - R = cmpxchg(A, C, B) is saying that we replace A with B if and only if - current A is equal to C, and we put the old (current) A into R + R = cmpxchg(A, C, B) is saying that we replace A with B if and only + if current A is equal to C, and we put the old (current) + A into R - R gets the previous A regardless if A is updated with B or not. + R gets the previous A regardless if A is updated with B or not. - To see if the update was successful a compare of R == C may be used. + To see if the update was successful a compare of ``R == C`` + may be used. The Generic Ring Buffer ----------------------- @@ -64,7 +105,7 @@ No two writers can write at the same time (on the same per-cpu buffer), but a writer may interrupt another writer, but it must finish writing before the previous writer may continue. This is very important to the algorithm. The writers act like a "stack". The way interrupts works -enforces this behavior. +enforces this behavior:: writer1 start @@ -115,6 +156,8 @@ A sample of how the reader page is swapped: Note this does not show the head page in the buffer, it is for demonstrating a swap only. +:: + +------+ |reader| RING BUFFER |page | @@ -172,21 +215,22 @@ only. It is possible that the page swapped is the commit page and the tail page, if what is in the ring buffer is less than what is held in a buffer page. - - reader page commit page tail page - | | | - v | | - +---+ | | - | |<----------+ | - | |<------------------------+ - | |------+ - +---+ | - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |--->| |--->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ +:: + + reader page commit page tail page + | | | + v | | + +---+ | | + | |<----------+ | + | |<------------------------+ + | |------+ + +---+ | + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |--->| |--->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ This case is still valid for this algorithm. When the writer leaves the page, it simply goes into the ring buffer @@ -196,15 +240,19 @@ buffer. The main pointers: - reader page - The page used solely by the reader and is not part - of the ring buffer (may be swapped in) + reader page + - The page used solely by the reader and is not part + of the ring buffer (may be swapped in) - head page - the next page in the ring buffer that will be swapped + head page + - the next page in the ring buffer that will be swapped with the reader page. - tail page - the page where the next write will take place. + tail page + - the page where the next write will take place. - commit page - the page that last finished a write. + commit page + - the page that last finished a write. The commit page only is updated by the outermost writer in the writer stack. A writer that preempts another writer will not move the @@ -219,7 +267,7 @@ transaction. If another write happens it must finish before continuing with the previous write. - Write reserve: + Write reserve:: Buffer page +---------+ @@ -230,7 +278,7 @@ with the previous write. | empty | +---------+ - Write commit: + Write commit:: Buffer page +---------+ @@ -242,7 +290,7 @@ with the previous write. +---------+ - If a write happens after the first reserve: + If a write happens after the first reserve:: Buffer page +---------+ @@ -253,7 +301,7 @@ with the previous write. |reserved | +---------+ <--- tail pointer - After second writer commits: + After second writer commits:: Buffer page @@ -266,7 +314,7 @@ with the previous write. |commit | +---------+ <--- tail pointer - When the first writer commits: + When the first writer commits:: Buffer page +---------+ @@ -292,21 +340,22 @@ be several pages ahead. If the tail page catches up to the commit page then no more writes may take place (regardless of the mode of the ring buffer: overwrite and produce/consumer). -The order of pages is: +The order of pages is:: head page commit page tail page -Possible scenario: - tail page - head page commit page | - | | | - v v v - +---+ +---+ +---+ +---+ -<---| |--->| |--->| |--->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ +Possible scenario:: + + tail page + head page commit page | + | | | + v v v + +---+ +---+ +---+ +---+ + <---| |--->| |--->| |--->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ There is a special case that the head page is after either the commit page and possibly the tail page. That is when the commit (and tail) page has been @@ -315,24 +364,25 @@ part of the ring buffer, but the reader page is not. Whenever there has been less than a full page that has been committed inside the ring buffer, and a reader swaps out a page, it will be swapping out the commit page. - - reader page commit page tail page - | | | - v | | - +---+ | | - | |<----------+ | - | |<------------------------+ - | |------+ - +---+ | - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |--->| |--->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ - ^ - | - head page +:: + + reader page commit page tail page + | | | + v | | + +---+ | | + | |<----------+ | + | |<------------------------+ + | |------+ + +---+ | + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |--->| |--->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ + ^ + | + head page In this case, the head page will not move when the tail and commit @@ -347,42 +397,42 @@ When the tail meets the head page, if the buffer is in overwrite mode, the head page will be pushed ahead one. If the buffer is in producer/consumer mode, the write will fail. -Overwrite mode: - - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |--->| |--->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ - ^ - | - head page - - - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |--->| |--->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ - ^ - | - head page - - - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |--->| |--->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ - ^ - | - head page +Overwrite mode:: + + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |--->| |--->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ + ^ + | + head page + + + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |--->| |--->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ + ^ + | + head page + + + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |--->| |--->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ + ^ + | + head page Note, the reader page will still point to the previous head page. But when a swap takes place, it will use the most recent head page. @@ -397,7 +447,7 @@ State flags are placed inside the pointer to the page. To do this, each page must be aligned in memory by 4 bytes. This will allow the 2 least significant bits of the address to be used as flags, since they will always be zero for the address. To get the address, -simply mask out the flags. +simply mask out the flags:: MASK = ~3 @@ -405,24 +455,27 @@ simply mask out the flags. Two flags will be kept by these two bits: - HEADER - the page being pointed to is a head page + HEADER + - the page being pointed to is a head page - UPDATE - the page being pointed to is being updated by a writer + UPDATE + - the page being pointed to is being updated by a writer and was or is about to be a head page. +:: - reader page - | - v - +---+ - | |------+ - +---+ | - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-H->| |--->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + reader page + | + v + +---+ + | |------+ + +---+ | + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-H->| |--->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ The above pointer "-H->" would have the HEADER flag set. That is @@ -430,24 +483,24 @@ the next page is the next page to be swapped out by the reader. This pointer means the next page is the head page. When the tail page meets the head pointer, it will use cmpxchg to -change the pointer to the UPDATE state: +change the pointer to the UPDATE state:: - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-H->| |--->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-H->| |--->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-U->| |--->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-U->| |--->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ "-U->" represents a pointer in the UPDATE state. @@ -462,7 +515,7 @@ head page does not have the HEADER flag set, the compare will fail and the reader will need to look for the new head page and try again. Note, the flags UPDATE and HEADER are never set at the same time. -The reader swaps the reader page as follows: +The reader swaps the reader page as follows:: +------+ |reader| RING BUFFER @@ -477,7 +530,7 @@ The reader swaps the reader page as follows: +-----H-------------+ The reader sets the reader page next pointer as HEADER to the page after -the head page. +the head page:: +------+ @@ -495,7 +548,7 @@ the head page. It does a cmpxchg with the pointer to the previous head page to make it point to the reader page. Note that the new pointer does not have the HEADER -flag set. This action atomically moves the head page forward. +flag set. This action atomically moves the head page forward:: +------+ |reader| RING BUFFER @@ -511,7 +564,7 @@ flag set. This action atomically moves the head page forward. +------------------------------------+ After the new head page is set, the previous pointer of the head page is -updated to the reader page. +updated to the reader page:: +------+ |reader| RING BUFFER @@ -548,7 +601,7 @@ prev pointers may not. Note, the way to determine a reader page is simply by examining the previous pointer of the page. If the next pointer of the previous page does not -point back to the original page, then the original page is a reader page: +point back to the original page, then the original page is a reader page:: +--------+ @@ -572,54 +625,54 @@ not be able to swap the head page from the buffer, nor will it be able to move the head page, until the writer is finished with the move. This eliminates any races that the reader can have on the writer. The reader -must spin, and this is why the reader cannot preempt the writer. - - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-H->| |--->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ - - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-U->| |--->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ - -The following page will be made into the new head page. - - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-U->| |-H->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ +must spin, and this is why the reader cannot preempt the writer:: + + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-H->| |--->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ + + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-U->| |--->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ + +The following page will be made into the new head page:: + + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-U->| |-H->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ After the new head page has been set, we can set the old head page -pointer back to NORMAL. +pointer back to NORMAL:: - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |--->| |-H->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |--->| |-H->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ -After the head page has been moved, the tail page may now move forward. +After the head page has been moved, the tail page may now move forward:: - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |--->| |-H->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |--->| |-H->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ The above are the trivial updates. Now for the more complex scenarios. @@ -630,26 +683,26 @@ tail page may make it all the way around the buffer and meet the commit page. At this time, we must start dropping writes (usually with some kind of warning to the user). But what happens if the commit was still on the reader page? The commit page is not part of the ring buffer. The tail page -must account for this. - - - reader page commit page - | | - v | - +---+ | - | |<----------+ - | | - | |------+ - +---+ | - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-H->| |--->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ - ^ - | - tail page +must account for this:: + + + reader page commit page + | | + v | + +---+ | + | |<----------+ + | | + | |------+ + +---+ | + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-H->| |--->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ + ^ + | + tail page If the tail page were to simply push the head page forward, the commit when leaving the reader page would not be pointing to the correct page. @@ -676,7 +729,7 @@ the head page if the head page is the next page. If the head page is not the next page, the tail page is simply updated with a cmpxchg. Only writers move the tail page. This must be done atomically to protect -against nested writers. +against nested writers:: temp_page = tail_page next_page = temp_page->next @@ -684,54 +737,54 @@ against nested writers. The above will update the tail page if it is still pointing to the expected page. If this fails, a nested write pushed it forward, the current write -does not need to push it. - - - temp page - | - v - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |--->| |--->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ - -Nested write comes in and moves the tail page forward: - - tail page (moved by nested writer) - temp page | - | | - v v - +---+ +---+ +---+ +---+ -<---| |--->| |--->| |--->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ +does not need to push it:: + + + temp page + | + v + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |--->| |--->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ + +Nested write comes in and moves the tail page forward:: + + tail page (moved by nested writer) + temp page | + | | + v v + +---+ +---+ +---+ +---+ + <---| |--->| |--->| |--->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ The above would fail the cmpxchg, but since the tail page has already been moved forward, the writer will just try again to reserve storage on the new tail page. -But the moving of the head page is a bit more complex. +But the moving of the head page is a bit more complex:: - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-H->| |--->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-H->| |--->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ -The write converts the head page pointer to UPDATE. +The write converts the head page pointer to UPDATE:: - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-U->| |--->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-U->| |--->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ But if a nested writer preempts here, it will see that the next page is a head page, but it is also nested. It will detect that @@ -739,217 +792,216 @@ it is nested and will save that information. The detection is the fact that it sees the UPDATE flag instead of a HEADER or NORMAL pointer. -The nested writer will set the new head page pointer. +The nested writer will set the new head page pointer:: - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-U->| |-H->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-U->| |-H->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ But it will not reset the update back to normal. Only the writer that converted a pointer from HEAD to UPDATE will convert it back -to NORMAL. +to NORMAL:: - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-U->| |-H->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-U->| |-H->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ After the nested writer finishes, the outermost writer will convert -the UPDATE pointer to NORMAL. +the UPDATE pointer to NORMAL:: - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |--->| |-H->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |--->| |-H->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ It can be even more complex if several nested writes came in and moved -the tail page ahead several pages: +the tail page ahead several pages:: -(first writer) + (first writer) - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-H->| |--->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-H->| |--->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ -The write converts the head page pointer to UPDATE. +The write converts the head page pointer to UPDATE:: - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-U->| |--->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-U->| |--->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ Next writer comes in, and sees the update and sets up the new -head page. +head page:: -(second writer) + (second writer) - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-U->| |-H->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-U->| |-H->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ The nested writer moves the tail page forward. But does not set the old -update page to NORMAL because it is not the outermost writer. +update page to NORMAL because it is not the outermost writer:: - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-U->| |-H->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-U->| |-H->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ Another writer preempts and sees the page after the tail page is a head page. -It changes it from HEAD to UPDATE. +It changes it from HEAD to UPDATE:: -(third writer) + (third writer) - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-U->| |-U->| |---> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-U->| |-U->| |---> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ -The writer will move the head page forward: +The writer will move the head page forward:: -(third writer) + (third writer) - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-U->| |-U->| |-H-> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-U->| |-U->| |-H-> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ But now that the third writer did change the HEAD flag to UPDATE it -will convert it to normal: +will convert it to normal:: -(third writer) + (third writer) - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-U->| |--->| |-H-> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-U->| |--->| |-H-> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ -Then it will move the tail page, and return back to the second writer. +Then it will move the tail page, and return back to the second writer:: -(second writer) + (second writer) - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-U->| |--->| |-H-> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-U->| |--->| |-H-> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ The second writer will fail to move the tail page because it was already moved, so it will try again and add its data to the new tail page. -It will return to the first writer. +It will return to the first writer:: -(first writer) + (first writer) - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-U->| |--->| |-H-> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-U->| |--->| |-H-> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ The first writer cannot know atomically if the tail page moved while it updates the HEAD page. It will then update the head page to -what it thinks is the new head page. +what it thinks is the new head page:: -(first writer) + (first writer) - tail page - | - v - +---+ +---+ +---+ +---+ -<---| |--->| |-U->| |-H->| |-H-> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + tail page + | + v + +---+ +---+ +---+ +---+ + <---| |--->| |-U->| |-H->| |-H-> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ Since the cmpxchg returns the old value of the pointer the first writer will see it succeeded in updating the pointer from NORMAL to HEAD. But as we can see, this is not good enough. It must also check to see -if the tail page is either where it use to be or on the next page: +if the tail page is either where it use to be or on the next page:: -(first writer) + (first writer) - A B tail page - | | | - v v v - +---+ +---+ +---+ +---+ -<---| |--->| |-U->| |-H->| |-H-> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + A B tail page + | | | + v v v + +---+ +---+ +---+ +---+ + <---| |--->| |-U->| |-H->| |-H-> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ If tail page != A and tail page != B, then it must reset the pointer back to NORMAL. The fact that it only needs to worry about nested -writers means that it only needs to check this after setting the HEAD page. +writers means that it only needs to check this after setting the HEAD page:: -(first writer) + (first writer) - A B tail page - | | | - v v v - +---+ +---+ +---+ +---+ -<---| |--->| |-U->| |--->| |-H-> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + A B tail page + | | | + v v v + +---+ +---+ +---+ +---+ + <---| |--->| |-U->| |--->| |-H-> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ Now the writer can update the head page. This is also why the head page must remain in UPDATE and only reset by the outermost writer. This prevents -the reader from seeing the incorrect head page. - +the reader from seeing the incorrect head page:: -(first writer) - A B tail page - | | | - v v v - +---+ +---+ +---+ +---+ -<---| |--->| |--->| |--->| |-H-> ---->| |<---| |<---| |<---| |<--- - +---+ +---+ +---+ +---+ + (first writer) + A B tail page + | | | + v v v + +---+ +---+ +---+ +---+ + <---| |--->| |--->| |--->| |-H-> + --->| |<---| |<---| |<---| |<--- + +---+ +---+ +---+ +---+ diff --git a/Documentation/trace/stm.rst b/Documentation/trace/stm.rst index 99f99963e5e7..1ed49dde04fc 100644 --- a/Documentation/trace/stm.rst +++ b/Documentation/trace/stm.rst @@ -33,8 +33,8 @@ This policy is a tree structure containing rules (policy_node) that have a name (string identifier) and a range of masters and channels associated with it, located in "stp-policy" subsystem directory in configfs. The topmost directory's name (the policy) is formatted as -the STM device name to which this policy applies and and arbitrary -string identifier separated by a stop. From the examle above, a rule +the STM device name to which this policy applies and an arbitrary +string identifier separated by a stop. From the example above, a rule may look like this:: $ ls /config/stp-policy/dummy_stm.my-policy/user diff --git a/Documentation/translations/it_IT/core-api/index.rst b/Documentation/translations/it_IT/core-api/index.rst new file mode 100644 index 000000000000..cc4c4328ad03 --- /dev/null +++ b/Documentation/translations/it_IT/core-api/index.rst @@ -0,0 +1,18 @@ +=============================== +Documentazione dell'API di base +=============================== + +Utilità di base +=============== + +.. toctree:: + :maxdepth: 1 + + symbol-namespaces + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/it_IT/core-api/symbol-namespaces.rst b/Documentation/translations/it_IT/core-api/symbol-namespaces.rst new file mode 100644 index 000000000000..aa851a57a4b0 --- /dev/null +++ b/Documentation/translations/it_IT/core-api/symbol-namespaces.rst @@ -0,0 +1,166 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :doc:`../../../core-api/symbol-namespaces` +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> + +=========================== +Spazio dei nomi dei simboli +=========================== + +Questo documento descrive come usare lo spazio dei nomi dei simboli +per strutturare quello che viene esportato internamente al kernel +grazie alle macro della famiglia EXPORT_SYMBOL(). + +1. Introduzione +=============== + +Lo spazio dei nomi dei simboli è stato introdotto come mezzo per strutturare +l'API esposta internamente al kernel. Permette ai manutentori di un +sottosistema di organizzare i simboli esportati in diversi spazi di +nomi. Questo meccanismo è utile per la documentazione (pensate ad +esempio allo spazio dei nomi SUBSYSTEM_DEBUG) così come per limitare +la disponibilità di un gruppo di simboli in altre parti del kernel. Ad +oggi, i moduli che usano simboli esportati da uno spazio di nomi +devono prima importare detto spazio. Altrimenti il kernel, a seconda +della configurazione, potrebbe rifiutare di caricare il modulo o +avvisare l'utente di un'importazione mancante. + +2. Come definire uno spazio dei nomi dei simboli +================================================ + +I simboli possono essere esportati in spazi dei nomi usando diversi +meccanismi. Tutti questi meccanismi cambiano il modo in cui +EXPORT_SYMBOL e simili vengono guidati verso la creazione di voci in ksymtab. + +2.1 Usare le macro EXPORT_SYMBOL +================================ + +In aggiunta alle macro EXPORT_SYMBOL() e EXPORT_SYMBOL_GPL(), che permettono +di esportare simboli del kernel nella rispettiva tabella, ci sono +varianti che permettono di esportare simboli all'interno di uno spazio dei +nomi: EXPORT_SYMBOL_NS() ed EXPORT_SYMBOL_NS_GPL(). Queste macro richiedono un +argomento aggiuntivo: lo spazio dei nomi. +Tenete presente che per via dell'espansione delle macro questo argomento deve +essere un simbolo di preprocessore. Per esempio per esportare il +simbolo `usb_stor_suspend` nello spazio dei nomi `USB_STORAGE` usate:: + + EXPORT_SYMBOL_NS(usb_stor_suspend, USB_STORAGE); + +Di conseguenza, nella tabella dei simboli del kernel ci sarà una voce +rappresentata dalla struttura `kernel_symbol` che avrà il campo +`namespace` (spazio dei nomi) impostato. Un simbolo esportato senza uno spazio +dei nomi avrà questo campo impostato a `NULL`. Non esiste uno spazio dei nomi +di base. Il programma `modpost` e il codice in kernel/module.c usano lo spazio +dei nomi, rispettivamente, durante la compilazione e durante il caricamento +di un modulo. + +2.2 Usare il simbolo di preprocessore DEFAULT_SYMBOL_NAMESPACE +============================================================== + +Definire lo spazio dei nomi per tutti i simboli di un sottosistema può essere +logorante e di difficile manutenzione. Perciò è stato fornito un simbolo +di preprocessore di base (DEFAULT_SYMBOL_NAMESPACE), che, se impostato, +diventa lo spazio dei simboli di base per tutti gli usi di EXPORT_SYMBOL() +ed EXPORT_SYMBOL_GPL() che non specificano esplicitamente uno spazio dei nomi. + +Ci sono molti modi per specificare questo simbolo di preprocessore e il loro +uso dipende dalle preferenze del manutentore di un sottosistema. La prima +possibilità è quella di definire il simbolo nel `Makefile` del sottosistema. +Per esempio per esportare tutti i simboli definiti in usb-common nello spazio +dei nomi USB_COMMON, si può aggiungere la seguente linea in +drivers/usb/common/Makefile:: + + ccflags-y += -DDEFAULT_SYMBOL_NAMESPACE=USB_COMMON + +Questo cambierà tutte le macro EXPORT_SYMBOL() ed EXPORT_SYMBOL_GPL(). Invece, +un simbolo esportato con EXPORT_SYMBOL_NS() non verrà cambiato e il simbolo +verrà esportato nello spazio dei nomi indicato. + +Una seconda possibilità è quella di definire il simbolo di preprocessore +direttamente nei file da compilare. L'esempio precedente diventerebbe:: + + #undef DEFAULT_SYMBOL_NAMESPACE + #define DEFAULT_SYMBOL_NAMESPACE USB_COMMON + +Questo va messo prima di un qualsiasi uso di EXPORT_SYMBOL. + +3. Come usare i simboli esportati attraverso uno spazio dei nomi +================================================================ + +Per usare i simboli esportati da uno spazio dei nomi, i moduli del +kernel devono esplicitamente importare il relativo spazio dei nomi; altrimenti +il kernel potrebbe rifiutarsi di caricare il modulo. Il codice del +modulo deve usare la macro MODULE_IMPORT_NS per importare lo spazio +dei nomi che contiene i simboli desiderati. Per esempio un modulo che +usa il simbolo usb_stor_suspend deve importare lo spazio dei nomi +USB_STORAGE usando la seguente dichiarazione:: + + MODULE_IMPORT_NS(USB_STORAGE); + +Questo creerà un'etichetta `modinfo` per ogni spazio dei nomi +importato. Un risvolto di questo fatto è che gli spazi dei +nomi importati da un modulo possono essere ispezionati tramite +modinfo:: + + $ modinfo drivers/usb/storage/ums-karma.ko + [...] + import_ns: USB_STORAGE + [...] + + +Si consiglia di posizionare la dichiarazione MODULE_IMPORT_NS() vicino +ai metadati del modulo come MODULE_AUTHOR() o MODULE_LICENSE(). Fate +riferimento alla sezione 5. per creare automaticamente le importazioni +mancanti. + +4. Caricare moduli che usano simboli provenienti da spazi dei nomi +================================================================== + +Quando un modulo viene caricato (per esempio usando `insmod`), il kernel +verificherà la disponibilità di ogni simbolo usato e se lo spazio dei nomi +che potrebbe contenerli è stato importato. Il comportamento di base del kernel +è di rifiutarsi di caricare quei moduli che non importano tutti gli spazi dei +nomi necessari. L'errore verrà annotato e il caricamento fallirà con l'errore +EINVAL. Per caricare i moduli che non soddisfano questo requisito esiste +un'opzione di configurazione: impostare +MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS=y caricherà i moduli comunque ma +emetterà un avviso. + +5. Creare automaticamente la dichiarazione MODULE_IMPORT_NS +=========================================================== + +La mancanza di un'importazione può essere individuata facilmente al momento +della compilazione. Infatti, modpost emetterà un avviso se il modulo usa +un simbolo da uno spazio dei nomi che non è stato importato. +La dichiarazione MODULE_IMPORT_NS() viene solitamente aggiunta in un posto +ben definito (assieme agli altri metadati del modulo). Per facilitare +la vita di chi scrive moduli (e i manutentori di sottosistemi), esistono uno +script e un target make per correggere le importazioni mancanti. Questo può +essere fatto con:: + + $ make nsdeps + +Lo scenario tipico di chi scrive un modulo potrebbe essere:: + + - scrivere codice che dipende da un simbolo appartenente ad uno spazio + dei nomi non importato + - eseguire `make` + - aver notato un avviso da modpost che parla di un'importazione + mancante + - eseguire `make nsdeps` per aggiungere import nel posto giusto + +Per i manutentori di sottosistemi che vogliono aggiungere uno spazio dei nomi, +l'approccio è simile. Di nuovo, eseguendo `make nsdeps` aggiungerà le +importazioni mancanti nei moduli inclusi nel kernel:: + + - spostare o aggiungere simboli ad uno spazio dei nomi (per esempio + usando EXPORT_SYMBOL_NS()) + - eseguire `make` (preferibilmente con allmodconfig per coprire tutti + i moduli del kernel) + - aver notato un avviso da modpost che parla di un'importazione + mancante + - eseguire `make nsdeps` per aggiungere import nel posto giusto + +Potete anche eseguire nsdeps per moduli esterni. Solitamente si usa così:: + + $ make -C <path_to_kernel_src> M=$PWD nsdeps diff --git a/Documentation/translations/it_IT/index.rst b/Documentation/translations/it_IT/index.rst index 409eaac03e9f..bb8fa7346939 100644 --- a/Documentation/translations/it_IT/index.rst +++ b/Documentation/translations/it_IT/index.rst @@ -121,9 +121,10 @@ file sorgenti, informazioni aggiuntive vengono aggiunte solo se necessarie (o almeno ci proviamo — probabilmente *non* tutto quello che è davvero necessario). -.. warning:: +.. toctree:: + :maxdepth: 2 - TODO ancora da tradurre + core-api/index Documentazione specifica per architettura ----------------------------------------- diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst index e9a2e92134f0..6aab27a8d323 100644 --- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst @@ -634,7 +634,7 @@ Definita in ``include/linux/export.h`` Questa è una variate di `EXPORT_SYMBOL()` che permette di specificare uno spazio dei nomi. Lo spazio dei nomi è documentato in -:doc:`../../../core-api/symbol-namespaces` +:doc:`../core-api/symbol-namespaces` :c:func:`EXPORT_SYMBOL_NS_GPL()` -------------------------------- @@ -643,7 +643,7 @@ Definita in ``include/linux/export.h`` Questa è una variate di `EXPORT_SYMBOL_GPL()` che permette di specificare uno spazio dei nomi. Lo spazio dei nomi è documentato in -:doc:`../../../core-api/symbol-namespaces` +:doc:`../core-api/symbol-namespaces` Procedure e convenzioni ======================= diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst index 6f4f85832dee..a346f1f2ce21 100644 --- a/Documentation/translations/it_IT/process/coding-style.rst +++ b/Documentation/translations/it_IT/process/coding-style.rst @@ -1097,7 +1097,7 @@ la direttiva condizionale su di esse. Se avete una variabile o funzione che potrebbe non essere usata in alcune configurazioni, e quindi il compilatore potrebbe avvisarvi circa la definizione -inutilizzata, marcate questa definizione come __maybe_used piuttosto che +inutilizzata, marcate questa definizione come __maybe_unused piuttosto che racchiuderla in una direttiva condizionale del preprocessore. (Comunque, se una variabile o funzione è *sempre* inutilizzata, rimuovetela). diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt index 34d041d68f78..9dcc7c9d52e6 100644 --- a/Documentation/translations/ko_KR/memory-barriers.txt +++ b/Documentation/translations/ko_KR/memory-barriers.txt @@ -570,14 +570,14 @@ ACQUIRE 는 해당 오í¼ë ˆì´ì…˜ì˜ 로드 부분ì—만 ì ìš©ë˜ê³ RELEASE ë [*] 버스 ë§ˆìŠ¤í„°ë§ DMA 와 ì¼ê´€ì„±ì— 대해서는 다ìŒì„ ì°¸ê³ í•˜ì‹œê¸° ë°”ëžë‹ˆë‹¤: Documentation/driver-api/pci/pci.rst - Documentation/DMA-API-HOWTO.txt - Documentation/DMA-API.txt + Documentation/core-api/dma-api-howto.rst + Documentation/core-api/dma-api.rst ë°ì´í„° ì˜ì¡´ì„± 배리어 (ì—사ì ) ----------------------------- -리눅스 ì»¤ë„ v4.15 기준으로, smp_read_barrier_depends() ê°€ READ_ONCE() ì— +리눅스 ì»¤ë„ v4.15 기준으로, smp_mb() ê°€ DEC Alpha ìš© READ_ONCE() ì½”ë“œì— ì¶”ê°€ë˜ì—ˆëŠ”ë°, ì´ëŠ” ì´ ì„¹ì…˜ì— ì£¼ì˜ë¥¼ 기울여야 하는 ì‚¬ëžŒë“¤ì€ DEC Alpha 아키í…ì³ ì „ìš© 코드를 만드는 사람들과 READ_ONCE() ìžì²´ë¥¼ 만드는 사람들 ë¿ìž„ì„ ì˜ë¯¸í•©ë‹ˆë‹¤. 그런 ë¶„ë“¤ì„ ìœ„í•´, ê·¸ë¦¬ê³ ì—ì‚¬ì— ê´€ì‹¬ 있는 ë¶„ë“¤ì„ ìœ„í•´, 여기 ë°ì´í„° ì˜ì¡´ì„± @@ -1907,7 +1907,7 @@ Mandatory ë°°ë¦¬ì–´ë“¤ì€ SMP 시스템ì—ì„œë„ UP 시스템ì—ì„œë„ SMP íš¨ê³ writel_relaxed() 와 ê°™ì€ ì™„í™”ëœ I/O ì ‘ê·¼ìžë“¤ì— 대한 ìžì„¸í•œ ë‚´ìš©ì„ ìœ„í•´ì„œëŠ” "ì»¤ë„ I/O ë°°ë¦¬ì–´ì˜ íš¨ê³¼" 섹션ì„, consistent memory ì— ëŒ€í•œ ìžì„¸í•œ ë‚´ìš©ì„ - ìœ„í•´ì„ Documentation/DMA-API.txt 문서를 ì°¸ê³ í•˜ì„¸ìš”. + ìœ„í•´ì„ Documentation/core-api/dma-api.rst 문서를 ì°¸ê³ í•˜ì„¸ìš”. ========================= @@ -2664,144 +2664,6 @@ CPU 코어는 í”„ë¡œê·¸ëž¨ì˜ ì¸ê³¼ì„±ì´ ìœ ì§€ëœë‹¤ê³ 만 여겨진다면 ì ìˆ˜ë„ ìžˆìŠµë‹ˆë‹¤. -ìºì‹œ ì¼ê´€ì„± ------------ - -하지만 ì‚¶ì€ ì•žì—ì„œ ì´ì•¼ê¸°í•œ 것처럼 단순하지 않습니다: ìºì‹œë“¤ì€ ì¼ê´€ì ì¼ ê²ƒìœ¼ë¡œ -기대ë˜ì§€ë§Œ, ê·¸ ì¼ê´€ì„±ì´ 순서ì—ë„ ì ìš©ë ê±°ë¼ëŠ” ë³´ìž¥ì€ ì—†ìŠµë‹ˆë‹¤. í•œ CPU ì—ì„œ -만들어진 변경 사í•ì€ 최종ì 으로는 ì‹œìŠ¤í…œì˜ ëª¨ë“ CPU ì—게 보여지게 ë˜ì§€ë§Œ, 다른 -CPU 들ì—ê²Œë„ ê°™ì€ ìˆœì„œë¡œ ë³´ì´ê²Œ ë ê±°ë¼ëŠ” ë³´ìž¥ì€ ì—†ë‹¤ëŠ” 뜻입니다. - - -ë‘ê°œì˜ CPU (1 & 2) ê°€ ë‹¬ë ¤ ìžˆê³ , ê° CPU ì— ë‘ê°œì˜ ë°ì´í„° ìºì‹œ(CPU 1 ì€ A/B 를, -CPU 2 는 C/D 를 갖습니다)ê°€ ë³‘ë ¬ë¡œ ì—°ê²°ë˜ì–´ 있는 ì‹œìŠ¤í…œì„ ë‹¤ë£¬ë‹¤ê³ ìƒê°í•´ -봅시다: - - : - : +--------+ - : +---------+ | | - +--------+ : +--->| Cache A |<------->| | - | | : | +---------+ | | - | CPU 1 |<---+ | | - | | : | +---------+ | | - +--------+ : +--->| Cache B |<------->| | - : +---------+ | | - : | Memory | - : +---------+ | System | - +--------+ : +--->| Cache C |<------->| | - | | : | +---------+ | | - | CPU 2 |<---+ | | - | | : | +---------+ | | - +--------+ : +--->| Cache D |<------->| | - : +---------+ | | - : +--------+ - : - -ì´ ì‹œìŠ¤í…œì´ ë‹¤ìŒê³¼ ê°™ì€ íŠ¹ì„±ì„ ê°–ëŠ”ë‹¤ ìƒê°í•´ 봅시다: - - (*) 홀수번 ìºì‹œë¼ì¸ì€ ìºì‹œ A, ìºì‹œ C ë˜ëŠ” ë©”ëª¨ë¦¬ì— ìœ„ì¹˜í• ìˆ˜ 있ìŒ; - - (*) ì§ìˆ˜ë²ˆ ìºì‹œë¼ì¸ì€ ìºì‹œ B, ìºì‹œ D ë˜ëŠ” ë©”ëª¨ë¦¬ì— ìœ„ì¹˜í• ìˆ˜ 있ìŒ; - - (*) CPU 코어가 í•œê°œì˜ ìºì‹œì— ì ‘ê·¼í•˜ëŠ” ë™ì•ˆ, 다른 ìºì‹œëŠ” - ë”í‹° ìºì‹œë¼ì¸ì„ - ë©”ëª¨ë¦¬ì— ë‚´ë¦¬ê±°ë‚˜ 추측성 로드를 하거나 하기 위해 - ì‹œìŠ¤í…œì˜ ë‹¤ë¥¸ ë¶€ë¶„ì— - 액세스 하기 위해 버스를 ì‚¬ìš©í• ìˆ˜ 있ìŒ; - - (*) ê° ìºì‹œëŠ” ì‹œìŠ¤í…œì˜ ë‚˜ë¨¸ì§€ 부분들과 ì¼ê´€ì„±ì„ 맞추기 위해 해당 ìºì‹œì— - ì ìš©ë˜ì–´ì•¼ í• ì˜¤í¼ë ˆì´ì…˜ë“¤ì˜ í를 ê°€ì§; - - (*) ì´ ì¼ê´€ì„± í는 ìºì‹œì— ì´ë¯¸ 존재하는 ë¼ì¸ì— 가해지는 í‰ë²”í•œ ë¡œë“œì— ì˜í•´ì„œëŠ” - 비워지지 않는ë°, íì˜ ì˜¤í¼ë ˆì´ì…˜ë“¤ì´ ì´ ë¡œë“œì˜ ê²°ê³¼ì— ì˜í–¥ì„ ë¼ì¹ 수 있다 - í• ì§€ë¼ë„ 그러함. - -ì´ì œ, 첫번째 CPU ì—ì„œ ë‘ê°œì˜ ì“°ê¸° 오í¼ë ˆì´ì…˜ì„ 만드는ë°, 해당 CPU ì˜ ìºì‹œì— -ìš”ì²ëœ 순서로 오í¼ë ˆì´ì…˜ì´ ë„달ë¨ì„ 보장하기 위해 ë‘ ì˜¤í¼ë ˆì´ì…˜ 사ì´ì— 쓰기 -배리어를 사용하는 ìƒí™©ì„ ìƒìƒí•´ 봅시다: - - CPU 1 CPU 2 COMMENT - =============== =============== ======================================= - u == 0, v == 1 and p == &u, q == &u - v = 2; - smp_wmb(); v ì˜ ë³€ê²½ì´ p ì˜ ë³€ê²½ ì „ì— ë³´ì¼ ê²ƒì„ - 분명히 함 - <A:modify v=2> v 는 ì´ì œ ìºì‹œ A ì— ë…ì ì 으로 존재함 - p = &v; - <B:modify p=&v> p 는 ì´ì œ ìºì‹œ B ì— ë…ì ì 으로 존재함 - -ì—¬ê¸°ì„œì˜ ì“°ê¸° 메모리 배리어는 CPU 1 ì˜ ìºì‹œê°€ 올바른 순서로 ì—…ë°ì´íŠ¸ ëœ ê²ƒìœ¼ë¡œ -ì‹œìŠ¤í…œì˜ ë‹¤ë¥¸ CPU ë“¤ì´ ì¸ì§€í•˜ê²Œ 만ë“니다. 하지만, ì´ì œ ë‘번째 CPU ê°€ ê·¸ ê°’ë“¤ì„ -ì½ìœ¼ë ¤ 하는 ìƒí™©ì„ ìƒê°í•´ 봅시다: - - CPU 1 CPU 2 COMMENT - =============== =============== ======================================= - ... - q = p; - x = *q; - -ìœ„ì˜ ë‘ê°œì˜ ì½ê¸° 오í¼ë ˆì´ì…˜ì€ 예ìƒëœ 순서로 ì¼ì–´ë‚˜ì§€ ëª»í• ìˆ˜ 있는ë°, ë‘번째 CPU -ì˜ í•œ ìºì‹œì— 다른 ìºì‹œ ì´ë²¤íŠ¸ê°€ ë°œìƒí•´ v 를 ë‹´ê³ ìžˆëŠ” ìºì‹œë¼ì¸ì˜ 해당 ìºì‹œì—ì˜ -ì—…ë°ì´íŠ¸ê°€ 지연ë˜ëŠ” 사ì´, p 를 ë‹´ê³ ìžˆëŠ” ìºì‹œë¼ì¸ì€ ë‘번째 CPU ì˜ ë‹¤ë¥¸ ìºì‹œì— -ì—…ë°ì´íŠ¸ ë˜ì–´ë²„ë ¸ì„ ìˆ˜ 있기 때문입니다. - - CPU 1 CPU 2 COMMENT - =============== =============== ======================================= - u == 0, v == 1 and p == &u, q == &u - v = 2; - smp_wmb(); - <A:modify v=2> <C:busy> - <C:queue v=2> - p = &v; q = p; - <D:request p> - <B:modify p=&v> <D:commit p=&v> - <D:read p> - x = *q; - <C:read *q> ìºì‹œì— ì—…ë°ì´íŠ¸ ë˜ê¸° ì „ì˜ v 를 ì½ìŒ - <C:unbusy> - <C:commit v=2> - -기본ì 으로, ë‘ê°œì˜ ìºì‹œë¼ì¸ ëª¨ë‘ CPU 2 ì— ìµœì¢…ì 으로는 ì—…ë°ì´íŠ¸ ë 것ì´ì§€ë§Œ, -별ë„ì˜ ê°œìž… ì—†ì´ëŠ”, ì—…ë°ì´íŠ¸ì˜ 순서가 CPU 1 ì—ì„œ 만들어진 순서와 ë™ì¼í• -것ì´ë¼ëŠ” ë³´ìž¥ì´ ì—†ìŠµë‹ˆë‹¤. - - -ì—¬ê¸°ì— ê°œìž…í•˜ê¸° ìœ„í•´ì„ , ë°ì´í„° ì˜ì¡´ì„± 배리어나 ì½ê¸° 배리어를 로드 오í¼ë ˆì´ì…˜ë“¤ -사ì´ì— 넣어야 합니다 (v4.15 부터는 READ_ONCE() 매í¬ë¡œì— ì˜í•´ 무조건ì 으로 -ê·¸ë ‡ê²Œ ë©ë‹ˆë‹¤). ì´ë ‡ê²Œ í•¨ìœ¼ë¡œì¨ ìºì‹œê°€ ë‹¤ìŒ ìš”ì²ì„ 처리하기 ì „ì— ì¼ê´€ì„± í를 -처리하ë„ë¡ ê°•ì œí•˜ê²Œ ë©ë‹ˆë‹¤. - - CPU 1 CPU 2 COMMENT - =============== =============== ======================================= - u == 0, v == 1 and p == &u, q == &u - v = 2; - smp_wmb(); - <A:modify v=2> <C:busy> - <C:queue v=2> - p = &v; q = p; - <D:request p> - <B:modify p=&v> <D:commit p=&v> - <D:read p> - smp_read_barrier_depends() - <C:unbusy> - <C:commit v=2> - x = *q; - <C:read *q> ìºì‹œì— ì—…ë°ì´íŠ¸ ëœ v 를 ì½ìŒ - - -ì´ëŸ° ë¶€ë¥˜ì˜ ë¬¸ì œëŠ” DEC Alpha 계열 프로세서들ì—ì„œ 발견ë 수 있는ë°, ì´ë“¤ì€ -ë°ì´í„° 버스를 좀 ë” ìž˜ 사용해 ì„±ëŠ¥ì„ ê°œì„ í• ìˆ˜ 있는, ë¶„í• ëœ ìºì‹œë¥¼ ê°€ì§€ê³ ìžˆê¸° -때문입니다. ëŒ€ë¶€ë¶„ì˜ CPU 는 í•˜ë‚˜ì˜ ì½ê¸° 오í¼ë ˆì´ì…˜ì˜ 메모리 액세스가 다른 ì½ê¸° -오í¼ë ˆì´ì…˜ì— ì˜ì¡´ì ì´ë¼ë©´ ë°ì´í„° ì˜ì¡´ì„± 배리어를 ë‚´í¬ì‹œí‚µë‹ˆë‹¤ë§Œ, 모ë‘ê°€ 그런건 -아니기 ë•Œë¬¸ì— ì´ì ì— ì˜ì¡´í•´ì„ 안ë©ë‹ˆë‹¤. - -다른 CPU ë“¤ë„ ë¶„í• ëœ ìºì‹œë¥¼ ê°€ì§€ê³ ìžˆì„ ìˆ˜ 있지만, 그런 CPU ë“¤ì€ í‰ë²”í•œ 메모리 -액세스를 ìœ„í•´ì„œë„ ì´ ë¶„í• ëœ ìºì‹œë“¤ 사ì´ì˜ ì¡°ì •ì„ í•´ì•¼ë§Œ 합니다. Alpha 는 가장 -약한 메모리 순서 시맨틱 (semantic) ì„ ì„ íƒí•¨ìœ¼ë¡œì¨ 메모리 배리어가 명시ì 으로 -사용ë˜ì§€ ì•Šì•˜ì„ ë•Œì—는 그런 ì¡°ì •ì´ í•„ìš”í•˜ì§€ 않게 했으며, ì´ëŠ” Alpha ê°€ ë‹¹ì‹œì— -ë” ë†’ì€ CPU í´ë½ ì†ë„를 가질 수 있게 했습니다. 하지만, (다시 ë§í•˜ê±´ëŒ€, v4.15 -ì´í›„부터는) Alpha 아키í…ì³ ì „ìš© 코드와 READ_ONCE() 매í¬ë¡œ 내부ì—서를 ì œì™¸í•˜ê³ ëŠ” -smp_read_barrier_depends() ê°€ 사용ë˜ì§€ 않아야 í•¨ì„ ì•Œì•„ë‘시기 ë°”ëžë‹ˆë‹¤. - - ìºì‹œ ì¼ê´€ì„± VS DMA ------------------ @@ -2962,10 +2824,8 @@ Alpha CPU ì˜ ì¼ë¶€ ë²„ì „ì€ ë¶„í• ëœ ë°ì´í„° ìºì‹œë¥¼ ê°€ì§€ê³ ìžˆì–´ì„œ ë°ì´í„°ì˜ ë°œê²¬ì„ ì˜¬ë°”ë¥¸ 순서로 ì¼ì–´ë‚˜ê²Œ 하기 때문입니다. 리눅스 커ë„ì˜ ë©”ëª¨ë¦¬ 배리어 모ë¸ì€ Alpha ì— ê¸°ì´ˆí•´ì„œ ì •ì˜ë˜ì—ˆìŠµë‹ˆë‹¤ë§Œ, v4.15 -부터는 리눅스 커ë„ì´ READ_ONCE() ë‚´ì— smp_read_barrier_depends() 를 추가해서 -Alpha ì˜ ë©”ëª¨ë¦¬ 모ë¸ë¡œì˜ ì˜í–¥ë ¥ì´ í¬ê²Œ 줄어들긴 했습니다. - -ìœ„ì˜ "ìºì‹œ ì¼ê´€ì„±" ì„œë¸Œì„¹ì…˜ì„ ì°¸ê³ í•˜ì„¸ìš”. +부터는 Alpha ìš© READ_ONCE() 코드 ë‚´ì— smp_mb() ê°€ 추가ë˜ì–´ì„œ 메모리 모ë¸ë¡œì˜ +Alpha ì˜ ì˜í–¥ë ¥ì´ í¬ê²Œ 줄어들었습니다. ê°€ìƒ ë¨¸ì‹ ê²ŒìŠ¤íŠ¸ diff --git a/Documentation/translations/zh_CN/admin-guide/clearing-warn-once.rst b/Documentation/translations/zh_CN/admin-guide/clearing-warn-once.rst new file mode 100644 index 000000000000..659264d5f994 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/clearing-warn-once.rst @@ -0,0 +1,9 @@ +清除 WARN_ONCE +-------------- + +WARN_ONCE / WARN_ON_ONCE / printk_once 仅仅打å°ä¸€æ¬¡æ¶ˆæ¯. + +echo 1 > /sys/kernel/debug/clear_warn_once + +å¯ä»¥æ¸…除这ç§çŠ¶æ€å¹¶ä¸”å†æ¬¡å…许打å°ä¸€æ¬¡å‘Šè¦ä¿¡æ¯ï¼Œè¿™å¯¹äºŽè¿è¡Œæµ‹è¯•é›†åŽé‡çŽ°é—®é¢˜ +很有用。 diff --git a/Documentation/translations/zh_CN/admin-guide/cpu-load.rst b/Documentation/translations/zh_CN/admin-guide/cpu-load.rst new file mode 100644 index 000000000000..0116d0477799 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/cpu-load.rst @@ -0,0 +1,105 @@ +======= +CPU è´Ÿè½½ +======= + +Linux通过``/proc/stat``å’Œ``/proc/uptime``导出å„ç§ä¿¡æ¯ï¼Œç”¨æˆ·ç©ºé—´å·¥å…· +如top(1)使用这些信æ¯è®¡ç®—系统花费在æŸä¸ªç‰¹å®šçŠ¶æ€çš„å¹³å‡æ—¶é—´ã€‚ +例如： + + $ iostat + Linux 2.6.18.3-exp (linmac) 02/20/2007 + + avg-cpu: %user %nice %system %iowait %steal %idle + 10.01 0.00 2.92 5.44 0.00 81.63 + + ... + +è¿™é‡Œç³»ç»Ÿè®¤ä¸ºåœ¨é»˜è®¤é‡‡æ ·å‘¨æœŸå…§æœ‰10.01%的时间工作在用户空间，2.92%çš„æ—¶ +间用在系统空间，总体上有81.63%的时间是空闲的。 + +大多数情况下``/proc/stat``çš„ä¿¡æ¯å‡ 乎真实åæ˜ äº†ç³»ç»Ÿä¿¡æ¯ï¼Œç„¶è€Œï¼Œç”±äºŽå†… +æ ¸é‡‡é›†è¿™äº›æ•°æ®çš„æ–¹å¼/时间的特点，有时这些信æ¯æ ¹æœ¬ä¸å¯é 。 + +那么这些信æ¯æ˜¯å¦‚何被æœé›†çš„呢？æ¯å½“时间ä¸æ–触å‘æ—¶ï¼Œå†…æ ¸æŸ¥çœ‹æ¤åˆ»è¿è¡Œçš„ +è¿›ç¨‹ç±»åž‹ï¼Œå¹¶å¢žåŠ ä¸Žæ¤ç±»åž‹/状æ€è¿›ç¨‹å¯¹åº”的计数器的值。这ç§æ–¹æ³•çš„问题是 +在两次时间ä¸æ–之间系统（进程）能够在多ç§çŠ¶æ€ä¹‹é—´åˆ‡æ¢å¤šæ¬¡ï¼Œè€Œè®¡æ•°å™¨åª +å¢žåŠ æœ€åŽä¸€ç§çŠ¶æ€ä¸‹çš„计数。 + +举例 +--- + +å‡è®¾ç³»ç»Ÿæœ‰ä¸€ä¸ªè¿›ç¨‹ä»¥å¦‚下方å¼å‘¨æœŸæ€§åœ°å 用cpu:: + + 两个时钟ä¸æ–之间的时间线 + |-----------------------| + ^ ^ + |_ 开始è¿è¡Œ | + |_ 开始ç¡çœ + （很快会被唤醒） + +在上é¢çš„æƒ…å†µä¸‹ï¼Œæ ¹æ®``/proc/stat``çš„ä¿¡æ¯ï¼ˆç”±äºŽå½“系统处于空闲状æ€æ—¶ï¼Œ +时间ä¸æ–ç»å¸¸ä¼šå‘生）系统的负载将会是0 + +å¤§å®¶èƒ½å¤Ÿæƒ³è±¡å†…æ ¸çš„è¿™ç§è¡Œä¸ºä¼šå‘生在许多情况下，这将导致``/proc/stat`` +ä¸å˜åœ¨ç›¸å½“å¤æ€ªçš„ä¿¡æ¯:: + + /* gcc -o hog smallhog.c */ + #include <time.h> + #include <limits.h> + #include <signal.h> + #include <sys/time.h> + #define HIST 10 + + static volatile sig_atomic_t stop; + + static void sighandler (int signr) + { + (void) signr; + stop = 1; + } + static unsigned long hog (unsigned long niters) + { + stop = 0; + while (!stop && --niters); + return niters; + } + int main (void) + { + int i; + struct itimerval it = { .it_interval = { .tv_sec = 0, .tv_usec = 1 }, + .it_value = { .tv_sec = 0, .tv_usec = 1 } }; + sigset_t set; + unsigned long v[HIST]; + double tmp = 0.0; + unsigned long n; + signal (SIGALRM, &sighandler); + setitimer (ITIMER_REAL, &it, NULL); + + hog (ULONG_MAX); + for (i = 0; i < HIST; ++i) v[i] = ULONG_MAX - hog (ULONG_MAX); + for (i = 0; i < HIST; ++i) tmp += v[i]; + tmp /= HIST; + n = tmp - (tmp / 3.0); + + sigemptyset (&set); + sigaddset (&set, SIGALRM); + + for (;;) { + hog (n); + sigwait (&set, &i); + } + return 0; + } + + +å‚考 +--- + +- http://lkml.org/lkml/2007/2/12/6 +- Documentation/filesystems/proc.rst (1.8) + + +谢谢 +--- + +Con Kolivas, Pavel Machek diff --git a/Documentation/translations/zh_CN/admin-guide/index.rst b/Documentation/translations/zh_CN/admin-guide/index.rst new file mode 100644 index 000000000000..7d502fa5da64 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/index.rst @@ -0,0 +1,125 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/admin-guide/index.rst` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + + +Linux å†…æ ¸ç”¨æˆ·å’Œç®¡ç†å‘˜æŒ‡å— +========================== + +下é¢æ˜¯ä¸€ç»„éšæ—¶é—´æ·»åŠ åˆ°å†…æ ¸ä¸çš„é¢å‘用户的文档的集åˆã€‚到目å‰ä¸ºæ¢ï¼Œè¿˜æ²¡æœ‰ä¸€ä¸ª +整体的顺åºæˆ–组织 - 这些ææ–™ä¸æ˜¯ä¸€ä¸ªå•ä¸€çš„，连贯的文件ï¼å¹¸è¿çš„è¯ï¼Œæƒ…况会éšç€ +时间的推移而迅速改善。 + +这个åˆå§‹éƒ¨åˆ†åŒ…å«æ€»ä½“ä¿¡æ¯ï¼ŒåŒ…括æè¿°å†…æ ¸çš„README， å…³äºŽå†…æ ¸å‚数的文档ç‰ã€‚ + +Todolist: + + README + kernel-parameters + devices + sysctl/index + +本节介ç»CPUæ¼æ´žåŠå…¶ç¼“解措施。 + +Todolist: + + hw-vuln/index + +下é¢çš„一组文档，针对的是试图跟踪问题和bug的用户。 + +Todolist: + + reporting-bugs + security-bugs + bug-hunting + bug-bisect + tainted-kernels + ramoops + dynamic-debug-howto + init + kdump/index + perf/index + +这是应用程åºå¼€å‘äººå‘˜æ„Ÿå…´è¶£çš„ç« èŠ‚çš„å¼€å§‹ã€‚å¯ä»¥åœ¨è¿™é‡Œæ‰¾åˆ°æ¶µç›–å†…æ ¸ABIå„个 +æ–¹é¢çš„文档。 + +Todolist: + + sysfs-rules + +本手册的其余部分包括å„ç§æŒ‡å—，介ç»å¦‚ä½•æ ¹æ®æ‚¨çš„喜好é…ç½®å†…æ ¸çš„ç‰¹å®šè¡Œä¸ºã€‚ + + +.. toctree:: + :maxdepth: 1 + + clearing-warn-once + cpu-load + +Todolist: + + acpi/index + aoe/index + auxdisplay/index + bcache + binderfs + binfmt-misc + blockdev/index + bootconfig + braille-console + btmrvl + cgroup-v1/index + cgroup-v2 + cifs/index + cputopology + dell_rbu + device-mapper/index + edid + efi-stub + ext4 + nfs/index + gpio/index + highuid + hw_random + initrd + iostats + java + jfs + kernel-per-CPU-kthreads + laptops/index + lcd-panel-cgram + ldm + lockup-watchdogs + LSM/index + md + media/index + mm/index + module-signing + mono + namespaces/index + numastat + parport + perf-security + pm/index + pnp + rapidio + ras + rtc + serial-console + svga + sysrq + thunderbolt + ufs + unicode + vga-softcursor + video-output + wimax/index + xfs + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/arm/Booting b/Documentation/translations/zh_CN/arm/Booting index 562e9a2957e6..c3d26ce5f6de 100644 --- a/Documentation/translations/zh_CN/arm/Booting +++ b/Documentation/translations/zh_CN/arm/Booting @@ -124,7 +124,7 @@ bootloader å¿…é¡»ä¼ é€’ä¸€ä¸ªç³»ç»Ÿå†…å˜çš„ä½ç½®å’Œæœ€å°å€¼ï¼Œä»¥åŠæ ¹æ–‡ä»¶ bootloader 必须以 64bit 地å€å¯¹é½çš„å½¢å¼åŠ è½½ä¸€ä¸ªè®¾å¤‡æ ‘æ˜ åƒ(dtb)到系统 RAM ä¸ï¼Œå¹¶ç”¨å¯åŠ¨æ•°æ®åˆå§‹åŒ–它。dtb æ ¼å¼åœ¨æ–‡æ¡£ -Documentation/devicetree/booting-without-of.txt ä¸ã€‚å†…æ ¸å°†ä¼šåœ¨ +Documentation/devicetree/booting-without-of.rst ä¸ã€‚å†…æ ¸å°†ä¼šåœ¨ dtb 物ç†åœ°å€å¤„查找 dtb é”数值（0xd00dfeed），以确定 dtb 是å¦å·²ç»ä»£æ›¿ æ ‡ç¾åˆ—è¡¨è¢«ä¼ é€’è¿›æ¥ã€‚ diff --git a/Documentation/translations/zh_CN/filesystems/sysfs.txt b/Documentation/translations/zh_CN/filesystems/sysfs.txt index fcf620049d11..9481e3ed2a06 100644 --- a/Documentation/translations/zh_CN/filesystems/sysfs.txt +++ b/Documentation/translations/zh_CN/filesystems/sysfs.txt @@ -213,10 +213,12 @@ Sysfs 将会为æ¯æ¬¡è¯»å†™æ“ä½œè°ƒç”¨ä¸€æ¬¡è¿™ä¸ªæ–¹æ³•ã€‚è¿™ä½¿å¾—è¿™äº›æ–¹æ³ - 缓冲区应总是 PAGE_SIZE 大å°ã€‚对于i386，这个值为4096。 -- show() 方法应该返回写入缓冲区的å—节数，也就是 snprintf()çš„ +- show() 方法应该返回写入缓冲区的å—节数，也就是 scnprintf()çš„ 返回值。 -- show() 应始终使用 snprintf()。 +- show() æ–¹æ³•åœ¨å°†æ ¼å¼åŒ–返回值返回用户空间的时候，ç¦æ¢ä½¿ç”¨snprintf()。 + 如果å¯ä»¥ä¿è¯ä¸ä¼šå‘生缓冲区溢出，å¯ä»¥ä½¿ç”¨sprintf()，å¦åˆ™å¿…须使用 + scnprintf()。 - store() 应返回缓冲区的已用å—节数。如果整个缓å˜éƒ½å·²å¡«æ»¡ï¼Œåªéœ€è¿”回 count å‚数。 diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst index 76850a5dd982..85643e46e308 100644 --- a/Documentation/translations/zh_CN/index.rst +++ b/Documentation/translations/zh_CN/index.rst @@ -10,9 +10,13 @@ 人员åšå‡ºè´¡çŒ®ã€‚ ä¸Žä»»ä½•å¤§åž‹ç¤¾åŒºä¸€æ ·ï¼ŒçŸ¥é“如何完æˆä»»åŠ¡å°†ä½¿å¾—更改åˆå¹¶çš„过程å˜å¾—æ›´ åŠ å®¹æ˜“ã€‚ +翻译计划: +å†…æ ¸ä¸æ–‡æ–‡æ¡£æ¬¢è¿Žä»»ä½•ç¿»è¯‘æŠ•ç¨¿ï¼Œç‰¹åˆ«æ˜¯å…³äºŽå†…æ ¸ç”¨æˆ·å’Œç®¡ç†å‘˜æŒ‡å—部分。 + .. toctree:: :maxdepth: 2 + admin-guide/index process/index filesystems/index diff --git a/Documentation/translations/zh_CN/process/2.Process.rst b/Documentation/translations/zh_CN/process/2.Process.rst index ceb733bb0294..ebe2e0254b3e 100644 --- a/Documentation/translations/zh_CN/process/2.Process.rst +++ b/Documentation/translations/zh_CN/process/2.Process.rst @@ -212,7 +212,7 @@ Next æ ‘ 当å‰-mm è¡¥ä¸å¯åœ¨â€œmmotmâ€ï¼ˆ-mm of the moment）目录ä¸æ‰¾åˆ°ï¼Œåœ°å€ï¼š - http://www.ozlabs.org/~akpm/mmotm/ + https://www.ozlabs.org/~akpm/mmotm/ 然而，使用mmotmæ ‘å¯èƒ½æ˜¯ä¸€ç§ä»¤äººæ²®ä¸§çš„体验；它甚至å¯èƒ½æ— 法编译。 @@ -220,7 +220,7 @@ Next æ ‘ linux-next 是下一个åˆå¹¶çª—å£å…³é—åŽä¸»çº¿çš„快照。linux-nextæ ‘åœ¨Linux-kernel å’Œ Linux-next 邮件列表ä¸å‘布，å¯ä»Žä»¥ä¸‹ä½ç½®ä¸‹è½½ï¼š - http://www.kernel.org/pub/linux/kernel/next/ + https://www.kernel.org/pub/linux/kernel/next/ Linux-next å·²ç»æˆä¸ºå†…æ ¸å¼€å‘过程ä¸ä¸å¯æˆ–缺的一部分；在一个给定的åˆå¹¶çª—å£ä¸åˆå¹¶ 的所有补ä¸éƒ½åº”该在åˆå¹¶çª—å£æ‰“开之å‰çš„一段时间内找到进入Linux-next 的方法。 @@ -260,7 +260,7 @@ staging驱动程åºã€‚å› æ¤ï¼Œåœ¨æˆä¸ºä¸€ååˆé€‚的主线驱动的路上，s çŽ°åœ¨å‡ ä¹Žæ‰€æœ‰çš„Linuxå‘行版都打包了Git。主页ä½äºŽï¼š - http://git-scm.com/ + https://git-scm.com/ 那个页é¢æœ‰æŒ‡å‘文档和教程的指针。 @@ -272,7 +272,7 @@ Mercurial与Git共享许多特性，但它æ供了一个界é¢ï¼Œè®¸å¤šäººè§‰å¾ å¦ä¸€ä¸ªå€¼å¾—了解的工具是quilt: - http://savannah.nongnu.org/projects/quilt + https://savannah.nongnu.org/projects/quilt Quilt 是一个补ä¸ç®¡ç†ç³»ç»Ÿï¼Œè€Œä¸æ˜¯æºä»£ç 管ç†ç³»ç»Ÿã€‚它ä¸ä¼šéšç€æ—¶é—´çš„推移跟踪历å²ï¼› 相å，它é¢å‘æ ¹æ®ä¸æ–å‘展的代ç 库跟踪一组特定的更改。一些主è¦çš„å系统维护人员 diff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rst index b82b1dde3122..959a06ba025c 100644 --- a/Documentation/translations/zh_CN/process/4.Coding.rst +++ b/Documentation/translations/zh_CN/process/4.Coding.rst @@ -224,7 +224,7 @@ scripts/coccinelle目录下已ç»æ‰“åŒ…äº†ç›¸å½“å¤šçš„å†…æ ¸â€œè¯ä¹‰è¡¥ä¸â€ï¼ 或Blackfinå¼€å‘æ¿ï¼Œæ‚¨ä»ç„¶å¯ä»¥æ‰§è¡Œç¼–译æ¥éª¤ã€‚å¯ä»¥åœ¨ä»¥ä¸‹ä½ç½®æ‰¾åˆ°ä¸€ç»„用于x86系统的 大型交å‰ç¼–译器： - http://www.kernel.org/pub/tools/crosstool/ + https://www.kernel.org/pub/tools/crosstool/ 花一些时间安装和使用这些编译器将有助于é¿å…以åŽçš„尴尬。 diff --git a/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst b/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst index 956815edbd18..2f0ef750746f 100644 --- a/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst +++ b/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst @@ -25,9 +25,9 @@ 将是Git如何特别适åˆå†…æ ¸å¼€å‘过程。想è¦åŠ å¿«Gitçš„å¼€å‘人员å¯ä»¥åœ¨ä»¥ä¸‹ç½‘站上找到 更多信æ¯ï¼š - http://git-scm.com/ + https://git-scm.com/ - http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + https://www.kernel.org/pub/software/scm/git/docs/user-manual.html 在å°è¯•ä½¿ç”¨å®ƒä½¿è¡¥ä¸å¯ä¾›å…¶ä»–人使用之å‰ï¼Œç¬¬ä¸€è¦åŠ¡æ˜¯é˜…读上述站点，对Git的工作 æ–¹å¼æœ‰ä¸€ä¸ªæ‰Žå®žçš„了解。使用Gitçš„å¼€å‘人员应该能够获得主线å˜å‚¨åº“的副本，探索 @@ -42,7 +42,7 @@ 如果您有一个å¯ä»¥è®¿é—®Internet的系统，那么使用gitå®ˆæŠ¤è¿›ç¨‹è®¾ç½®è¿™æ ·çš„æœåŠ¡å™¨ç›¸ 对简å•ã€‚å¦åˆ™ï¼Œå…费的公共托管网站（例如github）开始出现在网络上。æˆç†Ÿçš„å¼€å‘ äººå‘˜å¯ä»¥åœ¨kernel.org上获得一个å¸æˆ·ï¼Œä½†è¿™äº›å¸æˆ·å¹¶ä¸å®¹æ˜“找到；有关更多信æ¯ï¼Œ -请å‚阅 http://kernel.org/faq/ +请å‚阅 https://kernel.org/faq/ æ£å¸¸çš„Git工作æµç¨‹æ¶‰åŠåˆ°è®¸å¤šåˆ†æ”¯çš„使用。æ¯ä¸€æ¡å¼€å‘线都å¯ä»¥åˆ†ä¸ºå•ç‹¬çš„“主题 分支â€ï¼Œå¹¶ç‹¬ç«‹ç»´æŠ¤ã€‚Git的分支机构很便宜，没有ç†ç”±ä¸å…费使用它们。而且，在 diff --git a/Documentation/translations/zh_CN/process/8.Conclusion.rst b/Documentation/translations/zh_CN/process/8.Conclusion.rst index 2bbd76161e10..90cec3de6106 100644 --- a/Documentation/translations/zh_CN/process/8.Conclusion.rst +++ b/Documentation/translations/zh_CN/process/8.Conclusion.rst @@ -17,16 +17,16 @@ 记录的；“make htmldocsâ€æˆ–“make pdfdocsâ€å¯ç”¨äºŽä»¥HTML或PDFæ ¼å¼ç”Ÿæˆè¿™äº›æ–‡æ¡£ï¼ˆ 尽管æŸäº›å‘行版æ供的tex版本会é‡åˆ°å†…部é™åˆ¶ï¼Œæ— 法æ£ç¡®å¤„ç†æ–‡æ¡£ï¼‰ã€‚ -ä¸åŒçš„网站在å„ä¸ªç»†èŠ‚å±‚æ¬¡ä¸Šè®¨è®ºå†…æ ¸å¼€å‘。您的作者想谦虚地建议用 http://lwn.net/ +ä¸åŒçš„网站在å„ä¸ªç»†èŠ‚å±‚æ¬¡ä¸Šè®¨è®ºå†…æ ¸å¼€å‘。您的作者想谦虚地建议用 https://lwn.net/ 作为æ¥æºï¼›æœ‰å…³è®¸å¤šç‰¹å®šå†…æ ¸ä¸»é¢˜çš„ä¿¡æ¯å¯ä»¥é€šè¿‡ä»¥ä¸‹ç½‘å€çš„lwnå†…æ ¸ç´¢å¼•æ‰¾åˆ°ï¼š http://lwn.net/kernel/index/ 除æ¤ä¹‹å¤–ï¼Œå†…æ ¸å¼€å‘人员的一个å®è´µèµ„æºæ˜¯ï¼š - http://kernelnewbies.org/ + https://kernelnewbies.org/ -当然，我们ä¸åº”该忘记 http://kernel.org/ è¿™æ˜¯å†…æ ¸å‘布信æ¯çš„最终ä½ç½®ã€‚ +当然，我们ä¸åº”该忘记 https://kernel.org/ è¿™æ˜¯å†…æ ¸å‘布信æ¯çš„最终ä½ç½®ã€‚ å…³äºŽå†…æ ¸å¼€å‘有很多书： @@ -42,9 +42,9 @@ 有关git的文档，请访问： - http://www.kernel.org/pub/software/scm/git/docs/ + https://www.kernel.org/pub/software/scm/git/docs/ - http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + https://www.kernel.org/pub/software/scm/git/docs/user-manual.html 结论 ==== diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst index eae10bc7f86f..406d43a02c02 100644 --- a/Documentation/translations/zh_CN/process/coding-style.rst +++ b/Documentation/translations/zh_CN/process/coding-style.rst @@ -946,7 +946,7 @@ Addison-Wesley, Inc., 1999. ISBN 0-201-61586-X. GNU 手册 - éµå¾ª K&R æ ‡å‡†å’Œæ¤æ–‡æœ¬ - cpp, gcc, gcc internals and indent, -都å¯ä»¥ä»Ž http://www.gnu.org/manual/ 找到 +都å¯ä»¥ä»Ž https://www.gnu.org/manual/ 找到 WG14 是 C è¯è¨€çš„å›½é™…æ ‡å‡†åŒ–å·¥ä½œç»„ï¼ŒURL: http://www.open-std.org/JTC1/SC22/WG14/ diff --git a/Documentation/translations/zh_CN/process/howto.rst b/Documentation/translations/zh_CN/process/howto.rst index a8e6ab818983..ee3dee476d57 100644 --- a/Documentation/translations/zh_CN/process/howto.rst +++ b/Documentation/translations/zh_CN/process/howto.rst @@ -69,7 +69,7 @@ Linuxå†…æ ¸æºä»£ç 都是在GPL（通用公共许å¯è¯ï¼‰çš„ä¿æŠ¤ä¸‹å‘布的 邮件组里的人并ä¸æ˜¯å¾‹å¸ˆï¼Œä¸è¦æœŸæœ›ä»–们的è¯æœ‰æ³•å¾‹æ•ˆåŠ›ã€‚ 对于GPL的常è§é—®é¢˜å’Œè§£ç”，请访问以下链接： - http://www.gnu.org/licenses/gpl-faq.html + https://www.gnu.org/licenses/gpl-faq.html 文档 @@ -109,7 +109,7 @@ Linuxå†…æ ¸ä»£ç ä¸åŒ…å«æœ‰å¤§é‡çš„文档。这些文档对于å¦ä¹ 如何与 其他关于如何æ£ç¡®åœ°ç”Ÿæˆè¡¥ä¸çš„优秀文档包括： "The Perfect Patch" - http://www.ozlabs.org/~akpm/stuff/tpp.txt + https://www.ozlabs.org/~akpm/stuff/tpp.txt "Linux kernel patch submission format" @@ -163,7 +163,7 @@ ReSTæ ¼å¼çš„文档会生æˆåœ¨ Documentation/output. 目录ä¸ã€‚ ------------------ å¦‚æžœä½ å¯¹Linuxå†…æ ¸å¼€å‘ä¸€æ— æ‰€çŸ¥ï¼Œä½ åº”è¯¥è®¿é—®â€œLinuxå†…æ ¸æ–°æ‰‹â€è®¡åˆ’： - http://kernelnewbies.org + https://kernelnewbies.org 它拥有一个å¯ä»¥é—®å„ç§æœ€åŸºæœ¬çš„å†…æ ¸å¼€å‘问题的邮件列表（在æ问之å‰ä¸€å®šè¦è®°å¾— 查找已往的邮件，确认是å¦æœ‰äººå·²ç»å›žç”过相åŒçš„问题）。它还拥有一个å¯ä»¥èŽ·å¾— @@ -176,7 +176,7 @@ ReSTæ ¼å¼çš„文档会生æˆåœ¨ Documentation/output. 目录ä¸ã€‚ å¦‚æžœä½ æƒ³åŠ å…¥å†…æ ¸å¼€å‘社区并å助完æˆä¸€äº›ä»»åŠ¡ï¼Œå´æ‰¾ä¸åˆ°ä»Žå“ªé‡Œå¼€å§‹ï¼Œå¯ä»¥è®¿é—® “Linuxå†…æ ¸æˆ¿ç®¡å‘˜â€è®¡åˆ’： - http://kernelnewbies.org/KernelJanitors + https://kernelnewbies.org/KernelJanitors 这是æžä½³çš„起点。它æ供一个相对简å•çš„ä»»åŠ¡åˆ—è¡¨ï¼Œåˆ—å‡ºå†…æ ¸ä»£ç ä¸éœ€è¦è¢«é‡æ–° æ•´ç†æˆ–者改æ£çš„地方。通过和负责这个计划的开å‘者们一åŒå·¥ä½œï¼Œä½ 会å¦åˆ°å°†è¡¥ä¸ @@ -212,7 +212,7 @@ ReSTæ ¼å¼çš„文档会生æˆåœ¨ Documentation/output. 目录ä¸ã€‚ - æ¯å½“ä¸€ä¸ªæ–°ç‰ˆæœ¬çš„å†…æ ¸è¢«å‘布，为期两周的集æˆçª—å£å°†è¢«æ‰“开。在这段时间里 维护者å¯ä»¥å‘Linusæ交大段的修改，通常这些修改已ç»è¢«æ”¾åˆ°-mmå†…æ ¸ä¸å‡ 个 星期了。æ交大é‡ä¿®æ”¹çš„首选方å¼æ˜¯ä½¿ç”¨gitå·¥å…·ï¼ˆå†…æ ¸çš„ä»£ç 版本管ç†å·¥å…· - ，更多的信æ¯å¯ä»¥åœ¨ http://git-scm.com/ 获å–），ä¸è¿‡ä½¿ç”¨æ™®é€šè¡¥ä¸ä¹Ÿæ˜¯ + ，更多的信æ¯å¯ä»¥åœ¨ https://git-scm.com/ 获å–），ä¸è¿‡ä½¿ç”¨æ™®é€šè¡¥ä¸ä¹Ÿæ˜¯ å¯ä»¥çš„。 - 两个星期以åŽ-rc1ç‰ˆæœ¬å†…æ ¸å‘布。之åŽåªæœ‰ä¸åŒ…å«å¯èƒ½å½±å“æ•´ä¸ªå†…æ ¸ç¨³å®šæ€§çš„ 新功能的补ä¸æ‰å¯èƒ½è¢«æŽ¥å—。请注æ„一个全新的驱动程åºï¼ˆæˆ–者文件系统）有 @@ -472,7 +472,7 @@ Linuxå†…æ ¸ç¤¾åŒºå¹¶ä¸å–œæ¬¢ä¸€ä¸‹æŽ¥æ”¶å¤§æ®µçš„代ç 。修改需è¦è¢«æ°å½“ 想了解它具体应该看起æ¥åƒä»€ä¹ˆï¼Œè¯·æŸ¥é˜…以下文档ä¸çš„“ChangeLogâ€ç« 节： “The Perfect Patch†- http://www.ozlabs.org/~akpm/stuff/tpp.txt + https://www.ozlabs.org/~akpm/stuff/tpp.txt 这些事情有时候åšèµ·æ¥å¾ˆéš¾ã€‚è¦åœ¨ä»»ä½•æ–¹é¢éƒ½åšåˆ°å®Œç¾Žå¯èƒ½éœ€è¦å¥½å‡ 年时间。这是 diff --git a/Documentation/translations/zh_CN/process/submitting-drivers.rst b/Documentation/translations/zh_CN/process/submitting-drivers.rst index d99885c27aed..98341e7cd812 100644 --- a/Documentation/translations/zh_CN/process/submitting-drivers.rst +++ b/Documentation/translations/zh_CN/process/submitting-drivers.rst @@ -19,8 +19,8 @@ ============================= 这篇文档将会解释如何å‘ä¸åŒçš„å†…æ ¸æºç æ ‘æ交设备驱动程åºã€‚请注æ„ï¼Œå¦‚æžœä½ æ„Ÿ -兴趣的是显å¡é©±åŠ¨ç¨‹åºï¼Œä½ 也许应该访问 XFree86 项目(http://www.xfree86.org/) -å’Œï¼æˆ– X.org 项目 (http://x.org)。 +兴趣的是显å¡é©±åŠ¨ç¨‹åºï¼Œä½ 也许应该访问 XFree86 项目(https://www.xfree86.org/) +å’Œï¼æˆ– X.org 项目 (https://x.org)。 å¦è¯·å‚阅 Documentation/translations/zh_CN/process/submitting-patches.rst 文档。 @@ -29,7 +29,7 @@ ---------- å—设备和å—符设备的主设备å·ä¸Žä»Žè®¾å¤‡å·æ˜¯ç”± Linux 命åç¼–å·åˆ†é…æƒå¨ LANANA（ -现在是 Torben Mathiasen）负责分é…。申请的网å€æ˜¯ http://www.lanana.org/。 +现在是 Torben Mathiasen）负责分é…。申请的网å€æ˜¯ https://www.lanana.org/。 å³ä½¿ä¸å‡†å¤‡æ交到主æµå†…æ ¸çš„è®¾å¤‡é©±åŠ¨ä¹Ÿéœ€è¦åœ¨è¿™é‡Œåˆ†é…设备å·ã€‚有关详细信æ¯ï¼Œ 请å‚阅 Documentation/admin-guide/devices.rst。 @@ -133,22 +133,22 @@ Linux å†…æ ¸é‚®ä»¶åˆ—è¡¨ï¼š [å¯é€šè¿‡å‘majordomo@vger.kernel.orgå‘邮件æ¥è®¢é˜…] Linux 设备驱动程åºï¼Œç¬¬ä¸‰ç‰ˆï¼ˆæŽ¢è®¨ 2.6.10 ç‰ˆå†…æ ¸ï¼‰ï¼š - http://lwn.net/Kernel/LDD3/ （å…费版） + https://lwn.net/Kernel/LDD3/ （å…费版） LWN.net: - æ¯å‘¨å†…æ ¸å¼€å‘æ´»åŠ¨æ‘˜è¦ - http://lwn.net/ + æ¯å‘¨å†…æ ¸å¼€å‘æ´»åŠ¨æ‘˜è¦ - https://lwn.net/ 2.6 ç‰ˆä¸ API çš„å˜æ›´ï¼š - http://lwn.net/Articles/2.6-kernel-api/ + https://lwn.net/Articles/2.6-kernel-api/ å°†æ—§ç‰ˆå†…æ ¸çš„é©±åŠ¨ç¨‹åºç§»æ¤åˆ° 2.6 版： - http://lwn.net/Articles/driver-porting/ + https://lwn.net/Articles/driver-porting/ å†…æ ¸æ–°æ‰‹(KernelNewbies): ä¸ºæ–°çš„å†…æ ¸å¼€å‘者æ供文档和帮助 - http://kernelnewbies.org/ + https://kernelnewbies.org/ Linux USB项目： http://www.linux-usb.org/ @@ -157,4 +157,4 @@ Linux USB项目： http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf å†…æ ¸æ¸…æ´å·¥ (Kernel Janitor): - http://kernelnewbies.org/KernelJanitors + https://kernelnewbies.org/KernelJanitors diff --git a/Documentation/translations/zh_CN/process/submitting-patches.rst b/Documentation/translations/zh_CN/process/submitting-patches.rst index 1bb4271ab420..2e7dbaad4028 100644 --- a/Documentation/translations/zh_CN/process/submitting-patches.rst +++ b/Documentation/translations/zh_CN/process/submitting-patches.rst @@ -91,7 +91,7 @@ :ref:`cn_split_changes` å¦‚æžœä½ ç”¨ ``git`` , ``git rebase -i`` å¯ä»¥å¸®åŠ©ä½ è¿™ä¸€ç‚¹ã€‚å¦‚æžœä½ ä¸ç”¨ ``git``, -``quilt`` <http://savannah.nongnu.org/projects/quilt> å¦å¤–一个æµè¡Œçš„选择。 +``quilt`` <https://savannah.nongnu.org/projects/quilt> å¦å¤–一个æµè¡Œçš„选择。 .. _cn_describe_changes: @@ -649,7 +649,7 @@ pull 请求还应该包å«ä¸€æ¡æ•´ä½“消æ¯ï¼Œè¯´æ˜Žè¯·æ±‚ä¸å°†åŒ…å«ä»€ä¹ˆï¼Œ -------- Andrew Morton, "The perfect patch" (tpp). - <http://www.ozlabs.org/~akpm/stuff/tpp.txt> + <https://www.ozlabs.org/~akpm/stuff/tpp.txt> Jeff Garzik, "Linux kernel patch submission format". <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> diff --git a/Documentation/translations/zh_CN/process/volatile-considered-harmful.rst b/Documentation/translations/zh_CN/process/volatile-considered-harmful.rst index 48b32ce58ef1..ded3b5d0c9a8 100644 --- a/Documentation/translations/zh_CN/process/volatile-considered-harmful.rst +++ b/Documentation/translations/zh_CN/process/volatile-considered-harmful.rst @@ -94,8 +94,8 @@ bug并且需è¦å¯¹è¿™æ ·çš„代ç é¢å¤–仔细检查。那些试图使用volatile 注释 ---- -[1] http://lwn.net/Articles/233481/ -[2] http://lwn.net/Articles/233482/ +[1] https://lwn.net/Articles/233481/ +[2] https://lwn.net/Articles/233482/ 致谢 ---- diff --git a/Documentation/usb/gadget_hid.rst b/Documentation/usb/gadget_hid.rst index 098d563040cc..e623416de4f1 100644 --- a/Documentation/usb/gadget_hid.rst +++ b/Documentation/usb/gadget_hid.rst @@ -11,7 +11,7 @@ and HID reports can be sent/received through I/O on the /dev/hidgX character devices. For more details about HID, see the developer page on -http://www.usb.org/developers/hidpage/ +https://www.usb.org/developers/hidpage/ Configuration ============= diff --git a/Documentation/usb/gadget_multi.rst b/Documentation/usb/gadget_multi.rst index 9806b55af301..3a22c1b2f39e 100644 --- a/Documentation/usb/gadget_multi.rst +++ b/Documentation/usb/gadget_multi.rst @@ -142,7 +142,7 @@ Footnotes ========= [1] Remote Network Driver Interface Specification, -[[http://msdn.microsoft.com/en-us/library/ee484414.aspx]]. +[[https://msdn.microsoft.com/en-us/library/ee484414.aspx]]. [2] Communications Device Class Abstract Control Model, spec for this and other USB classes can be found at @@ -150,9 +150,9 @@ and other USB classes can be found at [3] CDC Ethernet Control Model. -[4] [[http://msdn.microsoft.com/en-us/library/ff537109(v=VS.85).aspx]] +[4] [[https://msdn.microsoft.com/en-us/library/ff537109(v=VS.85).aspx]] -[5] [[http://msdn.microsoft.com/en-us/library/ff539234(v=VS.85).aspx]] +[5] [[https://msdn.microsoft.com/en-us/library/ff539234(v=VS.85).aspx]] [6] To put it in some other nice words, Windows failed to respond to any user input. @@ -160,6 +160,6 @@ any user input. [7] You may find [[http://www.cygnal.org/ubb/Forum9/HTML/001050.html]] useful. -[8] http://www.nirsoft.net/utils/usb_devices_view.html +[8] https://www.nirsoft.net/utils/usb_devices_view.html -[9] [[http://msdn.microsoft.com/en-us/library/ff570620.aspx]] +[9] [[https://msdn.microsoft.com/en-us/library/ff570620.aspx]] diff --git a/Documentation/usb/linux.inf b/Documentation/usb/linux.inf index 4ffa715b0ae8..c569ac6bec58 100644 --- a/Documentation/usb/linux.inf +++ b/Documentation/usb/linux.inf @@ -1,5 +1,5 @@ ; Based on template INF file found at -; <http://msdn.microsoft.com/en-us/library/ff570620.aspx> +; <https://msdn.microsoft.com/en-us/library/ff570620.aspx> ; which was: ; Copyright (c) Microsoft Corporation ; and released under the MLPL as found at: diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst index 94e46a11d68d..436a882dfa31 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst @@ -58,6 +58,9 @@ returns the information to the application. The ioctl never fails. - The name of this CEC adapter. The combination ``driver`` and ``name`` must be unique. * - __u32 + - ``available_log_addrs`` + - The maximum number of logical addresses that can be configured. + * - __u32 - ``capabilities`` - The capabilities of the CEC adapter, see :ref:`cec-capabilities`. diff --git a/Documentation/userspace-api/media/conf_nitpick.py b/Documentation/userspace-api/media/conf_nitpick.py index d0c50d75f518..0a8e236d07ab 100644 --- a/Documentation/userspace-api/media/conf_nitpick.py +++ b/Documentation/userspace-api/media/conf_nitpick.py @@ -27,7 +27,7 @@ nitpick_ignore = [ ("c:func", "copy_to_user"), ("c:func", "determine_valid_ioctls"), ("c:func", "ERR_PTR"), - ("c:func", "i2c_new_device"), + ("c:func", "i2c_new_client_device"), ("c:func", "ioctl"), ("c:func", "IS_ERR"), ("c:func", "KERNEL_VERSION"), diff --git a/Documentation/userspace-api/media/dvb/fe-get-info.rst b/Documentation/userspace-api/media/dvb/fe-get-info.rst index 80d9f8195ac4..6b3ffd301142 100644 --- a/Documentation/userspace-api/media/dvb/fe-get-info.rst +++ b/Documentation/userspace-api/media/dvb/fe-get-info.rst @@ -34,8 +34,7 @@ Arguments File descriptor returned by :ref:`open() <frontend_f_open>`. ``argp`` - pointer to struct struct - :c:type:`dvb_frontend_info` + pointer to struct :c:type:`dvb_frontend_info` Description diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst index 951ae1ed485f..57e752aaf414 100644 --- a/Documentation/userspace-api/media/v4l/buffer.rst +++ b/Documentation/userspace-api/media/v4l/buffer.rst @@ -23,8 +23,8 @@ argument to the :ref:`VIDIOC_QUERYBUF`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. In the multi-planar API, some plane-specific members of struct :c:type:`v4l2_buffer`, -such as pointers and sizes for each plane, are stored in struct -struct :c:type:`v4l2_plane` instead. In that case, struct +such as pointers and sizes for each plane, are stored in +struct :c:type:`v4l2_plane` instead. In that case, struct :c:type:`v4l2_buffer` contains an array of plane structures. Dequeued video buffers come with timestamps. The driver decides at which @@ -577,7 +577,10 @@ Buffer Flags applications shall use this flag if the data captured in the buffer is not going to be touched by the CPU, instead the buffer will, probably, be passed on to a DMA-capable hardware unit for - further processing or output. + further processing or output. This flag is ignored unless the + queue is used for :ref:`memory mapping <mmap>` streaming I/O and + reports :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS + <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability. * .. _`V4L2-BUF-FLAG-NO-CACHE-CLEAN`: - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` @@ -585,7 +588,10 @@ Buffer Flags - Caches do not have to be cleaned for this buffer. Typically applications shall use this flag for output buffers if the data in this buffer has not been created by the CPU but by some - DMA-capable unit, in which case caches have not been used. + DMA-capable unit, in which case caches have not been used. This flag + is ignored unless the queue is used for :ref:`memory mapping <mmap>` + streaming I/O and reports :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS + <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability. * .. _`V4L2-BUF-FLAG-M2M-HOLD-CAPTURE-BUF`: - ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` @@ -681,6 +687,36 @@ Buffer Flags \normalsize +.. _memory-flags: + +Memory Consistency Flags +======================== + +.. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.3cm}| + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * .. _`V4L2-FLAG-MEMORY-NON-CONSISTENT`: + + - ``V4L2_FLAG_MEMORY_NON_CONSISTENT`` + - 0x00000001 + - A buffer is allocated either in consistent (it will be automatically + coherent between the CPU and the bus) or non-consistent memory. The + latter can provide performance gains, for instance the CPU cache + sync/flush operations can be avoided if the buffer is accessed by the + corresponding device only and the CPU does not read/write to/from that + buffer. However, this requires extra care from the driver -- it must + guarantee memory consistency by issuing a cache flush/sync when + consistency is needed. If this flag is set V4L2 will attempt to + allocate the buffer in non-consistent memory. The flag takes effect + only if the buffer is used for :ref:`memory mapping <mmap>` I/O and the + queue reports the :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS + <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability. .. c:type:: v4l2_memory diff --git a/Documentation/userspace-api/media/v4l/colorspaces-details.rst b/Documentation/userspace-api/media/v4l/colorspaces-details.rst index 79ed6f4f76eb..300c5d2e7d0f 100644 --- a/Documentation/userspace-api/media/v4l/colorspaces-details.rst +++ b/Documentation/userspace-api/media/v4l/colorspaces-details.rst @@ -767,8 +767,8 @@ scaled to [-128…128] and then clipped to [-128…127]. information. So if something other than sRGB is used, then the driver will have to set that information explicitly. Effectively ``V4L2_COLORSPACE_JPEG`` can be considered to be an abbreviation for - ``V4L2_COLORSPACE_SRGB``, ``V4L2_YCBCR_ENC_601`` and - ``V4L2_QUANTIZATION_FULL_RANGE``. + ``V4L2_COLORSPACE_SRGB``, ``V4L2_XFER_FUNC_SRGB``, ``V4L2_YCBCR_ENC_601`` + and ``V4L2_QUANTIZATION_FULL_RANGE``. *************************************** Detailed Transfer Function Descriptions diff --git a/Documentation/userspace-api/media/v4l/dev-decoder.rst b/Documentation/userspace-api/media/v4l/dev-decoder.rst index 606b54947e10..3d4138a4ba69 100644 --- a/Documentation/userspace-api/media/v4l/dev-decoder.rst +++ b/Documentation/userspace-api/media/v4l/dev-decoder.rst @@ -247,7 +247,7 @@ Querying Capabilities Initialization ============== -1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT` +1. Set the coded format on ``OUTPUT`` via :c:func:`VIDIOC_S_FMT`. * **Required fields:** @@ -803,7 +803,7 @@ it may be affected as per normal decoder operation. * The decoder will drop all the pending ``OUTPUT`` buffers and they must be treated as returned to the client (following standard semantics). -2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON` +2. Restart the ``OUTPUT`` queue via :c:func:`VIDIOC_STREAMON`. * **Required fields:** @@ -906,7 +906,9 @@ reflected by corresponding queries): * visible resolution (selection rectangles), -* the minimum number of buffers needed for decoding. +* the minimum number of buffers needed for decoding, + +* bit-depth of the bitstream has been changed. Whenever that happens, the decoder must proceed as follows: @@ -1059,7 +1061,7 @@ sequence was started. ``V4L2_DEC_CMD_STOP`` again while the drain sequence is in progress and they will fail with -EBUSY error code if attempted. - Although mandatory, the availability of decoder commands may be queried + Although not mandatory, the availability of decoder commands may be queried using :c:func:`VIDIOC_TRY_DECODER_CMD`. End of Stream diff --git a/Documentation/userspace-api/media/v4l/dev-encoder.rst b/Documentation/userspace-api/media/v4l/dev-encoder.rst new file mode 100644 index 000000000000..fb44f20924de --- /dev/null +++ b/Documentation/userspace-api/media/v4l/dev-encoder.rst @@ -0,0 +1,753 @@ +.. This file is dual-licensed: you can use it either under the terms +.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this +.. dual licensing only applies to this file, and not this project as a +.. whole. +.. +.. a) This file is free software; you can redistribute it and/or +.. modify it under the terms of the GNU General Public License as +.. published by the Free Software Foundation version 2 of +.. the License. +.. +.. This file is distributed in the hope that it will be useful, +.. but WITHOUT ANY WARRANTY; without even the implied warranty of +.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.. GNU General Public License for more details. +.. +.. Or, alternatively, +.. +.. b) Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections + +.. _encoder: + +************************************************* +Memory-to-Memory Stateful Video Encoder Interface +************************************************* + +A stateful video encoder takes raw video frames in display order and encodes +them into a bytestream. It generates complete chunks of the bytestream, including +all metadata, headers, etc. The resulting bytestream does not require any +further post-processing by the client. + +Performing software stream processing, header generation etc. in the driver +in order to support this interface is strongly discouraged. In case such +operations are needed, use of the Stateless Video Encoder Interface (in +development) is strongly advised. + +Conventions and Notations Used in This Document +=============================================== + +1. The general V4L2 API rules apply if not specified in this document + otherwise. + +2. The meaning of words "must", "may", "should", etc. is as per `RFC + 2119 <https://tools.ietf.org/html/rfc2119>`_. + +3. All steps not marked "optional" are required. + +4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`VIDIOC_S_EXT_CTRLS` may be used + interchangeably with :c:func:`VIDIOC_G_CTRL` and :c:func:`VIDIOC_S_CTRL`, + unless specified otherwise. + +5. Single-planar API (see :ref:`planar-apis`) and applicable structures may be + used interchangeably with multi-planar API, unless specified otherwise, + depending on encoder capabilities and following the general V4L2 guidelines. + +6. i = [a..b]: sequence of integers from a to b, inclusive, i.e. i = + [0..2]: i = 0, 1, 2. + +7. Given an ``OUTPUT`` buffer A, then A' represents a buffer on the ``CAPTURE`` + queue containing data that resulted from processing buffer A. + +Glossary +======== + +Refer to :ref:`decoder-glossary`. + +State Machine +============= + +.. kernel-render:: DOT + :alt: DOT digraph of encoder state machine + :caption: Encoder State Machine + + digraph encoder_state_machine { + node [shape = doublecircle, label="Encoding"] Encoding; + + node [shape = circle, label="Initialization"] Initialization; + node [shape = circle, label="Stopped"] Stopped; + node [shape = circle, label="Drain"] Drain; + node [shape = circle, label="Reset"] Reset; + + node [shape = point]; qi + qi -> Initialization [ label = "open()" ]; + + Initialization -> Encoding [ label = "Both queues streaming" ]; + + Encoding -> Drain [ label = "V4L2_ENC_CMD_STOP" ]; + Encoding -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ]; + Encoding -> Stopped [ label = "VIDIOC_STREAMOFF(OUTPUT)" ]; + Encoding -> Encoding; + + Drain -> Stopped [ label = "All CAPTURE\nbuffers dequeued\nor\nVIDIOC_STREAMOFF(OUTPUT)" ]; + Drain -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ]; + + Reset -> Encoding [ label = "VIDIOC_STREAMON(CAPTURE)" ]; + Reset -> Initialization [ label = "VIDIOC_REQBUFS(OUTPUT, 0)" ]; + + Stopped -> Encoding [ label = "V4L2_ENC_CMD_START\nor\nVIDIOC_STREAMON(OUTPUT)" ]; + Stopped -> Reset [ label = "VIDIOC_STREAMOFF(CAPTURE)" ]; + } + +Querying Capabilities +===================== + +1. To enumerate the set of coded formats supported by the encoder, the + client may call :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``. + + * The full set of supported formats will be returned, regardless of the + format set on ``OUTPUT``. + +2. To enumerate the set of supported raw formats, the client may call + :c:func:`VIDIOC_ENUM_FMT` on ``OUTPUT``. + + * Only the formats supported for the format currently active on ``CAPTURE`` + will be returned. + + * In order to enumerate raw formats supported by a given coded format, + the client must first set that coded format on ``CAPTURE`` and then + enumerate the formats on ``OUTPUT``. + +3. The client may use :c:func:`VIDIOC_ENUM_FRAMESIZES` to detect supported + resolutions for a given format, passing the desired pixel format in + :c:type:`v4l2_frmsizeenum` ``pixel_format``. + + * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a coded pixel + format will include all possible coded resolutions supported by the + encoder for the given coded pixel format. + + * Values returned by :c:func:`VIDIOC_ENUM_FRAMESIZES` for a raw pixel format + will include all possible frame buffer resolutions supported by the + encoder for the given raw pixel format and coded format currently set on + ``CAPTURE``. + +4. The client may use :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` to detect supported + frame intervals for a given format and resolution, passing the desired pixel + format in :c:type:`v4l2_frmsizeenum` ``pixel_format`` and the resolution + in :c:type:`v4l2_frmsizeenum` ``width`` and :c:type:`v4l2_frmsizeenum` + ``height``. + + * Values returned by :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` for a coded pixel + format and coded resolution will include all possible frame intervals + supported by the encoder for the given coded pixel format and resolution. + + * Values returned by :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` for a raw pixel + format and resolution will include all possible frame intervals supported + by the encoder for the given raw pixel format and resolution and for the + coded format, coded resolution and coded frame interval currently set on + ``CAPTURE``. + + * Support for :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` is optional. If it is + not implemented, then there are no special restrictions other than the + limits of the codec itself. + +5. Supported profiles and levels for the coded format currently set on + ``CAPTURE``, if applicable, may be queried using their respective controls + via :c:func:`VIDIOC_QUERYCTRL`. + +6. Any additional encoder capabilities may be discovered by querying + their respective controls. + +Initialization +============== + +1. Set the coded format on the ``CAPTURE`` queue via :c:func:`VIDIOC_S_FMT`. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + ``pixelformat`` + the coded format to be produced. + + ``sizeimage`` + desired size of ``CAPTURE`` buffers; the encoder may adjust it to + match hardware requirements. + + ``width``, ``height`` + ignored (read-only). + + other fields + follow standard semantics. + + * **Return fields:** + + ``sizeimage`` + adjusted size of ``CAPTURE`` buffers. + + ``width``, ``height`` + the coded size selected by the encoder based on current state, e.g. + ``OUTPUT`` format, selection rectangles, etc. (read-only). + + .. important:: + + Changing the ``CAPTURE`` format may change the currently set ``OUTPUT`` + format. How the new ``OUTPUT`` format is determined is up to the encoder + and the client must ensure it matches its needs afterwards. + +2. **Optional.** Enumerate supported ``OUTPUT`` formats (raw formats for + source) for the selected coded format via :c:func:`VIDIOC_ENUM_FMT`. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + other fields + follow standard semantics. + + * **Return fields:** + + ``pixelformat`` + raw format supported for the coded format currently selected on + the ``CAPTURE`` queue. + + other fields + follow standard semantics. + +3. Set the raw source format on the ``OUTPUT`` queue via + :c:func:`VIDIOC_S_FMT`. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + ``pixelformat`` + raw format of the source. + + ``width``, ``height`` + source resolution. + + other fields + follow standard semantics. + + * **Return fields:** + + ``width``, ``height`` + may be adjusted to match encoder minimums, maximums and alignment + requirements, as required by the currently selected formats, as + reported by :c:func:`VIDIOC_ENUM_FRAMESIZES`. + + other fields + follow standard semantics. + + * Setting the ``OUTPUT`` format will reset the selection rectangles to their + default values, based on the new resolution, as described in the next + step. + +4. Set the raw frame interval on the ``OUTPUT`` queue via + :c:func:`VIDIOC_S_PARM`. This also sets the coded frame interval on the + ``CAPTURE`` queue to the same value. + + * ** Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + ``parm.output`` + set all fields except ``parm.output.timeperframe`` to 0. + + ``parm.output.timeperframe`` + the desired frame interval; the encoder may adjust it to + match hardware requirements. + + * **Return fields:** + + ``parm.output.timeperframe`` + the adjusted frame interval. + + .. important:: + + Changing the ``OUTPUT`` frame interval *also* sets the framerate that + the encoder uses to encode the video. So setting the frame interval + to 1/24 (or 24 frames per second) will produce a coded video stream + that can be played back at that speed. The frame interval for the + ``OUTPUT`` queue is just a hint, the application may provide raw + frames at a different rate. It can be used by the driver to help + schedule multiple encoders running in parallel. + + In the next step the ``CAPTURE`` frame interval can optionally be + changed to a different value. This is useful for off-line encoding + were the coded frame interval can be different from the rate at + which raw frames are supplied. + + .. important:: + + ``timeperframe`` deals with *frames*, not fields. So for interlaced + formats this is the time per two fields, since a frame consists of + a top and a bottom field. + + .. note:: + + It is due to historical reasons that changing the ``OUTPUT`` frame + interval also changes the coded frame interval on the ``CAPTURE`` + queue. Ideally these would be independent settings, but that would + break the existing API. + +5. **Optional** Set the coded frame interval on the ``CAPTURE`` queue via + :c:func:`VIDIOC_S_PARM`. This is only necessary if the coded frame + interval is different from the raw frame interval, which is typically + the case for off-line encoding. Support for this feature is signalled + by the :ref:`V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL <fmtdesc-flags>` format flag. + + * ** Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. + + ``parm.capture`` + set all fields except ``parm.capture.timeperframe`` to 0. + + ``parm.capture.timeperframe`` + the desired coded frame interval; the encoder may adjust it to + match hardware requirements. + + * **Return fields:** + + ``parm.capture.timeperframe`` + the adjusted frame interval. + + .. important:: + + Changing the ``CAPTURE`` frame interval sets the framerate for the + coded video. It does *not* set the rate at which buffers arrive on the + ``CAPTURE`` queue, that depends on how fast the encoder is and how + fast raw frames are queued on the ``OUTPUT`` queue. + + .. important:: + + ``timeperframe`` deals with *frames*, not fields. So for interlaced + formats this is the time per two fields, since a frame consists of + a top and a bottom field. + + .. note:: + + Not all drivers support this functionality, in that case just set + the desired coded frame interval for the ``OUTPUT`` queue. + + However, drivers that can schedule multiple encoders based on the + ``OUTPUT`` frame interval must support this optional feature. + +6. **Optional.** Set the visible resolution for the stream metadata via + :c:func:`VIDIOC_S_SELECTION` on the ``OUTPUT`` queue if it is desired + to be different than the full OUTPUT resolution. + + * **Required fields:** + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + ``target`` + set to ``V4L2_SEL_TGT_CROP``. + + ``r.left``, ``r.top``, ``r.width``, ``r.height`` + visible rectangle; this must fit within the `V4L2_SEL_TGT_CROP_BOUNDS` + rectangle and may be subject to adjustment to match codec and + hardware constraints. + + * **Return fields:** + + ``r.left``, ``r.top``, ``r.width``, ``r.height`` + visible rectangle adjusted by the encoder. + + * The following selection targets are supported on ``OUTPUT``: + + ``V4L2_SEL_TGT_CROP_BOUNDS`` + equal to the full source frame, matching the active ``OUTPUT`` + format. + + ``V4L2_SEL_TGT_CROP_DEFAULT`` + equal to ``V4L2_SEL_TGT_CROP_BOUNDS``. + + ``V4L2_SEL_TGT_CROP`` + rectangle within the source buffer to be encoded into the + ``CAPTURE`` stream; defaults to ``V4L2_SEL_TGT_CROP_DEFAULT``. + + .. note:: + + A common use case for this selection target is encoding a source + video with a resolution that is not a multiple of a macroblock, + e.g. the common 1920x1080 resolution may require the source + buffers to be aligned to 1920x1088 for codecs with 16x16 macroblock + size. To avoid encoding the padding, the client needs to explicitly + configure this selection target to 1920x1080. + + .. warning:: + + The encoder may adjust the crop/compose rectangles to the nearest + supported ones to meet codec and hardware requirements. The client needs + to check the adjusted rectangle returned by :c:func:`VIDIOC_S_SELECTION`. + +7. Allocate buffers for both ``OUTPUT`` and ``CAPTURE`` via + :c:func:`VIDIOC_REQBUFS`. This may be performed in any order. + + * **Required fields:** + + ``count`` + requested number of buffers to allocate; greater than zero. + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT`` or + ``CAPTURE``. + + other fields + follow standard semantics. + + * **Return fields:** + + ``count`` + actual number of buffers allocated. + + .. warning:: + + The actual number of allocated buffers may differ from the ``count`` + given. The client must check the updated value of ``count`` after the + call returns. + + .. note:: + + To allocate more than the minimum number of OUTPUT buffers (for pipeline + depth), the client may query the ``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` + control to get the minimum number of buffers required, and pass the + obtained value plus the number of additional buffers needed in the + ``count`` field to :c:func:`VIDIOC_REQBUFS`. + + Alternatively, :c:func:`VIDIOC_CREATE_BUFS` can be used to have more + control over buffer allocation. + + * **Required fields:** + + ``count`` + requested number of buffers to allocate; greater than zero. + + ``type`` + a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. + + other fields + follow standard semantics. + + * **Return fields:** + + ``count`` + adjusted to the number of allocated buffers. + +8. Begin streaming on both ``OUTPUT`` and ``CAPTURE`` queues via + :c:func:`VIDIOC_STREAMON`. This may be performed in any order. The actual + encoding process starts when both queues start streaming. + +.. note:: + + If the client stops the ``CAPTURE`` queue during the encode process and then + restarts it again, the encoder will begin generating a stream independent + from the stream generated before the stop. The exact constraints depend + on the coded format, but may include the following implications: + + * encoded frames produced after the restart must not reference any + frames produced before the stop, e.g. no long term references for + H.264/HEVC, + + * any headers that must be included in a standalone stream must be + produced again, e.g. SPS and PPS for H.264/HEVC. + +Encoding +======== + +This state is reached after the `Initialization` sequence finishes +successfully. In this state, the client queues and dequeues buffers to both +queues via :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBUF`, following the +standard semantics. + +The content of encoded ``CAPTURE`` buffers depends on the active coded pixel +format and may be affected by codec-specific extended controls, as stated +in the documentation of each format. + +Both queues operate independently, following standard behavior of V4L2 buffer +queues and memory-to-memory devices. In addition, the order of encoded frames +dequeued from the ``CAPTURE`` queue may differ from the order of queuing raw +frames to the ``OUTPUT`` queue, due to properties of the selected coded format, +e.g. frame reordering. + +The client must not assume any direct relationship between ``CAPTURE`` and +``OUTPUT`` buffers and any specific timing of buffers becoming +available to dequeue. Specifically: + +* a buffer queued to ``OUTPUT`` may result in more than one buffer produced on + ``CAPTURE`` (for example, if returning an encoded frame allowed the encoder + to return a frame that preceded it in display, but succeeded it in the decode + order; however, there may be other reasons for this as well), + +* a buffer queued to ``OUTPUT`` may result in a buffer being produced on + ``CAPTURE`` later into encode process, and/or after processing further + ``OUTPUT`` buffers, or be returned out of order, e.g. if display + reordering is used, + +* buffers may become available on the ``CAPTURE`` queue without additional + buffers queued to ``OUTPUT`` (e.g. during drain or ``EOS``), because of the + ``OUTPUT`` buffers queued in the past whose encoding results are only + available at later time, due to specifics of the encoding process, + +* buffers queued to ``OUTPUT`` may not become available to dequeue instantly + after being encoded into a corresponding ``CAPTURE`` buffer, e.g. if the + encoder needs to use the frame as a reference for encoding further frames. + +.. note:: + + To allow matching encoded ``CAPTURE`` buffers with ``OUTPUT`` buffers they + originated from, the client can set the ``timestamp`` field of the + :c:type:`v4l2_buffer` struct when queuing an ``OUTPUT`` buffer. The + ``CAPTURE`` buffer(s), which resulted from encoding that ``OUTPUT`` buffer + will have their ``timestamp`` field set to the same value when dequeued. + + In addition to the straightforward case of one ``OUTPUT`` buffer producing + one ``CAPTURE`` buffer, the following cases are defined: + + * one ``OUTPUT`` buffer generates multiple ``CAPTURE`` buffers: the same + ``OUTPUT`` timestamp will be copied to multiple ``CAPTURE`` buffers, + + * the encoding order differs from the presentation order (i.e. the + ``CAPTURE`` buffers are out-of-order compared to the ``OUTPUT`` buffers): + ``CAPTURE`` timestamps will not retain the order of ``OUTPUT`` timestamps. + +.. note:: + + To let the client distinguish between frame types (keyframes, intermediate + frames; the exact list of types depends on the coded format), the + ``CAPTURE`` buffers will have corresponding flag bits set in their + :c:type:`v4l2_buffer` struct when dequeued. See the documentation of + :c:type:`v4l2_buffer` and each coded pixel format for exact list of flags + and their meanings. + +Should an encoding error occur, it will be reported to the client with the level +of details depending on the encoder capabilities. Specifically: + +* the ``CAPTURE`` buffer (if any) that contains the results of the failed encode + operation will be returned with the ``V4L2_BUF_FLAG_ERROR`` flag set, + +* if the encoder is able to precisely report the ``OUTPUT`` buffer(s) that triggered + the error, such buffer(s) will be returned with the ``V4L2_BUF_FLAG_ERROR`` flag + set. + +.. note:: + + If a ``CAPTURE`` buffer is too small then it is just returned with the + ``V4L2_BUF_FLAG_ERROR`` flag set. More work is needed to detect that this + error occurred because the buffer was too small, and to provide support to + free existing buffers that were too small. + +In case of a fatal failure that does not allow the encoding to continue, any +further operations on corresponding encoder file handle will return the -EIO +error code. The client may close the file handle and open a new one, or +alternatively reinitialize the instance by stopping streaming on both queues, +releasing all buffers and performing the Initialization sequence again. + +Encoding Parameter Changes +========================== + +The client is allowed to use :c:func:`VIDIOC_S_CTRL` to change encoder +parameters at any time. The availability of parameters is encoder-specific +and the client must query the encoder to find the set of available controls. + +The ability to change each parameter during encoding is encoder-specific, as +per the standard semantics of the V4L2 control interface. The client may +attempt to set a control during encoding and if the operation fails with the +-EBUSY error code, the ``CAPTURE`` queue needs to be stopped for the +configuration change to be allowed. To do this, it may follow the `Drain` +sequence to avoid losing the already queued/encoded frames. + +The timing of parameter updates is encoder-specific, as per the standard +semantics of the V4L2 control interface. If the client needs to apply the +parameters exactly at specific frame, using the Request API +(:ref:`media-request-api`) should be considered, if supported by the encoder. + +Drain +===== + +To ensure that all the queued ``OUTPUT`` buffers have been processed and the +related ``CAPTURE`` buffers are given to the client, the client must follow the +drain sequence described below. After the drain sequence ends, the client has +received all encoded frames for all ``OUTPUT`` buffers queued before the +sequence was started. + +1. Begin the drain sequence by issuing :c:func:`VIDIOC_ENCODER_CMD`. + + * **Required fields:** + + ``cmd`` + set to ``V4L2_ENC_CMD_STOP``. + + ``flags`` + set to 0. + + ``pts`` + set to 0. + + .. warning:: + + The sequence can be only initiated if both ``OUTPUT`` and ``CAPTURE`` + queues are streaming. For compatibility reasons, the call to + :c:func:`VIDIOC_ENCODER_CMD` will not fail even if any of the queues is + not streaming, but at the same time it will not initiate the `Drain` + sequence and so the steps described below would not be applicable. + +2. Any ``OUTPUT`` buffers queued by the client before the + :c:func:`VIDIOC_ENCODER_CMD` was issued will be processed and encoded as + normal. The client must continue to handle both queues independently, + similarly to normal encode operation. This includes: + + * queuing and dequeuing ``CAPTURE`` buffers, until a buffer marked with the + ``V4L2_BUF_FLAG_LAST`` flag is dequeued, + + .. warning:: + + The last buffer may be empty (with :c:type:`v4l2_buffer` + ``bytesused`` = 0) and in that case it must be ignored by the client, + as it does not contain an encoded frame. + + .. note:: + + Any attempt to dequeue more ``CAPTURE`` buffers beyond the buffer + marked with ``V4L2_BUF_FLAG_LAST`` will result in a -EPIPE error from + :c:func:`VIDIOC_DQBUF`. + + * dequeuing processed ``OUTPUT`` buffers, until all the buffers queued + before the ``V4L2_ENC_CMD_STOP`` command are dequeued, + + * dequeuing the ``V4L2_EVENT_EOS`` event, if the client subscribes to it. + + .. note:: + + For backwards compatibility, the encoder will signal a ``V4L2_EVENT_EOS`` + event when the last frame has been encoded and all frames are ready to be + dequeued. It is deprecated behavior and the client must not rely on it. + The ``V4L2_BUF_FLAG_LAST`` buffer flag should be used instead. + +3. Once all ``OUTPUT`` buffers queued before the ``V4L2_ENC_CMD_STOP`` call are + dequeued and the last ``CAPTURE`` buffer is dequeued, the encoder is stopped + and it will accept, but not process any newly queued ``OUTPUT`` buffers + until the client issues any of the following operations: + + * ``V4L2_ENC_CMD_START`` - the encoder will not be reset and will resume + operation normally, with all the state from before the drain, + + * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the + ``CAPTURE`` queue - the encoder will be reset (see the `Reset` sequence) + and then resume encoding, + + * a pair of :c:func:`VIDIOC_STREAMOFF` and :c:func:`VIDIOC_STREAMON` on the + ``OUTPUT`` queue - the encoder will resume operation normally, however any + source frames queued to the ``OUTPUT`` queue between ``V4L2_ENC_CMD_STOP`` + and :c:func:`VIDIOC_STREAMOFF` will be discarded. + +.. note:: + + Once the drain sequence is initiated, the client needs to drive it to + completion, as described by the steps above, unless it aborts the process by + issuing :c:func:`VIDIOC_STREAMOFF` on any of the ``OUTPUT`` or ``CAPTURE`` + queues. The client is not allowed to issue ``V4L2_ENC_CMD_START`` or + ``V4L2_ENC_CMD_STOP`` again while the drain sequence is in progress and they + will fail with -EBUSY error code if attempted. + + For reference, handling of various corner cases is described below: + + * In case of no buffer in the ``OUTPUT`` queue at the time the + ``V4L2_ENC_CMD_STOP`` command was issued, the drain sequence completes + immediately and the encoder returns an empty ``CAPTURE`` buffer with the + ``V4L2_BUF_FLAG_LAST`` flag set. + + * In case of no buffer in the ``CAPTURE`` queue at the time the drain + sequence completes, the next time the client queues a ``CAPTURE`` buffer + it is returned at once as an empty buffer with the ``V4L2_BUF_FLAG_LAST`` + flag set. + + * If :c:func:`VIDIOC_STREAMOFF` is called on the ``CAPTURE`` queue in the + middle of the drain sequence, the drain sequence is canceled and all + ``CAPTURE`` buffers are implicitly returned to the client. + + * If :c:func:`VIDIOC_STREAMOFF` is called on the ``OUTPUT`` queue in the + middle of the drain sequence, the drain sequence completes immediately and + next ``CAPTURE`` buffer will be returned empty with the + ``V4L2_BUF_FLAG_LAST`` flag set. + + Although not mandatory, the availability of encoder commands may be queried + using :c:func:`VIDIOC_TRY_ENCODER_CMD`. + +Reset +===== + +The client may want to request the encoder to reinitialize the encoding, so +that the following stream data becomes independent from the stream data +generated before. Depending on the coded format, that may imply that: + +* encoded frames produced after the restart must not reference any frames + produced before the stop, e.g. no long term references for H.264/HEVC, + +* any headers that must be included in a standalone stream must be produced + again, e.g. SPS and PPS for H.264/HEVC. + +This can be achieved by performing the reset sequence. + +1. Perform the `Drain` sequence to ensure all the in-flight encoding finishes + and respective buffers are dequeued. + +2. Stop streaming on the ``CAPTURE`` queue via :c:func:`VIDIOC_STREAMOFF`. This + will return all currently queued ``CAPTURE`` buffers to the client, without + valid frame data. + +3. Start streaming on the ``CAPTURE`` queue via :c:func:`VIDIOC_STREAMON` and + continue with regular encoding sequence. The encoded frames produced into + ``CAPTURE`` buffers from now on will contain a standalone stream that can be + decoded without the need for frames encoded before the reset sequence, + starting at the first ``OUTPUT`` buffer queued after issuing the + `V4L2_ENC_CMD_STOP` of the `Drain` sequence. + +This sequence may be also used to change encoding parameters for encoders +without the ability to change the parameters on the fly. + +Commit Points +============= + +Setting formats and allocating buffers triggers changes in the behavior of the +encoder. + +1. Setting the format on the ``CAPTURE`` queue may change the set of formats + supported/advertised on the ``OUTPUT`` queue. In particular, it also means + that the ``OUTPUT`` format may be reset and the client must not rely on the + previously set format being preserved. + +2. Enumerating formats on the ``OUTPUT`` queue always returns only formats + supported for the current ``CAPTURE`` format. + +3. Setting the format on the ``OUTPUT`` queue does not change the list of + formats available on the ``CAPTURE`` queue. An attempt to set the ``OUTPUT`` + format that is not supported for the currently selected ``CAPTURE`` format + will result in the encoder adjusting the requested ``OUTPUT`` format to a + supported one. + +4. Enumerating formats on the ``CAPTURE`` queue always returns the full set of + supported coded formats, irrespective of the current ``OUTPUT`` format. + +5. While buffers are allocated on any of the ``OUTPUT`` or ``CAPTURE`` queues, + the client must not change the format on the ``CAPTURE`` queue. Drivers will + return the -EBUSY error code for any such format change attempt. + +To summarize, setting formats and allocation must always start with the +``CAPTURE`` queue and the ``CAPTURE`` queue is the master that governs the +set of supported formats for the ``OUTPUT`` queue. diff --git a/Documentation/userspace-api/media/v4l/dev-mem2mem.rst b/Documentation/userspace-api/media/v4l/dev-mem2mem.rst index 9279d87c08a1..40aff9c95267 100644 --- a/Documentation/userspace-api/media/v4l/dev-mem2mem.rst +++ b/Documentation/userspace-api/media/v4l/dev-mem2mem.rst @@ -46,4 +46,5 @@ devices are given in the following sections. :maxdepth: 1 dev-decoder + dev-encoder dev-stateless-decoder diff --git a/Documentation/userspace-api/media/v4l/dev-osd.rst b/Documentation/userspace-api/media/v4l/dev-osd.rst index 67dc46373a91..ad0c156c7898 100644 --- a/Documentation/userspace-api/media/v4l/dev-osd.rst +++ b/Documentation/userspace-api/media/v4l/dev-osd.rst @@ -51,7 +51,7 @@ other information, the physical address of the framebuffer in the ``base`` field of struct :c:type:`v4l2_framebuffer`. The framebuffer device ioctl ``FBIOGET_FSCREENINFO`` returns the same address in the ``smem_start`` field of struct -struct :c:type:`fb_fix_screeninfo`. The ``FBIOGET_FSCREENINFO`` +:c:type:`fb_fix_screeninfo`. The ``FBIOGET_FSCREENINFO`` ioctl and struct :c:type:`fb_fix_screeninfo` are defined in the ``linux/fb.h`` header file. diff --git a/Documentation/userspace-api/media/v4l/dev-sdr.rst b/Documentation/userspace-api/media/v4l/dev-sdr.rst index c9563bca444e..4a80319a53c6 100644 --- a/Documentation/userspace-api/media/v4l/dev-sdr.rst +++ b/Documentation/userspace-api/media/v4l/dev-sdr.rst @@ -78,7 +78,7 @@ field of a struct :c:type:`v4l2_format` to ``V4L2_BUF_TYPE_SDR_CAPTURE`` or ``V4L2_BUF_TYPE_SDR_OUTPUT`` and use the struct :c:type:`v4l2_sdr_format` ``sdr`` member of the ``fmt`` union as needed per the desired operation. Currently -there is two fields, ``pixelformat`` and ``buffersize``, of struct +there are two fields, ``pixelformat`` and ``buffersize``, of struct :c:type:`v4l2_sdr_format` which are used. Content of the ``pixelformat`` is V4L2 FourCC code of the data format. The ``buffersize`` field is maximum buffer size in bytes required for diff --git a/Documentation/userspace-api/media/v4l/hist-v4l2.rst b/Documentation/userspace-api/media/v4l/hist-v4l2.rst index 7913d017cd33..6dcfe6046e33 100644 --- a/Documentation/userspace-api/media/v4l/hist-v4l2.rst +++ b/Documentation/userspace-api/media/v4l/hist-v4l2.rst @@ -43,7 +43,7 @@ transmission arguments. 1998-09-28: Revamped video standard. Made video controls individually enumerable. -1998-10-02: The ``id`` field was removed from struct +1998-10-02: The ``id`` field was removed from struct ``video_standard`` and the color subcarrier fields were renamed. The :ref:`VIDIOC_QUERYSTD` ioctl was renamed to :ref:`VIDIOC_ENUMSTD`, @@ -260,7 +260,7 @@ multiple tuners into account.) 2000-09-18: ``V4L2_BUF_TYPE_VBI`` was added. This may *break compatibility* as the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and -:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls may fail now if the struct +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls may fail now if the struct ``v4l2_fmt`` ``type`` field does not contain ``V4L2_BUF_TYPE_VBI``. In the documentation of the struct :c:type:`v4l2_vbi_format` ``offset`` field the diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst index ec1239ada316..e2f5a2b36092 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst @@ -69,37 +69,37 @@ Each cell is one byte. B\ :sub:`00low bits 5--0`\ (bits 5--0) - - R\ :sub:`02low bits 3--0`\ (bits 7--4) + - B\ :sub:`02low bits 3--0`\ (bits 7--4) G\ :sub:`01low bits 5--2`\ (bits 3--0) - G\ :sub:`03low bits 5--0`\ (bits 7--2) - R\ :sub:`02low bits 5--4`\ (bits 1--0) + B\ :sub:`02low bits 5--4`\ (bits 1--0) - .. row 2 - start + 7 - - G\ :sub:`00high` + - G\ :sub:`10high` - - R\ :sub:`01high` + - R\ :sub:`11high` - - G\ :sub:`02high` + - G\ :sub:`12high` - - R\ :sub:`03high` + - R\ :sub:`13high` - - R\ :sub:`01low bits 1--0`\ (bits 7--6) + - R\ :sub:`11low bits 1--0`\ (bits 7--6) - G\ :sub:`00low bits 5--0`\ (bits 5--0) + G\ :sub:`10low bits 5--0`\ (bits 5--0) - - G\ :sub:`02low bits 3--0`\ (bits 7--4) + - G\ :sub:`12low bits 3--0`\ (bits 7--4) - R\ :sub:`01low bits 5--2`\ (bits 3--0) + R\ :sub:`11low bits 5--2`\ (bits 3--0) - - R\ :sub:`03low bits 5--0`\ (bits 7--2) + - R\ :sub:`13low bits 5--0`\ (bits 7--2) - G\ :sub:`02low bits 5--4`\ (bits 1--0) + G\ :sub:`12low bits 5--4`\ (bits 1--0) - .. row 3 @@ -117,13 +117,13 @@ Each cell is one byte. B\ :sub:`20low bits 5--0`\ (bits 5--0) - - R\ :sub:`22low bits 3--0`\ (bits 7--4) + - B\ :sub:`22low bits 3--0`\ (bits 7--4) G\ :sub:`21low bits 5--2`\ (bits 3--0) - G\ :sub:`23low bits 5--0`\ (bits 7--2) - R\ :sub:`22low bits 5--4`\ (bits 1--0) + B\ :sub:`22low bits 5--4`\ (bits 1--0) - .. row 4 diff --git a/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst b/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst index 759420a872d6..e0ee2823ab1f 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst @@ -44,6 +44,11 @@ Single-planar format structure inside the stream, when fed to a stateful mem2mem decoder, the fields may be zero to rely on the decoder to detect the right values. For more details see :ref:`decoder` and format descriptions. + + For compressed formats on the CAPTURE side of a stateful mem2mem + encoder, the fields must be zero, since the coded size is expected to + be calculated internally by the encoder itself, based on the OUTPUT + side. For more details see :ref:`encoder` and format descriptions. * - __u32 - ``pixelformat`` - The pixel format or type of compression, set by the application. diff --git a/Documentation/userspace-api/media/v4l/v4l2.rst b/Documentation/userspace-api/media/v4l/v4l2.rst index ab7c97c39b97..35796c4fbe52 100644 --- a/Documentation/userspace-api/media/v4l/v4l2.rst +++ b/Documentation/userspace-api/media/v4l/v4l2.rst @@ -63,6 +63,7 @@ Authors, in alphabetical order: - Figa, Tomasz <tfiga@chromium.org> - Documented the memory-to-memory decoder interface. + - Documented the memory-to-memory encoder interface. - H Schimek, Michael <mschimek@gmx.at> @@ -75,6 +76,7 @@ Authors, in alphabetical order: - Osciak, Pawel <posciak@chromium.org> - Documented the memory-to-memory decoder interface. + - Documented the memory-to-memory encoder interface. - Osciak, Pawel <pawel@osciak.com> diff --git a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst index e1afc5b504c2..f2a702870fad 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst @@ -121,7 +121,12 @@ than the number requested. other changes, then set ``count`` to 0, ``memory`` to ``V4L2_MEMORY_MMAP`` and ``format.type`` to the buffer type. * - __u32 - - ``reserved``\ [7] + - ``flags`` + - Specifies additional buffer management attributes. + See :ref:`memory-flags`. + + * - __u32 + - ``reserved``\ [6] - A place holder for future extensions. Drivers and applications must set the array to zero. diff --git a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst index a9a176d5256d..9412be0c3747 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst @@ -260,7 +260,7 @@ call. :ref:`v4l2_queryctrl <v4l2-queryctrl>`. * - __s32 - ``default_value`` - - The default value value of the control. See struct + - The default value of the control. See struct :ref:`v4l2_queryctrl <v4l2-queryctrl>`. diff --git a/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst b/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst index 16269b3b1715..d0eacce5485e 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst @@ -51,25 +51,26 @@ To send a command applications must initialize all fields of a struct ``VIDIOC_ENCODER_CMD`` or ``VIDIOC_TRY_ENCODER_CMD`` with a pointer to this structure. -The ``cmd`` field must contain the command code. The ``flags`` field is -currently only used by the STOP command and contains one bit: If the -``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag is set, encoding will continue -until the end of the current *Group Of Pictures*, otherwise it will stop -immediately. +The ``cmd`` field must contain the command code. Some commands use the +``flags`` field for additional information. -A :ref:`read() <func-read>` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` -call sends an implicit START command to the encoder if it has not been -started yet. After a STOP command, :ref:`read() <func-read>` calls will read +After a STOP command, :ref:`read() <func-read>` calls will read the remaining data buffered by the driver. When the buffer is empty, :ref:`read() <func-read>` will return zero and the next :ref:`read() <func-read>` call will restart the encoder. +A :ref:`read() <func-read>` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` +call sends an implicit START command to the encoder if it has not been +started yet. Applies to both queues of mem2mem encoders. + A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call of a streaming file descriptor sends an implicit immediate STOP to -the encoder, and all buffered data is discarded. +the encoder, and all buffered data is discarded. Applies to both queues of +mem2mem encoders. These ioctls are optional, not all drivers may support them. They were -introduced in Linux 2.6.21. +introduced in Linux 2.6.21. They are, however, mandatory for stateful mem2mem +encoders (as further documented in :ref:`encoder`). .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -109,21 +110,24 @@ introduced in Linux 2.6.21. - 0 - Start the encoder. When the encoder is already running or paused, this command does nothing. No flags are defined for this command. + + For a device implementing the :ref:`encoder`, once the drain sequence + is initiated with the ``V4L2_ENC_CMD_STOP`` command, it must be driven + to completion before this command can be invoked. Any attempt to + invoke the command while the drain sequence is in progress will trigger + an ``EBUSY`` error code. See :ref:`encoder` for more details. * - ``V4L2_ENC_CMD_STOP`` - 1 - Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag is set, encoding will continue until the end of the current *Group Of Pictures*, otherwise encoding will stop immediately. When the - encoder is already stopped, this command does nothing. mem2mem - encoders will send a ``V4L2_EVENT_EOS`` event when the last frame - has been encoded and all frames are ready to be dequeued and will - set the ``V4L2_BUF_FLAG_LAST`` buffer flag on the last buffer of - the capture queue to indicate there will be no new buffers - produced to dequeue. This buffer may be empty, indicated by the - driver setting the ``bytesused`` field to 0. Once the - ``V4L2_BUF_FLAG_LAST`` flag was set, the - :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, - but return an ``EPIPE`` error code. + encoder is already stopped, this command does nothing. + + For a device implementing the :ref:`encoder`, the command will initiate + the drain sequence as documented in :ref:`encoder`. No flags or other + arguments are accepted in this case. Any attempt to invoke the command + again before the sequence completes will trigger an ``EBUSY`` error + code. * - ``V4L2_ENC_CMD_PAUSE`` - 2 - Pause the encoder. When the encoder has not been started yet, the @@ -152,6 +156,8 @@ introduced in Linux 2.6.21. - Stop encoding at the end of the current *Group Of Pictures*, rather than immediately. + Does not apply to :ref:`encoder`. + Return Value ============ @@ -160,6 +166,11 @@ On success 0 is returned, on error -1 and the ``errno`` variable is set appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. +EBUSY + A drain sequence of a device implementing the :ref:`encoder` is still in + progress. It is not allowed to issue another encoder command until it + completes. + EINVAL The ``cmd`` field is invalid. diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst index a53dd3d7f7e2..05835e04c20b 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst @@ -167,17 +167,37 @@ the ``mbus_code`` field is handled differently: - The hardware decoder for this compressed bytestream format (aka coded format) is capable of parsing a continuous bytestream. Applications do not need to parse the bytestream themselves to find the boundaries - between frames/fields. This flag can only be used in combination with - the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to compressed + between frames/fields. + + This flag can only be used in combination with the + ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to compressed formats only. This flag is valid for stateful decoders only. * - ``V4L2_FMT_FLAG_DYN_RESOLUTION`` - 0x0008 - Dynamic resolution switching is supported by the device for this compressed bytestream format (aka coded format). It will notify the user via the event ``V4L2_EVENT_SOURCE_CHANGE`` when changes in the video - parameters are detected. This flag can only be used in combination - with the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to - compressed formats only. It is also only applies to stateful codecs. + parameters are detected. + + This flag can only be used in combination with the + ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to + compressed formats only. This flag is valid for stateful codecs only. + * - ``V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL`` + - 0x0010 + - The hardware encoder supports setting the ``CAPTURE`` coded frame + interval separately from the ``OUTPUT`` raw frame interval. + Setting the ``OUTPUT`` raw frame interval with :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` + also sets the ``CAPTURE`` coded frame interval to the same value. + If this flag is set, then the ``CAPTURE`` coded frame interval can be + set to a different value afterwards. This is typically used for + offline encoding where the ``OUTPUT`` raw frame interval is used as + a hint for reserving hardware encoder resources and the ``CAPTURE`` coded + frame interval is the actual frame rate embedded in the encoded video + stream. + + This flag can only be used in combination with the + ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to + compressed formats only. This flag is valid for stateful encoders only. Return Value diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst index 42e9f6ee7a59..59e02aca164c 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst @@ -42,12 +42,13 @@ Arguments Description =========== -The current video standard determines a nominal number of frames per -second. If less than this number of frames is to be captured or output, -applications can request frame skipping or duplicating on the driver -side. This is especially useful when using the :ref:`read() <func-read>` or -:ref:`write() <func-write>`, which are not augmented by timestamps or sequence -counters, and to avoid unnecessary data copying. +Applications can request a different frame interval. The capture or +output device will be reconfigured to support the requested frame +interval if possible. Optionally drivers may choose to skip or +repeat frames to achieve the requested frame interval. + +For stateful encoders (see :ref:`encoder`) this represents the +frame interval that is typically embedded in the encoded video stream. Changing the frame interval shall never change the format. Changing the format, on the other hand, may change the frame interval. @@ -57,7 +58,8 @@ internally by a driver in read/write mode. For implications see the section discussing the :ref:`read() <func-read>` function. To get and set the streaming parameters applications call the -:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a +:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and +:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a pointer to a struct :c:type:`v4l2_streamparm` which contains a union holding separate parameters for input and output devices. @@ -113,14 +115,21 @@ union holding separate parameters for input and output devices. * - struct :c:type:`v4l2_fract` - ``timeperframe`` - This is the desired period between successive frames captured by - the driver, in seconds. The field is intended to skip frames on - the driver side, saving I/O bandwidth. + the driver, in seconds. + * - :cspan:`2` + + This will configure the speed at which the video source (e.g. a sensor) + generates video frames. If the speed is fixed, then the driver may + choose to skip or repeat frames in order to achieve the requested + frame rate. + + For stateful encoders (see :ref:`encoder`) this represents the + frame interval that is typically embedded in the encoded video stream. Applications store here the desired frame period, drivers return - the actual frame period, which must be greater or equal to the - nominal frame period determined by the current video standard - (struct :c:type:`v4l2_standard` ``frameperiod`` - field). Changing the video standard (also implicitly by switching + the actual frame period. + + Changing the video standard (also implicitly by switching the video input) may reset this parameter to the nominal frame period. To reset manually applications can just set this field to zero. @@ -173,11 +182,15 @@ union holding separate parameters for input and output devices. :ref:`write() <func-write>` mode (in streaming mode timestamps can be used to throttle the output), saving I/O bandwidth. + For stateful encoders (see :ref:`encoder`) this represents the + frame interval that is typically embedded in the encoded video stream + and it provides a hint to the encoder of the speed at which raw + frames are queued up to the encoder. + Applications store here the desired frame period, drivers return - the actual frame period, which must be greater or equal to the - nominal frame period determined by the current video standard - (struct :c:type:`v4l2_standard` ``frameperiod`` - field). Changing the video standard (also implicitly by switching + the actual frame period. + + Changing the video standard (also implicitly by switching the video output) may reset this parameter to the nominal frame period. To reset manually applications can just set this field to zero. @@ -216,8 +229,8 @@ union holding separate parameters for input and output devices. * - ``V4L2_CAP_TIMEPERFRAME`` - 0x1000 - - The frame skipping/repeating controlled by the ``timeperframe`` - field is supported. + - The frame period can be modified by setting the ``timeperframe`` + field. diff --git a/Documentation/userspace-api/media/v4l/vidioc-querycap.rst b/Documentation/userspace-api/media/v4l/vidioc-querycap.rst index 666ac4d42051..90347367ef06 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-querycap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-querycap.rst @@ -168,11 +168,11 @@ specification the ioctl returns an ``EINVAL`` error code. - The device supports the :ref:`multi-planar API <planar-apis>` through the :ref:`Video Output <output>` interface. * - ``V4L2_CAP_VIDEO_M2M`` - - 0x00004000 + - 0x00008000 - The device supports the single-planar API through the Video Memory-To-Memory interface. * - ``V4L2_CAP_VIDEO_M2M_MPLANE`` - - 0x00008000 + - 0x00004000 - The device supports the :ref:`multi-planar API <planar-apis>` through the Video Memory-To-Memory interface. * - ``V4L2_CAP_VIDEO_OVERLAY`` diff --git a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst index b6d52083707b..75d894d9c36c 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst @@ -112,10 +112,17 @@ aborting or finishing any DMA in progress, an implicit ``V4L2_MEMORY_MMAP`` and ``type`` set to the buffer type. This will free any previously allocated buffers, so this is typically something that will be done at the start of the application. + * - union { + - (anonymous) + * - __u32 + - ``flags`` + - Specifies additional buffer management attributes. + See :ref:`memory-flags`. * - __u32 - ``reserved``\ [1] - - A place holder for future extensions. Drivers and applications - must set the array to zero. + - Kept for backwards compatibility. Use ``flags`` instead. + * - } + - .. tabularcolumns:: |p{6.1cm}|p{2.2cm}|p{8.7cm}| @@ -126,6 +133,7 @@ aborting or finishing any DMA in progress, an implicit .. _V4L2-BUF-CAP-SUPPORTS-REQUESTS: .. _V4L2-BUF-CAP-SUPPORTS-ORPHANED-BUFS: .. _V4L2-BUF-CAP-SUPPORTS-M2M-HOLD-CAPTURE-BUF: +.. _V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS: .. cssclass:: longtable @@ -156,6 +164,15 @@ aborting or finishing any DMA in progress, an implicit - Only valid for stateless decoders. If set, then userspace can set the ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` flag to hold off on returning the capture buffer until the OUTPUT timestamp changes. + * - ``V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS`` + - 0x00000040 + - This capability is set by the driver to indicate that the queue supports + cache and memory management hints. However, it's only valid when the + queue is used for :ref:`memory mapping <mmap>` streaming I/O. See + :ref:`V4L2_FLAG_MEMORY_NON_CONSISTENT <V4L2-FLAG-MEMORY-NON-CONSISTENT>`, + :ref:`V4L2_BUF_FLAG_NO_CACHE_INVALIDATE <V4L2-BUF-FLAG-NO-CACHE-INVALIDATE>` and + :ref:`V4L2_BUF_FLAG_NO_CACHE_CLEAN <V4L2-BUF-FLAG-NO-CACHE-CLEAN>`. + Return Value ============ diff --git a/Documentation/userspace-api/media/videodev2.h.rst.exceptions b/Documentation/userspace-api/media/videodev2.h.rst.exceptions index a625fb90e3a9..ca05e4e126b2 100644 --- a/Documentation/userspace-api/media/videodev2.h.rst.exceptions +++ b/Documentation/userspace-api/media/videodev2.h.rst.exceptions @@ -187,6 +187,7 @@ replace define V4L2_FMT_FLAG_COMPRESSED fmtdesc-flags replace define V4L2_FMT_FLAG_EMULATED fmtdesc-flags replace define V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM fmtdesc-flags replace define V4L2_FMT_FLAG_DYN_RESOLUTION fmtdesc-flags +replace define V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL fmtdesc-flags # V4L2 timecode types replace define V4L2_TC_TYPE_24FPS timecode-type diff --git a/Documentation/virt/kvm/amd-memory-encryption.rst b/Documentation/virt/kvm/amd-memory-encryption.rst index 57c01f531e61..2d44388438cc 100644 --- a/Documentation/virt/kvm/amd-memory-encryption.rst +++ b/Documentation/virt/kvm/amd-memory-encryption.rst @@ -270,6 +270,6 @@ References See [white-paper]_, [api-spec]_, [amd-apm]_ and [kvm-forum]_ for more info. .. [white-paper] http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf -.. [api-spec] http://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf -.. [amd-apm] http://support.amd.com/TechDocs/24593.pdf (section 15.34) -.. [kvm-forum] http://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf +.. [api-spec] https://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf +.. [amd-apm] https://support.amd.com/TechDocs/24593.pdf (section 15.34) +.. [kvm-forum] https://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 426f94582b7a..eb3a1316f03e 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -65,7 +65,7 @@ not be freed until both the parent (original) process and its child have put their references to the VM's file descriptor. Because a VM's resources are not freed until the last reference to its -file descriptor is released, creating additional references to a VM via +file descriptor is released, creating additional references to a VM via fork(), dup(), etc... without careful consideration is strongly discouraged and may have unwanted side effects, e.g. memory allocated by and on behalf of the VM's process may not be freed/unaccounted when @@ -536,7 +536,7 @@ X86: ========= =================================== 0 on success, -EEXIST if an interrupt is already enqueued - -EINVAL the the irq number is invalid + -EINVAL the irq number is invalid -ENXIO if the PIC is in the kernel -EFAULT if the pointer is invalid ========= =================================== @@ -669,6 +669,10 @@ MSRs that have been set successfully. Defines the vcpu responses to the cpuid instruction. Applications should use the KVM_SET_CPUID2 ioctl if available. +Note, when this IOCTL fails, KVM gives no guarantees that previous valid CPUID +configuration (if there is) is not corrupted. Userspace can get a copy of the +resulting CPUID configuration through KVM_GET_CPUID2 in case. + :: struct kvm_cpuid_entry { @@ -2156,9 +2160,12 @@ registers, find a list below: PPC KVM_REG_PPC_MMCRA 64 PPC KVM_REG_PPC_MMCR2 64 PPC KVM_REG_PPC_MMCRS 64 + PPC KVM_REG_PPC_MMCR3 64 PPC KVM_REG_PPC_SIAR 64 PPC KVM_REG_PPC_SDAR 64 PPC KVM_REG_PPC_SIER 64 + PPC KVM_REG_PPC_SIER2 64 + PPC KVM_REG_PPC_SIER3 64 PPC KVM_REG_PPC_PMC1 32 PPC KVM_REG_PPC_PMC2 32 PPC KVM_REG_PPC_PMC3 32 @@ -3147,7 +3154,7 @@ Possible features: :Capability: basic :Architectures: arm, arm64 :Type: vm ioctl -:Parameters: struct struct kvm_vcpu_init (out) +:Parameters: struct kvm_vcpu_init (out) :Returns: 0 on success; -1 on error Errors: @@ -3167,7 +3174,7 @@ not mandatory. The information returned by this ioctl can be used to prepare an instance of struct kvm_vcpu_init for KVM_ARM_VCPU_INIT ioctl which will result in -in VCPU matching underlying host. +VCPU matching underlying host. 4.84 KVM_GET_REG_LIST @@ -4339,14 +4346,15 @@ Errors: #define KVM_STATE_VMX_PREEMPTION_TIMER_DEADLINE 0x00000001 struct kvm_vmx_nested_state_hdr { - __u32 flags; __u64 vmxon_pa; __u64 vmcs12_pa; - __u64 preemption_timer_deadline; struct { __u16 flags; } smm; + + __u32 flags; + __u64 preemption_timer_deadline; }; struct kvm_vmx_nested_state_data { @@ -4794,6 +4802,7 @@ hardware_exit_reason. /* KVM_EXIT_FAIL_ENTRY */ struct { __u64 hardware_entry_failure_reason; + __u32 cpu; /* if KVM_LAST_CPU */ } fail_entry; If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due @@ -5855,7 +5864,7 @@ features of the KVM implementation. :Architectures: ppc This capability, if KVM_CHECK_EXTENSION indicates that it is -available, means that that the kernel has an implementation of the +available, means that the kernel has an implementation of the H_RANDOM hypercall backed by a hardware random-number generator. If present, the kernel H_RANDOM handler can be enabled for guest use with the KVM_CAP_PPC_ENABLE_HCALL capability. @@ -5866,7 +5875,7 @@ with the KVM_CAP_PPC_ENABLE_HCALL capability. :Architectures: x86 This capability, if KVM_CHECK_EXTENSION indicates that it is -available, means that that the kernel has an implementation of the +available, means that the kernel has an implementation of the Hyper-V Synthetic interrupt controller(SynIC). Hyper-V SynIC is used to support Windows Hyper-V based guest paravirt drivers(VMBus). @@ -5881,7 +5890,7 @@ by the CPU, as it's incompatible with SynIC auto-EOI behavior. :Architectures: ppc This capability, if KVM_CHECK_EXTENSION indicates that it is -available, means that that the kernel can support guests using the +available, means that the kernel can support guests using the radix MMU defined in Power ISA V3.00 (as implemented in the POWER9 processor). @@ -5891,7 +5900,7 @@ processor). :Architectures: ppc This capability, if KVM_CHECK_EXTENSION indicates that it is -available, means that that the kernel can support guests using the +available, means that the kernel can support guests using the hashed page table MMU defined in Power ISA V3.00 (as implemented in the POWER9 processor), including in-memory segment tables. @@ -5996,7 +6005,7 @@ run->kvm_valid_regs or run->kvm_dirty_regs bits. If KVM_CAP_ARM_USER_IRQ is supported, the KVM_CHECK_EXTENSION ioctl returns a number larger than 0 indicating the version of this capability is implemented -and thereby which bits in in run->s.regs.device_irq_level can signal values. +and thereby which bits in run->s.regs.device_irq_level can signal values. Currently the following bits are defined for the device_irq_level bitmap:: diff --git a/Documentation/virt/kvm/mmu.rst b/Documentation/virt/kvm/mmu.rst index 46126ecc70f7..1c030dbac7c4 100644 --- a/Documentation/virt/kvm/mmu.rst +++ b/Documentation/virt/kvm/mmu.rst @@ -480,4 +480,4 @@ Further reading =============== - NPT presentation from KVM Forum 2008 - http://www.linux-kvm.org/images/c/c8/KvmForum2008%24kdf2008_21.pdf + https://www.linux-kvm.org/images/c/c8/KvmForum2008%24kdf2008_21.pdf diff --git a/Documentation/virt/kvm/nested-vmx.rst b/Documentation/virt/kvm/nested-vmx.rst index 89851cbb7df9..6ab4e35cee23 100644 --- a/Documentation/virt/kvm/nested-vmx.rst +++ b/Documentation/virt/kvm/nested-vmx.rst @@ -22,7 +22,7 @@ its implementation and its performance characteristics, in the OSDI 2010 paper "The Turtles Project: Design and Implementation of Nested Virtualization", available at: - http://www.usenix.org/events/osdi10/tech/full_papers/Ben-Yehuda.pdf + https://www.usenix.org/events/osdi10/tech/full_papers/Ben-Yehuda.pdf Terminology diff --git a/Documentation/virt/kvm/s390-pv.rst b/Documentation/virt/kvm/s390-pv.rst index 774a8c606091..8e41a3b63fa5 100644 --- a/Documentation/virt/kvm/s390-pv.rst +++ b/Documentation/virt/kvm/s390-pv.rst @@ -78,7 +78,7 @@ Register Save Area. Only GR values needed to emulate an instruction will be copied into this save area and the real register numbers will be hidden. -The Interception Parameters state description field still contains the +The Interception Parameters state description field still contains the bytes of the instruction text, but with pre-set register values instead of the actual ones. I.e. each instruction always uses the same instruction text, in order not to leak guest instruction text. diff --git a/Documentation/vm/arch_pgtable_helpers.rst b/Documentation/vm/arch_pgtable_helpers.rst new file mode 100644 index 000000000000..f3591ee3aaa8 --- /dev/null +++ b/Documentation/vm/arch_pgtable_helpers.rst @@ -0,0 +1,258 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _arch_page_table_helpers: + +=============================== +Architecture Page Table Helpers +=============================== + +Generic MM expects architectures (with MMU) to provide helpers to create, access +and modify page table entries at various level for different memory functions. +These page table helpers need to conform to a common semantics across platforms. +Following tables describe the expected semantics which can also be tested during +boot via CONFIG_DEBUG_VM_PGTABLE option. All future changes in here or the debug +test need to be in sync. + +====================== +PTE Page Table Helpers +====================== + ++---------------------------+--------------------------------------------------+ +| pte_same | Tests whether both PTE entries are the same | ++---------------------------+--------------------------------------------------+ +| pte_bad | Tests a non-table mapped PTE | ++---------------------------+--------------------------------------------------+ +| pte_present | Tests a valid mapped PTE | ++---------------------------+--------------------------------------------------+ +| pte_young | Tests a young PTE | ++---------------------------+--------------------------------------------------+ +| pte_dirty | Tests a dirty PTE | ++---------------------------+--------------------------------------------------+ +| pte_write | Tests a writable PTE | ++---------------------------+--------------------------------------------------+ +| pte_special | Tests a special PTE | ++---------------------------+--------------------------------------------------+ +| pte_protnone | Tests a PROT_NONE PTE | ++---------------------------+--------------------------------------------------+ +| pte_devmap | Tests a ZONE_DEVICE mapped PTE | ++---------------------------+--------------------------------------------------+ +| pte_soft_dirty | Tests a soft dirty PTE | ++---------------------------+--------------------------------------------------+ +| pte_swp_soft_dirty | Tests a soft dirty swapped PTE | ++---------------------------+--------------------------------------------------+ +| pte_mkyoung | Creates a young PTE | ++---------------------------+--------------------------------------------------+ +| pte_mkold | Creates an old PTE | ++---------------------------+--------------------------------------------------+ +| pte_mkdirty | Creates a dirty PTE | ++---------------------------+--------------------------------------------------+ +| pte_mkclean | Creates a clean PTE | ++---------------------------+--------------------------------------------------+ +| pte_mkwrite | Creates a writable PTE | ++---------------------------+--------------------------------------------------+ +| pte_mkwrprotect | Creates a write protected PTE | ++---------------------------+--------------------------------------------------+ +| pte_mkspecial | Creates a special PTE | ++---------------------------+--------------------------------------------------+ +| pte_mkdevmap | Creates a ZONE_DEVICE mapped PTE | ++---------------------------+--------------------------------------------------+ +| pte_mksoft_dirty | Creates a soft dirty PTE | ++---------------------------+--------------------------------------------------+ +| pte_clear_soft_dirty | Clears a soft dirty PTE | ++---------------------------+--------------------------------------------------+ +| pte_swp_mksoft_dirty | Creates a soft dirty swapped PTE | ++---------------------------+--------------------------------------------------+ +| pte_swp_clear_soft_dirty | Clears a soft dirty swapped PTE | ++---------------------------+--------------------------------------------------+ +| pte_mknotpresent | Invalidates a mapped PTE | ++---------------------------+--------------------------------------------------+ +| ptep_get_and_clear | Clears a PTE | ++---------------------------+--------------------------------------------------+ +| ptep_get_and_clear_full | Clears a PTE | ++---------------------------+--------------------------------------------------+ +| ptep_test_and_clear_young | Clears young from a PTE | ++---------------------------+--------------------------------------------------+ +| ptep_set_wrprotect | Converts into a write protected PTE | ++---------------------------+--------------------------------------------------+ +| ptep_set_access_flags | Converts into a more permissive PTE | ++---------------------------+--------------------------------------------------+ + +====================== +PMD Page Table Helpers +====================== + ++---------------------------+--------------------------------------------------+ +| pmd_same | Tests whether both PMD entries are the same | ++---------------------------+--------------------------------------------------+ +| pmd_bad | Tests a non-table mapped PMD | ++---------------------------+--------------------------------------------------+ +| pmd_leaf | Tests a leaf mapped PMD | ++---------------------------+--------------------------------------------------+ +| pmd_huge | Tests a HugeTLB mapped PMD | ++---------------------------+--------------------------------------------------+ +| pmd_trans_huge | Tests a Transparent Huge Page (THP) at PMD | ++---------------------------+--------------------------------------------------+ +| pmd_present | Tests a valid mapped PMD | ++---------------------------+--------------------------------------------------+ +| pmd_young | Tests a young PMD | ++---------------------------+--------------------------------------------------+ +| pmd_dirty | Tests a dirty PMD | ++---------------------------+--------------------------------------------------+ +| pmd_write | Tests a writable PMD | ++---------------------------+--------------------------------------------------+ +| pmd_special | Tests a special PMD | ++---------------------------+--------------------------------------------------+ +| pmd_protnone | Tests a PROT_NONE PMD | ++---------------------------+--------------------------------------------------+ +| pmd_devmap | Tests a ZONE_DEVICE mapped PMD | ++---------------------------+--------------------------------------------------+ +| pmd_soft_dirty | Tests a soft dirty PMD | ++---------------------------+--------------------------------------------------+ +| pmd_swp_soft_dirty | Tests a soft dirty swapped PMD | ++---------------------------+--------------------------------------------------+ +| pmd_mkyoung | Creates a young PMD | ++---------------------------+--------------------------------------------------+ +| pmd_mkold | Creates an old PMD | ++---------------------------+--------------------------------------------------+ +| pmd_mkdirty | Creates a dirty PMD | ++---------------------------+--------------------------------------------------+ +| pmd_mkclean | Creates a clean PMD | ++---------------------------+--------------------------------------------------+ +| pmd_mkwrite | Creates a writable PMD | ++---------------------------+--------------------------------------------------+ +| pmd_mkwrprotect | Creates a write protected PMD | ++---------------------------+--------------------------------------------------+ +| pmd_mkspecial | Creates a special PMD | ++---------------------------+--------------------------------------------------+ +| pmd_mkdevmap | Creates a ZONE_DEVICE mapped PMD | ++---------------------------+--------------------------------------------------+ +| pmd_mksoft_dirty | Creates a soft dirty PMD | ++---------------------------+--------------------------------------------------+ +| pmd_clear_soft_dirty | Clears a soft dirty PMD | ++---------------------------+--------------------------------------------------+ +| pmd_swp_mksoft_dirty | Creates a soft dirty swapped PMD | ++---------------------------+--------------------------------------------------+ +| pmd_swp_clear_soft_dirty | Clears a soft dirty swapped PMD | ++---------------------------+--------------------------------------------------+ +| pmd_mkinvalid | Invalidates a mapped PMD [1] | ++---------------------------+--------------------------------------------------+ +| pmd_set_huge | Creates a PMD huge mapping | ++---------------------------+--------------------------------------------------+ +| pmd_clear_huge | Clears a PMD huge mapping | ++---------------------------+--------------------------------------------------+ +| pmdp_get_and_clear | Clears a PMD | ++---------------------------+--------------------------------------------------+ +| pmdp_get_and_clear_full | Clears a PMD | ++---------------------------+--------------------------------------------------+ +| pmdp_test_and_clear_young | Clears young from a PMD | ++---------------------------+--------------------------------------------------+ +| pmdp_set_wrprotect | Converts into a write protected PMD | ++---------------------------+--------------------------------------------------+ +| pmdp_set_access_flags | Converts into a more permissive PMD | ++---------------------------+--------------------------------------------------+ + +====================== +PUD Page Table Helpers +====================== + ++---------------------------+--------------------------------------------------+ +| pud_same | Tests whether both PUD entries are the same | ++---------------------------+--------------------------------------------------+ +| pud_bad | Tests a non-table mapped PUD | ++---------------------------+--------------------------------------------------+ +| pud_leaf | Tests a leaf mapped PUD | ++---------------------------+--------------------------------------------------+ +| pud_huge | Tests a HugeTLB mapped PUD | ++---------------------------+--------------------------------------------------+ +| pud_trans_huge | Tests a Transparent Huge Page (THP) at PUD | ++---------------------------+--------------------------------------------------+ +| pud_present | Tests a valid mapped PUD | ++---------------------------+--------------------------------------------------+ +| pud_young | Tests a young PUD | ++---------------------------+--------------------------------------------------+ +| pud_dirty | Tests a dirty PUD | ++---------------------------+--------------------------------------------------+ +| pud_write | Tests a writable PUD | ++---------------------------+--------------------------------------------------+ +| pud_devmap | Tests a ZONE_DEVICE mapped PUD | ++---------------------------+--------------------------------------------------+ +| pud_mkyoung | Creates a young PUD | ++---------------------------+--------------------------------------------------+ +| pud_mkold | Creates an old PUD | ++---------------------------+--------------------------------------------------+ +| pud_mkdirty | Creates a dirty PUD | ++---------------------------+--------------------------------------------------+ +| pud_mkclean | Creates a clean PUD | ++---------------------------+--------------------------------------------------+ +| pud_mkwrite | Creates a writable PUD | ++---------------------------+--------------------------------------------------+ +| pud_mkwrprotect | Creates a write protected PUD | ++---------------------------+--------------------------------------------------+ +| pud_mkdevmap | Creates a ZONE_DEVICE mapped PUD | ++---------------------------+--------------------------------------------------+ +| pud_mkinvalid | Invalidates a mapped PUD [1] | ++---------------------------+--------------------------------------------------+ +| pud_set_huge | Creates a PUD huge mapping | ++---------------------------+--------------------------------------------------+ +| pud_clear_huge | Clears a PUD huge mapping | ++---------------------------+--------------------------------------------------+ +| pudp_get_and_clear | Clears a PUD | ++---------------------------+--------------------------------------------------+ +| pudp_get_and_clear_full | Clears a PUD | ++---------------------------+--------------------------------------------------+ +| pudp_test_and_clear_young | Clears young from a PUD | ++---------------------------+--------------------------------------------------+ +| pudp_set_wrprotect | Converts into a write protected PUD | ++---------------------------+--------------------------------------------------+ +| pudp_set_access_flags | Converts into a more permissive PUD | ++---------------------------+--------------------------------------------------+ + +========================== +HugeTLB Page Table Helpers +========================== + ++---------------------------+--------------------------------------------------+ +| pte_huge | Tests a HugeTLB | ++---------------------------+--------------------------------------------------+ +| pte_mkhuge | Creates a HugeTLB | ++---------------------------+--------------------------------------------------+ +| huge_pte_dirty | Tests a dirty HugeTLB | ++---------------------------+--------------------------------------------------+ +| huge_pte_write | Tests a writable HugeTLB | ++---------------------------+--------------------------------------------------+ +| huge_pte_mkdirty | Creates a dirty HugeTLB | ++---------------------------+--------------------------------------------------+ +| huge_pte_mkwrite | Creates a writable HugeTLB | ++---------------------------+--------------------------------------------------+ +| huge_pte_mkwrprotect | Creates a write protected HugeTLB | ++---------------------------+--------------------------------------------------+ +| huge_ptep_get_and_clear | Clears a HugeTLB | ++---------------------------+--------------------------------------------------+ +| huge_ptep_set_wrprotect | Converts into a write protected HugeTLB | ++---------------------------+--------------------------------------------------+ +| huge_ptep_set_access_flags | Converts into a more permissive HugeTLB | ++---------------------------+--------------------------------------------------+ + +======================== +SWAP Page Table Helpers +======================== + ++---------------------------+--------------------------------------------------+ +| __pte_to_swp_entry | Creates a swapped entry (arch) from a mapped PTE | ++---------------------------+--------------------------------------------------+ +| __swp_to_pte_entry | Creates a mapped PTE from a swapped entry (arch) | ++---------------------------+--------------------------------------------------+ +| __pmd_to_swp_entry | Creates a swapped entry (arch) from a mapped PMD | ++---------------------------+--------------------------------------------------+ +| __swp_to_pmd_entry | Creates a mapped PMD from a swapped entry (arch) | ++---------------------------+--------------------------------------------------+ +| is_migration_entry | Tests a migration (read or write) swapped entry | ++---------------------------+--------------------------------------------------+ +| is_write_migration_entry | Tests a write migration swapped entry | ++---------------------------+--------------------------------------------------+ +| make_migration_entry_read | Converts into read migration swapped entry | ++---------------------------+--------------------------------------------------+ +| make_migration_entry | Creates a migration swapped entry (read or write)| ++---------------------------+--------------------------------------------------+ + +[1] https://lore.kernel.org/linux-mm/20181017020930.GN30832@redhat.com/ diff --git a/Documentation/vm/memory-model.rst b/Documentation/vm/memory-model.rst index 91228044ed16..769449734573 100644 --- a/Documentation/vm/memory-model.rst +++ b/Documentation/vm/memory-model.rst @@ -141,11 +141,8 @@ sections: `mem_section` objects and the number of rows is calculated to fit all the memory sections. -The architecture setup code should call :c:func:`memory_present` for -each active memory range or use :c:func:`memblocks_present` or -:c:func:`sparse_memory_present_with_active_regions` wrappers to -initialize the memory sections. Next, the actual memory maps should be -set up using :c:func:`sparse_init`. +The architecture setup code should call sparse_init() to +initialize the memory sections and the memory maps. With SPARSEMEM there are two possible ways to convert a PFN to the corresponding `struct page` - a "classic sparse" and "sparse @@ -159,7 +156,7 @@ frame. Inside a section, the PFN is the index to the array of pages. The sparse vmemmap uses a virtually mapped memory map to optimize pfn_to_page and page_to_pfn operations. There is a global `struct page *vmemmap` pointer that points to a virtually contiguous array of -`struct page` objects. A PFN is an index to that array and the the +`struct page` objects. A PFN is an index to that array and the offset of the `struct page` from `vmemmap` is the PFN of that page. @@ -178,7 +175,7 @@ for persistent memory devices in pre-allocated storage on those devices. This storage is represented with :c:type:`struct vmem_altmap` that is eventually passed to vmemmap_populate() through a long chain of function calls. The vmemmap_populate() implementation may use the -`vmem_altmap` along with :c:func:`altmap_alloc_block_buf` helper to +`vmem_altmap` along with :c:func:`vmemmap_alloc_block_buf` helper to allocate memory map on the persistent memory device. ZONE_DEVICE diff --git a/Documentation/vm/slub.rst b/Documentation/vm/slub.rst index 4eee598555c9..289d231cee97 100644 --- a/Documentation/vm/slub.rst +++ b/Documentation/vm/slub.rst @@ -41,6 +41,11 @@ slub_debug=<Debug-Options>,<slab name1>,<slab name2>,... Enable options only for select slabs (no spaces after a comma) +Multiple blocks of options for all slabs or selected slabs can be given, with +blocks of options delimited by ';'. The last of "all slabs" blocks is applied +to all slabs except those that match one of the "select slabs" block. Options +of the first "select slabs" blocks that matches the slab's name are applied. + Possible debug options are:: F Sanity checks on (enables SLAB_DEBUG_CONSISTENCY_CHECKS @@ -83,17 +88,33 @@ switch off debugging for such caches by default, use:: slub_debug=O -In case you forgot to enable debugging on the kernel command line: It is -possible to enable debugging manually when the kernel is up. Look at the -contents of:: +You can apply different options to different list of slab names, using blocks +of options. This will enable red zoning for dentry and user tracking for +kmalloc. All other slabs will not get any debugging enabled:: + + slub_debug=Z,dentry;U,kmalloc-* + +You can also enable options (e.g. sanity checks and poisoning) for all caches +except some that are deemed too performance critical and don't need to be +debugged by specifying global debug options followed by a list of slab names +with "-" as options:: + + slub_debug=FZ;-,zs_handle,zspage + +The state of each debug option for a slab can be found in the respective files +under:: /sys/kernel/slab/<slab name>/ -Look at the writable files. Writing 1 to them will enable the -corresponding debug option. All options can be set on a slab that does -not contain objects. If the slab already contains objects then sanity checks -and tracing may only be enabled. The other options may cause the realignment -of objects. +If the file contains 1, the option is enabled, 0 means disabled. The debug +options from the ``slub_debug`` parameter translate to the following files:: + + F sanity_checks + Z red_zone + P poison + U store_user + T trace + A failslab Careful with tracing: It may spew out lots of information and never stop if used on the wrong slab. diff --git a/Documentation/x86/boot.rst b/Documentation/x86/boot.rst index 5325c71ca877..7fafc7ac00d7 100644 --- a/Documentation/x86/boot.rst +++ b/Documentation/x86/boot.rst @@ -782,9 +782,9 @@ Protocol: 2.08+ uncompressed data should be determined using the standard magic numbers. The currently supported compression formats are gzip (magic numbers 1F 8B or 1F 9E), bzip2 (magic number 42 5A), LZMA - (magic number 5D 00), XZ (magic number FD 37), and LZ4 (magic number - 02 21). The uncompressed payload is currently always ELF (magic - number 7F 45 4C 46). + (magic number 5D 00), XZ (magic number FD 37), LZ4 (magic number + 02 21) and ZSTD (magic number 28 B5). The uncompressed payload is + currently always ELF (magic number 7F 45 4C 46). ============ ============== Field name: payload_length diff --git a/Documentation/x86/earlyprintk.rst b/Documentation/x86/earlyprintk.rst index 11307378acf0..51ef11e8f725 100644 --- a/Documentation/x86/earlyprintk.rst +++ b/Documentation/x86/earlyprintk.rst @@ -8,7 +8,7 @@ Mini-HOWTO for using the earlyprintk=dbgp boot option with a USB2 Debug port key and a debug cable, on x86 systems. You need two computers, the 'USB debug key' special gadget and -and two USB cables, connected like this:: +two USB cables, connected like this:: [host/target] <-------> [USB debug key] <-------> [client/console] diff --git a/Documentation/x86/x86_64/fsgs.rst b/Documentation/x86/x86_64/fsgs.rst new file mode 100644 index 000000000000..50960e09e1f6 --- /dev/null +++ b/Documentation/x86/x86_64/fsgs.rst @@ -0,0 +1,199 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Using FS and GS segments in user space applications +=================================================== + +The x86 architecture supports segmentation. Instructions which access +memory can use segment register based addressing mode. The following +notation is used to address a byte within a segment: + + Segment-register:Byte-address + +The segment base address is added to the Byte-address to compute the +resulting virtual address which is accessed. This allows to access multiple +instances of data with the identical Byte-address, i.e. the same code. The +selection of a particular instance is purely based on the base-address in +the segment register. + +In 32-bit mode the CPU provides 6 segments, which also support segment +limits. The limits can be used to enforce address space protections. + +In 64-bit mode the CS/SS/DS/ES segments are ignored and the base address is +always 0 to provide a full 64bit address space. The FS and GS segments are +still functional in 64-bit mode. + +Common FS and GS usage +------------------------------ + +The FS segment is commonly used to address Thread Local Storage (TLS). FS +is usually managed by runtime code or a threading library. Variables +declared with the '__thread' storage class specifier are instantiated per +thread and the compiler emits the FS: address prefix for accesses to these +variables. Each thread has its own FS base address so common code can be +used without complex address offset calculations to access the per thread +instances. Applications should not use FS for other purposes when they use +runtimes or threading libraries which manage the per thread FS. + +The GS segment has no common use and can be used freely by +applications. GCC and Clang support GS based addressing via address space +identifiers. + +Reading and writing the FS/GS base address +------------------------------------------ + +There exist two mechanisms to read and write the FS/GS base address: + + - the arch_prctl() system call + + - the FSGSBASE instruction family + +Accessing FS/GS base with arch_prctl() +-------------------------------------- + + The arch_prctl(2) based mechanism is available on all 64-bit CPUs and all + kernel versions. + + Reading the base: + + arch_prctl(ARCH_GET_FS, &fsbase); + arch_prctl(ARCH_GET_GS, &gsbase); + + Writing the base: + + arch_prctl(ARCH_SET_FS, fsbase); + arch_prctl(ARCH_SET_GS, gsbase); + + The ARCH_SET_GS prctl may be disabled depending on kernel configuration + and security settings. + +Accessing FS/GS base with the FSGSBASE instructions +--------------------------------------------------- + + With the Ivy Bridge CPU generation Intel introduced a new set of + instructions to access the FS and GS base registers directly from user + space. These instructions are also supported on AMD Family 17H CPUs. The + following instructions are available: + + =============== =========================== + RDFSBASE %reg Read the FS base register + RDGSBASE %reg Read the GS base register + WRFSBASE %reg Write the FS base register + WRGSBASE %reg Write the GS base register + =============== =========================== + + The instructions avoid the overhead of the arch_prctl() syscall and allow + more flexible usage of the FS/GS addressing modes in user space + applications. This does not prevent conflicts between threading libraries + and runtimes which utilize FS and applications which want to use it for + their own purpose. + +FSGSBASE instructions enablement +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + The instructions are enumerated in CPUID leaf 7, bit 0 of EBX. If + available /proc/cpuinfo shows 'fsgsbase' in the flag entry of the CPUs. + + The availability of the instructions does not enable them + automatically. The kernel has to enable them explicitly in CR4. The + reason for this is that older kernels make assumptions about the values in + the GS register and enforce them when GS base is set via + arch_prctl(). Allowing user space to write arbitrary values to GS base + would violate these assumptions and cause malfunction. + + On kernels which do not enable FSGSBASE the execution of the FSGSBASE + instructions will fault with a #UD exception. + + The kernel provides reliable information about the enabled state in the + ELF AUX vector. If the HWCAP2_FSGSBASE bit is set in the AUX vector, the + kernel has FSGSBASE instructions enabled and applications can use them. + The following code example shows how this detection works:: + + #include <sys/auxv.h> + #include <elf.h> + + /* Will be eventually in asm/hwcap.h */ + #ifndef HWCAP2_FSGSBASE + #define HWCAP2_FSGSBASE (1 << 1) + #endif + + .... + + unsigned val = getauxval(AT_HWCAP2); + + if (val & HWCAP2_FSGSBASE) + printf("FSGSBASE enabled\n"); + +FSGSBASE instructions compiler support +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +GCC version 4.6.4 and newer provide instrinsics for the FSGSBASE +instructions. Clang 5 supports them as well. + + =================== =========================== + _readfsbase_u64() Read the FS base register + _readfsbase_u64() Read the GS base register + _writefsbase_u64() Write the FS base register + _writegsbase_u64() Write the GS base register + =================== =========================== + +To utilize these instrinsics <immintrin.h> must be included in the source +code and the compiler option -mfsgsbase has to be added. + +Compiler support for FS/GS based addressing +------------------------------------------- + +GCC version 6 and newer provide support for FS/GS based addressing via +Named Address Spaces. GCC implements the following address space +identifiers for x86: + + ========= ==================================== + __seg_fs Variable is addressed relative to FS + __seg_gs Variable is addressed relative to GS + ========= ==================================== + +The preprocessor symbols __SEG_FS and __SEG_GS are defined when these +address spaces are supported. Code which implements fallback modes should +check whether these symbols are defined. Usage example:: + + #ifdef __SEG_GS + + long data0 = 0; + long data1 = 1; + + long __seg_gs *ptr; + + /* Check whether FSGSBASE is enabled by the kernel (HWCAP2_FSGSBASE) */ + .... + + /* Set GS base to point to data0 */ + _writegsbase_u64(&data0); + + /* Access offset 0 of GS */ + ptr = 0; + printf("data0 = %ld\n", *ptr); + + /* Set GS base to point to data1 */ + _writegsbase_u64(&data1); + /* ptr still addresses offset 0! */ + printf("data1 = %ld\n", *ptr); + + +Clang does not provide the GCC address space identifiers, but it provides +address spaces via an attribute based mechanism in Clang 2.6 and newer +versions: + + ==================================== ===================================== + __attribute__((address_space(256)) Variable is addressed relative to GS + __attribute__((address_space(257)) Variable is addressed relative to FS + ==================================== ===================================== + +FS/GS based addressing with inline assembly +------------------------------------------- + +In case the compiler does not support address spaces, inline assembly can +be used for FS/GS based addressing mode:: + + mov %fs:offset, %reg + mov %gs:offset, %reg + + mov %reg, %fs:offset + mov %reg, %gs:offset diff --git a/Documentation/x86/x86_64/index.rst b/Documentation/x86/x86_64/index.rst index d6eaaa5a35fc..a56070fc8e77 100644 --- a/Documentation/x86/x86_64/index.rst +++ b/Documentation/x86/x86_64/index.rst @@ -14,3 +14,4 @@ x86_64 Support fake-numa-for-cpusets cpu-hotplug-spec machinecheck + fsgs diff --git a/Documentation/x86/x86_64/machinecheck.rst b/Documentation/x86/x86_64/machinecheck.rst index e189168406fa..b402e04bee60 100644 --- a/Documentation/x86/x86_64/machinecheck.rst +++ b/Documentation/x86/x86_64/machinecheck.rst @@ -81,5 +81,5 @@ TBD document entries for AMD threshold interrupt configuration For more details about the x86 machine check architecture see the Intel and AMD architecture manuals from their developer websites. -For more details about the architecture see +For more details about the architecture see http://one.firstfloor.org/~andi/mce.pdf |