diff options
| author |   Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2017-12-22 14:38:28 -0500 |
|---|---|---|
| committer | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2017-12-22 14:38:28 -0500 |
| commit | 9eb124fe796cbadd454c8f946d7051f4c3f4a251 (patch) | |
| tree | 357d21901062bf487d4c19d0495e630256d1eee3 /Documentation | |
| parent | media: coda/imx-vdoa: Remove irq member from vdoa_data struct (diff) | |
| parent | w1_netlink.h: add support for nested structs (diff) | |
| download | linux-dev-9eb124fe796cbadd454c8f946d7051f4c3f4a251.tar.xz linux-dev-9eb124fe796cbadd454c8f946d7051f4c3f4a251.zip | |
Merge branch 'docs-next' of git://git.lwn.net/linux into patchwork
* 'docs-next' of git://git.lwn.net/linux: (888 commits)
w1_netlink.h: add support for nested structs
scripts: kernel-doc: apply filtering rules to warnings
scripts: kernel-doc: improve nested logic to handle multiple identifiers
scripts: kernel-doc: handle nested struct function arguments
scripts: kernel-doc: print the declaration name on warnings
scripts: kernel-doc: get rid of $nested parameter
scripts: kernel-doc: parse next structs/unions
scripts: kernel-doc: replace tabs by spaces
scripts: kernel-doc: change default to ReST format
scripts: kernel-doc: improve argument handling
scripts: kernel-doc: get rid of unused output formats
docs: get rid of kernel-doc-nano-HOWTO.txt
docs: kernel-doc.rst: add documentation about man pages
docs: kernel-doc.rst: improve typedef documentation
docs: kernel-doc.rst: improve structs chapter
docs: kernel-doc.rst: improve function documentation section
docs: kernel-doc.rst: improve private members description
docs: kernel-doc.rst: better describe kernel-doc arguments
docs: fix process/submit-checklist.rst Sphinx warning
docs: ftrace-uses.rst fix varios code-block directives
...
Diffstat (limited to 'Documentation')
112 files changed, 1114 insertions, 714 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 3bec49c33bbb..7f3a0728ccf2 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -228,8 +228,6 @@ isdn/ - directory with info on the Linux ISDN support, and supported cards. kbuild/ - directory with info about the kernel build process. -kernel-doc-nano-HOWTO.txt - - outdated info about kernel-doc documentation. kdump/ - directory with mini HowTo on getting the crash dump code to work. doc-guide/ @@ -346,8 +344,6 @@ prctl/ - directory with info on the priveledge control subsystem preempt-locking.txt - info on locking under a preemptive kernel. -printk-formats.txt - - how to get printk format specifiers right process/ - how to work with the mainline kernel development process. pps/ diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 6571fbfdb2a1..dfb7c35b5826 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -2538,6 +2538,9 @@ This is useful when you use a panic=... timeout and need the box quickly up again. + These settings can be accessed at runtime via + the nmi_watchdog and hardlockup_panic sysctls. + netpoll.carrier_timeout= [NET] Specifies amount of time (in seconds) that netpoll should wait for a carrier. By default netpoll diff --git a/Documentation/admin-guide/mono.rst b/Documentation/admin-guide/mono.rst index cdddc099af64..59e6d59f0ed9 100644 --- a/Documentation/admin-guide/mono.rst +++ b/Documentation/admin-guide/mono.rst @@ -9,14 +9,14 @@ This will allow you to execute Mono-based .NET binaries just like any other program after you have done the following: 1) You MUST FIRST install the Mono CLR support, either by downloading - a binary package, a source tarball or by installing from CVS. Binary + a binary package, a source tarball or by installing from Git. Binary packages for several distributions can be found at: - http://go-mono.com/download.html + http://www.mono-project.com/download/ Instructions for compiling Mono can be found at: - http://www.go-mono.com/compiling.html + http://www.mono-project.com/docs/compiling-mono/linux/ Once the Mono CLR support has been installed, just check that ``/usr/bin/mono`` (which could be located elsewhere, for example diff --git a/Documentation/conf.py b/Documentation/conf.py index 63857d33778c..62ac5a9f3a9f 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -88,7 +88,6 @@ finally: if makefile_version and makefile_patchlevel: version = release = makefile_version + '.' + makefile_patchlevel else: - sys.stderr.write('Warning: Could not extract kernel version\n') version = release = "unknown version" # The language for content autogenerated by Sphinx. Refer to documentation diff --git a/Documentation/core-api/genericirq.rst b/Documentation/core-api/genericirq.rst index 0054bd48be84..4da67b65cecf 100644 --- a/Documentation/core-api/genericirq.rst +++ b/Documentation/core-api/genericirq.rst @@ -225,9 +225,9 @@ interrupts. The following control flow is implemented (simplified excerpt):: - :c:func:`desc->irq_data.chip->irq_mask_ack`; + desc->irq_data.chip->irq_mask_ack(); handle_irq_event(desc->action); - :c:func:`desc->irq_data.chip->irq_unmask`; + desc->irq_data.chip->irq_unmask(); Default Fast EOI IRQ flow handler @@ -239,7 +239,7 @@ which only need an EOI at the end of the handler. The following control flow is implemented (simplified excerpt):: handle_irq_event(desc->action); - :c:func:`desc->irq_data.chip->irq_eoi`; + desc->irq_data.chip->irq_eoi(); Default Edge IRQ flow handler @@ -251,15 +251,15 @@ interrupts. The following control flow is implemented (simplified excerpt):: if (desc->status & running) { - :c:func:`desc->irq_data.chip->irq_mask_ack`; + desc->irq_data.chip->irq_mask_ack(); desc->status |= pending | masked; return; } - :c:func:`desc->irq_data.chip->irq_ack`; + desc->irq_data.chip->irq_ack(); desc->status |= running; do { if (desc->status & masked) - :c:func:`desc->irq_data.chip->irq_unmask`; + desc->irq_data.chip->irq_unmask(); desc->status &= ~pending; handle_irq_event(desc->action); } while (status & pending); @@ -293,10 +293,10 @@ simplified version without locking. The following control flow is implemented (simplified excerpt):: if (desc->irq_data.chip->irq_ack) - :c:func:`desc->irq_data.chip->irq_ack`; + desc->irq_data.chip->irq_ack(); handle_irq_event(desc->action); if (desc->irq_data.chip->irq_eoi) - :c:func:`desc->irq_data.chip->irq_eoi`; + desc->irq_data.chip->irq_eoi(); EOI Edge IRQ flow handler diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index d5bbe035316d..d55ee6b006ed 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -14,6 +14,7 @@ Core utilities kernel-api assoc_array atomic_ops + refcount-vs-atomic cpu_hotplug local_ops workqueue @@ -21,6 +22,7 @@ Core utilities flexible-arrays librs genalloc + printk-formats Interfaces for kernel debugging =============================== diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst index 2d9da6c40a4d..e7fadf02c511 100644 --- a/Documentation/core-api/kernel-api.rst +++ b/Documentation/core-api/kernel-api.rst @@ -139,6 +139,21 @@ Division Functions .. kernel-doc:: lib/gcd.c :export: +Sorting +------- + +.. kernel-doc:: lib/sort.c + :export: + +.. kernel-doc:: lib/list_sort.c + :export: + +UUID/GUID +--------- + +.. kernel-doc:: lib/uuid.c + :export: + Memory Management in Linux ========================== diff --git a/Documentation/printk-formats.txt b/Documentation/core-api/printk-formats.rst index 361789df51ec..258b46435320 100644 --- a/Documentation/printk-formats.txt +++ b/Documentation/core-api/printk-formats.rst @@ -26,27 +26,45 @@ Integer types s64 %lld or %llx u64 %llu or %llx -If <type> is dependent on a config option for its size (e.g., ``sector_t``, -``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``), -use a format specifier of its largest possible type and explicitly cast to it. + +If <type> is dependent on a config option for its size (e.g., sector_t, +blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a +format specifier of its largest possible type and explicitly cast to it. Example:: printk("test: sector number/total blocks: %llu/%llu\n", (unsigned long long)sector, (unsigned long long)blockcount); -Reminder: ``sizeof()`` result is of type ``size_t``. +Reminder: sizeof() returns type size_t. -The kernel's printf does not support ``%n``. For obvious reasons, floating -point formats (``%e, %f, %g, %a``) are also not recognized. Use of any +The kernel's printf does not support %n. Floating point formats (%e, %f, +%g, %a) are also not recognized, for obvious reasons. Use of any unsupported specifier or length qualifier results in a WARN and early -return from vsnprintf. +return from vsnprintf(). + +Pointer types +============= + +A raw pointer value may be printed with %p which will hash the address +before printing. The kernel also supports extended specifiers for printing +pointers of different types. + +Plain Pointers +-------------- + +:: -Raw pointer value SHOULD be printed with %p. The kernel supports -the following extended format specifiers for pointer types: + %p abcdef12 or 00000000abcdef12 + +Pointers printed without a specifier extension (i.e unadorned %p) are +hashed to prevent leaking information about the kernel memory layout. This +has the added benefit of providing a unique identifier. On 64-bit machines +the first 32 bits are zeroed. If you *really* want the address see %px +below. Symbols/Function Pointers -========================= +------------------------- :: @@ -58,6 +76,7 @@ Symbols/Function Pointers %ps versatile_init %pB prev_fn_of_versatile_init+0x88/0x88 + The ``F`` and ``f`` specifiers are for printing function pointers, for example, f->func, &gettimeofday. They have the same result as ``S`` and ``s`` specifiers. But they do an extra conversion on @@ -66,14 +85,14 @@ are actually function descriptors. The ``S`` and ``s`` specifiers can be used for printing symbols from direct addresses, for example, __builtin_return_address(0), -(void *)regs->ip. They result in the symbol name with (``S``) or -without (``s``) offsets. If KALLSYMS are disabled then the symbol +(void *)regs->ip. They result in the symbol name with (S) or +without (s) offsets. If KALLSYMS are disabled then the symbol address is printed instead. The ``B`` specifier results in the symbol name with offsets and should be used when printing stack backtraces. The specifier takes into consideration the effect of compiler optimisations which may occur -when tail-call``s are used and marked with the noreturn GCC attribute. +when tail-calls are used and marked with the noreturn GCC attribute. Examples:: @@ -85,20 +104,33 @@ Examples:: printk("Faulted at %pS\n", (void *)regs->ip); printk(" %s%pB\n", (reliable ? "" : "? "), (void *)*stack); - Kernel Pointers -=============== +--------------- :: - %pK 0x01234567 or 0x0123456789abcdef + %pK 01234567 or 0123456789abcdef For printing kernel pointers which should be hidden from unprivileged -users. The behaviour of ``%pK`` depends on the ``kptr_restrict sysctl`` - see +users. The behaviour of %pK depends on the kptr_restrict sysctl - see Documentation/sysctl/kernel.txt for more details. +Unmodified Addresses +-------------------- + +:: + + %px 01234567 or 0123456789abcdef + +For printing pointers when you *really* want to print the address. Please +consider whether or not you are leaking sensitive information about the +kernel memory layout before printing pointers with %px. %px is functionally +equivalent to %lx (or %lu). %px is preferred because it is more uniquely +grep'able. If in the future we need to modify the way the kernel handles +printing pointers we will be better equipped to find the call sites. + Struct Resources -================ +---------------- :: @@ -108,32 +140,37 @@ Struct Resources [mem 0x0000000060000000-0x000000006fffffff pref] For printing struct resources. The ``R`` and ``r`` specifiers result in a -printed resource with (``R``) or without (``r``) a decoded flags member. +printed resource with (R) or without (r) a decoded flags member. + Passed by reference. -Physical addresses types ``phys_addr_t`` -======================================== +Physical address types phys_addr_t +---------------------------------- :: %pa[p] 0x01234567 or 0x0123456789abcdef -For printing a ``phys_addr_t`` type (and its derivatives, such as -``resource_size_t``) which can vary based on build options, regardless of -the width of the CPU data path. Passed by reference. +For printing a phys_addr_t type (and its derivatives, such as +resource_size_t) which can vary based on build options, regardless of the +width of the CPU data path. + +Passed by reference. -DMA addresses types ``dma_addr_t`` -================================== +DMA address types dma_addr_t +---------------------------- :: %pad 0x01234567 or 0x0123456789abcdef -For printing a ``dma_addr_t`` type which can vary based on build options, -regardless of the width of the CPU data path. Passed by reference. +For printing a dma_addr_t type which can vary based on build options, +regardless of the width of the CPU data path. + +Passed by reference. Raw buffer as an escaped string -=============================== +------------------------------- :: @@ -143,8 +180,8 @@ For printing raw buffer as an escaped string. For the following buffer:: 1b 62 20 5c 43 07 22 90 0d 5d -few examples show how the conversion would be done (the result string -without surrounding quotes):: +A few examples show how the conversion would be done (excluding surrounding +quotes):: %*pE "\eb \C\a"\220\r]" %*pEhp "\x1bb \C\x07"\x90\x0d]" @@ -154,23 +191,23 @@ The conversion rules are applied according to an optional combination of flags (see :c:func:`string_escape_mem` kernel documentation for the details): - - ``a`` - ESCAPE_ANY - - ``c`` - ESCAPE_SPECIAL - - ``h`` - ESCAPE_HEX - - ``n`` - ESCAPE_NULL - - ``o`` - ESCAPE_OCTAL - - ``p`` - ESCAPE_NP - - ``s`` - ESCAPE_SPACE + - a - ESCAPE_ANY + - c - ESCAPE_SPECIAL + - h - ESCAPE_HEX + - n - ESCAPE_NULL + - o - ESCAPE_OCTAL + - p - ESCAPE_NP + - s - ESCAPE_SPACE By default ESCAPE_ANY_NP is used. ESCAPE_ANY_NP is the sane choice for many cases, in particularly for printing SSIDs. -If field width is omitted the 1 byte only will be escaped. +If field width is omitted then 1 byte only will be escaped. Raw buffer as a hex string -========================== +-------------------------- :: @@ -179,12 +216,12 @@ Raw buffer as a hex string %*phD 00-01-02- ... -3f %*phN 000102 ... 3f -For printing a small buffers (up to 64 bytes long) as a hex string with -certain separator. For the larger buffers consider to use +For printing small buffers (up to 64 bytes long) as a hex string with a +certain separator. For larger buffers consider using :c:func:`print_hex_dump`. MAC/FDDI addresses -================== +------------------ :: @@ -195,11 +232,11 @@ MAC/FDDI addresses %pmR 050403020100 For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m`` -specifiers result in a printed address with (``M``) or without (``m``) byte -separators. The default byte separator is the colon (``:``). +specifiers result in a printed address with (M) or without (m) byte +separators. The default byte separator is the colon (:). Where FDDI addresses are concerned the ``F`` specifier can be used after -the ``M`` specifier to use dash (``-``) separators instead of the default +the ``M`` specifier to use dash (-) separators instead of the default separator. For Bluetooth addresses the ``R`` specifier shall be used after the ``M`` @@ -209,7 +246,7 @@ of Bluetooth addresses which are in the little endian order. Passed by reference. IPv4 addresses -============== +-------------- :: @@ -218,8 +255,8 @@ IPv4 addresses %p[Ii]4[hnbl] For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4`` -specifiers result in a printed address with (``i4``) or without (``I4``) -leading zeros. +specifiers result in a printed address with (i4) or without (I4) leading +zeros. The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify host, network, big or little endian order addresses respectively. Where @@ -228,7 +265,7 @@ no specifier is provided the default network/big endian order is used. Passed by reference. IPv6 addresses -============== +-------------- :: @@ -237,7 +274,7 @@ IPv6 addresses %pI6c 1:2:3:4:5:6:7:8 For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6`` -specifiers result in a printed address with (``I6``) or without (``i6``) +specifiers result in a printed address with (I6) or without (i6) colon-separators. Leading zeros are always used. The additional ``c`` specifier can be used with the ``I`` specifier to @@ -247,7 +284,7 @@ http://tools.ietf.org/html/rfc5952 Passed by reference. IPv4/IPv6 addresses (generic, with port, flowinfo, scope) -========================================================= +--------------------------------------------------------- :: @@ -257,8 +294,8 @@ IPv4/IPv6 addresses (generic, with port, flowinfo, scope) %pISpc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345 %p[Ii]S[pfschnbl] -For printing an IP address without the need to distinguish whether it``s -of type AF_INET or AF_INET6, a pointer to a valid ``struct sockaddr``, +For printing an IP address without the need to distinguish whether it's of +type AF_INET or AF_INET6. A pointer to a valid struct sockaddr, specified through ``IS`` or ``iS``, can be passed to this format specifier. The additional ``p``, ``f``, and ``s`` specifiers are used to specify port @@ -284,7 +321,7 @@ Further examples:: %pISpfc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345/123456789 UUID/GUID addresses -=================== +------------------- :: @@ -293,33 +330,33 @@ UUID/GUID addresses %pUl 03020100-0504-0706-0809-0a0b0c0e0e0f %pUL 03020100-0504-0706-0809-0A0B0C0E0E0F -For printing 16-byte UUID/GUIDs addresses. The additional 'l', 'L', -'b' and 'B' specifiers are used to specify a little endian order in -lower ('l') or upper case ('L') hex characters - and big endian order -in lower ('b') or upper case ('B') hex characters. +For printing 16-byte UUID/GUIDs addresses. The additional ``l``, ``L``, +``b`` and ``B`` specifiers are used to specify a little endian order in +lower (l) or upper case (L) hex notation - and big endian order in lower (b) +or upper case (B) hex notation. Where no additional specifiers are used the default big endian -order with lower case hex characters will be printed. +order with lower case hex notation will be printed. Passed by reference. dentry names -============ +------------ :: %pd{,2,3,4} %pD{,2,3,4} -For printing dentry name; if we race with :c:func:`d_move`, the name might be -a mix of old and new ones, but it won't oops. ``%pd`` dentry is a safer -equivalent of ``%s`` ``dentry->d_name.name`` we used to use, ``%pd<n>`` prints -``n`` last components. ``%pD`` does the same thing for struct file. +For printing dentry name; if we race with :c:func:`d_move`, the name might +be a mix of old and new ones, but it won't oops. %pd dentry is a safer +equivalent of %s dentry->d_name.name we used to use, %pd<n> prints ``n`` +last components. %pD does the same thing for struct file. Passed by reference. block_device names -================== +------------------ :: @@ -328,7 +365,7 @@ block_device names For printing name of block_device pointers. struct va_format -================ +---------------- :: @@ -350,31 +387,27 @@ correctness of the format string and va_list arguments. Passed by reference. kobjects -======== +-------- :: - %pO + %pOF[fnpPcCF] - Base specifier for kobject based structs. Must be followed with - character for specific type of kobject as listed below: - Device tree nodes: +For printing kobject based structs (device nodes). Default behaviour is +equivalent to %pOFf. - %pOF[fnpPcCF] + - f - device node full_name + - n - device node name + - p - device node phandle + - P - device node path spec (name + @unit) + - F - device node flags + - c - major compatible string + - C - full compatible string - For printing device tree nodes. The optional arguments are: - f device node full_name - n device node name - p device node phandle - P device node path spec (name + @unit) - F device node flags - c major compatible string - C full compatible string - Without any arguments prints full_name (same as %pOFf) - The separator when using multiple arguments is ':' +The separator when using multiple arguments is ':' - Examples: +Examples:: %pOF /foo/bar@0 - Node full name %pOFf /foo/bar@0 - Same as above @@ -387,11 +420,10 @@ kobjects P - Populated B - Populated bus - Passed by reference. - +Passed by reference. struct clk -========== +---------- :: @@ -399,14 +431,14 @@ struct clk %pCn pll1 %pCr 1560000000 -For printing struct clk structures. ``%pC`` and ``%pCn`` print the name +For printing struct clk structures. %pC and %pCn print the name (Common Clock Framework) or address (legacy clock framework) of the -structure; ``%pCr`` prints the current clock rate. +structure; %pCr prints the current clock rate. Passed by reference. bitmap and its derivatives such as cpumask and nodemask -======================================================= +------------------------------------------------------- :: @@ -414,13 +446,13 @@ bitmap and its derivatives such as cpumask and nodemask %*pbl 0,3-6,8-10 For printing bitmap and its derivatives such as cpumask and nodemask, -``%*pb`` output the bitmap with field width as the number of bits and ``%*pbl`` +%*pb outputs the bitmap with field width as the number of bits and %*pbl output the bitmap as range list with field width as the number of bits. Passed by reference. Flags bitfields such as page flags, gfp_flags -============================================= +--------------------------------------------- :: @@ -434,14 +466,14 @@ character. Currently supported are [p]age flags, [v]ma_flags (both expect ``unsigned long *``) and [g]fp_flags (expects ``gfp_t *``). The flag names and print order depends on the particular type. -Note that this format should not be used directly in :c:func:`TP_printk()` part -of a tracepoint. Instead, use the ``show_*_flags()`` functions from -<trace/events/mmflags.h>. +Note that this format should not be used directly in the +:c:func:`TP_printk()` part of a tracepoint. Instead, use the show_*_flags() +functions from <trace/events/mmflags.h>. Passed by reference. Network device features -======================= +----------------------- :: @@ -451,8 +483,10 @@ For printing netdev_features_t. Passed by reference. -If you add other ``%p`` extensions, please extend lib/test_printf.c with -one or more test cases, if at all feasible. +Thanks +====== +If you add other %p extensions, please extend <lib/test_printf.c> with +one or more test cases, if at all feasible. Thank you for your cooperation and attention. diff --git a/Documentation/core-api/refcount-vs-atomic.rst b/Documentation/core-api/refcount-vs-atomic.rst new file mode 100644 index 000000000000..83351c258cdb --- /dev/null +++ b/Documentation/core-api/refcount-vs-atomic.rst @@ -0,0 +1,150 @@ +=================================== +refcount_t API compared to atomic_t +=================================== + +.. contents:: :local: + +Introduction +============ + +The goal of refcount_t API is to provide a minimal API for implementing +an object's reference counters. While a generic architecture-independent +implementation from lib/refcount.c uses atomic operations underneath, +there are a number of differences between some of the ``refcount_*()`` and +``atomic_*()`` functions with regards to the memory ordering guarantees. +This document outlines the differences and provides respective examples +in order to help maintainers validate their code against the change in +these memory ordering guarantees. + +The terms used through this document try to follow the formal LKMM defined in +github.com/aparri/memory-model/blob/master/Documentation/explanation.txt + +memory-barriers.txt and atomic_t.txt provide more background to the +memory ordering in general and for atomic operations specifically. + +Relevant types of memory ordering +================================= + +.. note:: The following section only covers some of the memory + ordering types that are relevant for the atomics and reference + counters and used through this document. For a much broader picture + please consult memory-barriers.txt document. + +In the absence of any memory ordering guarantees (i.e. fully unordered) +atomics & refcounters only provide atomicity and +program order (po) relation (on the same CPU). It guarantees that +each ``atomic_*()`` and ``refcount_*()`` operation is atomic and instructions +are executed in program order on a single CPU. +This is implemented using :c:func:`READ_ONCE`/:c:func:`WRITE_ONCE` and +compare-and-swap primitives. + +A strong (full) memory ordering guarantees that all prior loads and +stores (all po-earlier instructions) on the same CPU are completed +before any po-later instruction is executed on the same CPU. +It also guarantees that all po-earlier stores on the same CPU +and all propagated stores from other CPUs must propagate to all +other CPUs before any po-later instruction is executed on the original +CPU (A-cumulative property). This is implemented using :c:func:`smp_mb`. + +A RELEASE memory ordering guarantees that all prior loads and +stores (all po-earlier instructions) on the same CPU are completed +before the operation. It also guarantees that all po-earlier +stores on the same CPU and all propagated stores from other CPUs +must propagate to all other CPUs before the release operation +(A-cumulative property). This is implemented using +:c:func:`smp_store_release`. + +A control dependency (on success) for refcounters guarantees that +if a reference for an object was successfully obtained (reference +counter increment or addition happened, function returned true), +then further stores are ordered against this operation. +Control dependency on stores are not implemented using any explicit +barriers, but rely on CPU not to speculate on stores. This is only +a single CPU relation and provides no guarantees for other CPUs. + + +Comparison of functions +======================= + +case 1) - non-"Read/Modify/Write" (RMW) ops +------------------------------------------- + +Function changes: + + * :c:func:`atomic_set` --> :c:func:`refcount_set` + * :c:func:`atomic_read` --> :c:func:`refcount_read` + +Memory ordering guarantee changes: + + * none (both fully unordered) + + +case 2) - increment-based ops that return no value +-------------------------------------------------- + +Function changes: + + * :c:func:`atomic_inc` --> :c:func:`refcount_inc` + * :c:func:`atomic_add` --> :c:func:`refcount_add` + +Memory ordering guarantee changes: + + * none (both fully unordered) + +case 3) - decrement-based RMW ops that return no value +------------------------------------------------------ + +Function changes: + + * :c:func:`atomic_dec` --> :c:func:`refcount_dec` + +Memory ordering guarantee changes: + + * fully unordered --> RELEASE ordering + + +case 4) - increment-based RMW ops that return a value +----------------------------------------------------- + +Function changes: + + * :c:func:`atomic_inc_not_zero` --> :c:func:`refcount_inc_not_zero` + * no atomic counterpart --> :c:func:`refcount_add_not_zero` + +Memory ordering guarantees changes: + + * fully ordered --> control dependency on success for stores + +.. note:: We really assume here that necessary ordering is provided as a + result of obtaining pointer to the object! + + +case 5) - decrement-based RMW ops that return a value +----------------------------------------------------- + +Function changes: + + * :c:func:`atomic_dec_and_test` --> :c:func:`refcount_dec_and_test` + * :c:func:`atomic_sub_and_test` --> :c:func:`refcount_sub_and_test` + * no atomic counterpart --> :c:func:`refcount_dec_if_one` + * ``atomic_add_unless(&var, -1, 1)`` --> ``refcount_dec_not_one(&var)`` + +Memory ordering guarantees changes: + + * fully ordered --> RELEASE ordering + control dependency + +.. note:: :c:func:`atomic_add_unless` only provides full order on success. + + +case 6) - lock-based RMW +------------------------ + +Function changes: + + * :c:func:`atomic_dec_and_lock` --> :c:func:`refcount_dec_and_lock` + * :c:func:`atomic_dec_and_mutex_lock` --> :c:func:`refcount_dec_and_mutex_lock` + +Memory ordering guarantees changes: + + * fully ordered --> RELEASE ordering + control dependency + hold + :c:func:`spin_lock` on success diff --git a/Documentation/devicetree/bindings/arm/ccn.txt b/Documentation/devicetree/bindings/arm/ccn.txt index 29801456c9ee..43b5a71a5a9d 100644 --- a/Documentation/devicetree/bindings/arm/ccn.txt +++ b/Documentation/devicetree/bindings/arm/ccn.txt @@ -15,7 +15,7 @@ Required properties: Example: - ccn@0x2000000000 { + ccn@2000000000 { compatible = "arm,ccn-504"; reg = <0x20 0x00000000 0 0x1000000>; interrupts = <0 181 4>; diff --git a/Documentation/devicetree/bindings/arm/omap/crossbar.txt b/Documentation/devicetree/bindings/arm/omap/crossbar.txt index bb5727ae004a..ecb360ed0e33 100644 --- a/Documentation/devicetree/bindings/arm/omap/crossbar.txt +++ b/Documentation/devicetree/bindings/arm/omap/crossbar.txt @@ -49,7 +49,7 @@ An interrupt consumer on an SoC using crossbar will use: interrupts = <GIC_SPI request_number interrupt_level> Example: - device_x@0x4a023000 { + device_x@4a023000 { /* Crossbar 8 used */ interrupts = <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>; ... diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-mc.txt b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-mc.txt index 866d93421eba..f9632bacbd04 100644 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-mc.txt +++ b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-mc.txt @@ -8,7 +8,7 @@ Required properties: - interrupts : Should contain MC General interrupt. Example: - memory-controller@0x7000f000 { + memory-controller@7000f000 { compatible = "nvidia,tegra20-mc"; reg = <0x7000f000 0x024 0x7000f03c 0x3c4>; diff --git a/Documentation/devicetree/bindings/clock/axi-clkgen.txt b/Documentation/devicetree/bindings/clock/axi-clkgen.txt index fb40da303d25..aca94fe9416f 100644 --- a/Documentation/devicetree/bindings/clock/axi-clkgen.txt +++ b/Documentation/devicetree/bindings/clock/axi-clkgen.txt @@ -17,7 +17,7 @@ Optional properties: - clock-output-names : From common clock binding. Example: - clock@0xff000000 { + clock@ff000000 { compatible = "adi,axi-clkgen"; #clock-cells = <0>; reg = <0xff000000 0x1000>; diff --git a/Documentation/devicetree/bindings/clock/brcm,bcm2835-aux-clock.txt b/Documentation/devicetree/bindings/clock/brcm,bcm2835-aux-clock.txt index 7a837d2182ac..4acfc8f641b6 100644 --- a/Documentation/devicetree/bindings/clock/brcm,bcm2835-aux-clock.txt +++ b/Documentation/devicetree/bindings/clock/brcm,bcm2835-aux-clock.txt @@ -23,7 +23,7 @@ Example: clocks = <&clk_osc>; }; - aux: aux@0x7e215004 { + aux: aux@7e215004 { compatible = "brcm,bcm2835-aux"; #clock-cells = <1>; reg = <0x7e215000 0x8>; diff --git a/Documentation/devicetree/bindings/clock/exynos4-clock.txt b/Documentation/devicetree/bindings/clock/exynos4-clock.txt index bc61c952cb0b..17bb11365354 100644 --- a/Documentation/devicetree/bindings/clock/exynos4-clock.txt +++ b/Documentation/devicetree/bindings/clock/exynos4-clock.txt @@ -24,7 +24,7 @@ tree sources. Example 1: An example of a clock controller node is listed below. - clock: clock-controller@0x10030000 { + clock: clock-controller@10030000 { compatible = "samsung,exynos4210-clock"; reg = <0x10030000 0x20000>; #clock-cells = <1>; diff --git a/Documentation/devicetree/bindings/clock/exynos5250-clock.txt b/Documentation/devicetree/bindings/clock/exynos5250-clock.txt index 536eacd1063f..aff266a12eeb 100644 --- a/Documentation/devicetree/bindings/clock/exynos5250-clock.txt +++ b/Documentation/devicetree/bindings/clock/exynos5250-clock.txt @@ -22,7 +22,7 @@ tree sources. Example 1: An example of a clock controller node is listed below. - clock: clock-controller@0x10010000 { + clock: clock-controller@10010000 { compatible = "samsung,exynos5250-clock"; reg = <0x10010000 0x30000>; #clock-cells = <1>; diff --git a/Documentation/devicetree/bindings/clock/exynos5410-clock.txt b/Documentation/devicetree/bindings/clock/exynos5410-clock.txt index 4527de3ea205..c68b0d29b3d0 100644 --- a/Documentation/devicetree/bindings/clock/exynos5410-clock.txt +++ b/Documentation/devicetree/bindings/clock/exynos5410-clock.txt @@ -30,7 +30,7 @@ Example 1: An example of a clock controller node is listed below. #clock-cells = <0>; }; - clock: clock-controller@0x10010000 { + clock: clock-controller@10010000 { compatible = "samsung,exynos5410-clock"; reg = <0x10010000 0x30000>; #clock-cells = <1>; diff --git a/Documentation/devicetree/bindings/clock/exynos5420-clock.txt b/Documentation/devicetree/bindings/clock/exynos5420-clock.txt index d54f42cf0440..717a7b1531c7 100644 --- a/Documentation/devicetree/bindings/clock/exynos5420-clock.txt +++ b/Documentation/devicetree/bindings/clock/exynos5420-clock.txt @@ -23,7 +23,7 @@ tree sources. Example 1: An example of a clock controller node is listed below. - clock: clock-controller@0x10010000 { + clock: clock-controller@10010000 { compatible = "samsung,exynos5420-clock"; reg = <0x10010000 0x30000>; #clock-cells = <1>; diff --git a/Documentation/devicetree/bindings/clock/exynos5440-clock.txt b/Documentation/devicetree/bindings/clock/exynos5440-clock.txt index 5f7005f73058..c7d227c31e95 100644 --- a/Documentation/devicetree/bindings/clock/exynos5440-clock.txt +++ b/Documentation/devicetree/bindings/clock/exynos5440-clock.txt @@ -21,7 +21,7 @@ tree sources. Example: An example of a clock controller node is listed below. - clock: clock-controller@0x10010000 { + clock: clock-controller@10010000 { compatible = "samsung,exynos5440-clock"; reg = <0x160000 0x10000>; #clock-cells = <1>; diff --git a/Documentation/devicetree/bindings/clock/ti-keystone-pllctrl.txt b/Documentation/devicetree/bindings/clock/ti-keystone-pllctrl.txt index 3e6a81e99804..c35cb6c4af4d 100644 --- a/Documentation/devicetree/bindings/clock/ti-keystone-pllctrl.txt +++ b/Documentation/devicetree/bindings/clock/ti-keystone-pllctrl.txt @@ -14,7 +14,7 @@ Required properties: Example: -pllctrl: pll-controller@0x02310000 { +pllctrl: pll-controller@02310000 { compatible = "ti,keystone-pllctrl", "syscon"; reg = <0x02310000 0x200>; }; diff --git a/Documentation/devicetree/bindings/clock/zx296702-clk.txt b/Documentation/devicetree/bindings/clock/zx296702-clk.txt index e85ecb510d56..5c91c9e4f1be 100644 --- a/Documentation/devicetree/bindings/clock/zx296702-clk.txt +++ b/Documentation/devicetree/bindings/clock/zx296702-clk.txt @@ -20,13 +20,13 @@ ID in its "clocks" phandle cell. See include/dt-bindings/clock/zx296702-clock.h for the full list of zx296702 clock IDs. -topclk: topcrm@0x09800000 { +topclk: topcrm@09800000 { compatible = "zte,zx296702-topcrm-clk"; reg = <0x09800000 0x1000>; #clock-cells = <1>; }; -uart0: serial@0x09405000 { +uart0: serial@09405000 { compatible = "zte,zx296702-uart"; reg = <0x09405000 0x1000>; interrupts = <GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>; diff --git a/Documentation/devicetree/bindings/crypto/fsl-sec4.txt b/Documentation/devicetree/bindings/crypto/fsl-sec4.txt index 7aef0eae58d4..76aec8a3724d 100644 --- a/Documentation/devicetree/bindings/crypto/fsl-sec4.txt +++ b/Documentation/devicetree/bindings/crypto/fsl-sec4.txt @@ -456,7 +456,7 @@ System ON/OFF key driver Definition: this is phandle to the register map node. EXAMPLE: - snvs-pwrkey@0x020cc000 { + snvs-pwrkey@020cc000 { compatible = "fsl,sec-v4.0-pwrkey"; regmap = <&snvs>; interrupts = <0 4 0x4> @@ -545,7 +545,7 @@ FULL EXAMPLE interrupts = <93 2>; }; - snvs-pwrkey@0x020cc000 { + snvs-pwrkey@020cc000 { compatible = "fsl,sec-v4.0-pwrkey"; regmap = <&sec_mon>; interrupts = <0 4 0x4>; diff --git a/Documentation/devicetree/bindings/devfreq/event/rockchip-dfi.txt b/Documentation/devicetree/bindings/devfreq/event/rockchip-dfi.txt index 001dd63979a9..148191b0fc15 100644 --- a/Documentation/devicetree/bindings/devfreq/event/rockchip-dfi.txt +++ b/Documentation/devicetree/bindings/devfreq/event/rockchip-dfi.txt @@ -9,7 +9,7 @@ Required properties: - clock-names : the name of clock used by the DFI, must be "pclk_ddr_mon"; Example: - dfi: dfi@0xff630000 { + dfi: dfi@ff630000 { compatible = "rockchip,rk3399-dfi"; reg = <0x00 0xff630000 0x00 0x4000>; rockchip,pmu = <&pmugrf>; diff --git a/Documentation/devicetree/bindings/display/atmel,lcdc.txt b/Documentation/devicetree/bindings/display/atmel,lcdc.txt index 1a21202778ee..acb5a0132127 100644 --- a/Documentation/devicetree/bindings/display/atmel,lcdc.txt +++ b/Documentation/devicetree/bindings/display/atmel,lcdc.txt @@ -27,7 +27,7 @@ Optional properties: Example: - fb0: fb@0x00500000 { + fb0: fb@00500000 { compatible = "atmel,at91sam9g45-lcdc"; reg = <0x00500000 0x1000>; interrupts = <23 3 0>; @@ -41,7 +41,7 @@ Example: Example for fixed framebuffer memory: - fb0: fb@0x00500000 { + fb0: fb@00500000 { compatible = "atmel,at91sam9263-lcdc"; reg = <0x00700000 0x1000 0x70000000 0x200000>; [...] diff --git a/Documentation/devicetree/bindings/dma/qcom_hidma_mgmt.txt b/Documentation/devicetree/bindings/dma/qcom_hidma_mgmt.txt index 55492c264d17..b3408cc57be6 100644 --- a/Documentation/devicetree/bindings/dma/qcom_hidma_mgmt.txt +++ b/Documentation/devicetree/bindings/dma/qcom_hidma_mgmt.txt @@ -73,7 +73,7 @@ Hypervisor OS configuration: max-read-transactions = <31>; channel-reset-timeout-cycles = <0x500>; - hidma_24: dma-controller@0x5c050000 { + hidma_24: dma-controller@5c050000 { compatible = "qcom,hidma-1.0"; reg = <0 0x5c050000 0x0 0x1000>, <0 0x5c0b0000 0x0 0x1000>; @@ -85,7 +85,7 @@ Hypervisor OS configuration: Guest OS configuration: - hidma_24: dma-controller@0x5c050000 { + hidma_24: dma-controller@5c050000 { compatible = "qcom,hidma-1.0"; reg = <0 0x5c050000 0x0 0x1000>, <0 0x5c0b0000 0x0 0x1000>; diff --git a/Documentation/devicetree/bindings/dma/zxdma.txt b/Documentation/devicetree/bindings/dma/zxdma.txt index abec59f35fde..0ab80f69e566 100644 --- a/Documentation/devicetree/bindings/dma/zxdma.txt +++ b/Documentation/devicetree/bindings/dma/zxdma.txt @@ -13,7 +13,7 @@ Required properties: Example: Controller: - dma: dma-controller@0x09c00000{ + dma: dma-controller@09c00000{ compatible = "zte,zx296702-dma"; reg = <0x09c00000 0x1000>; clocks = <&topclk ZX296702_DMA_ACLK>; diff --git a/Documentation/devicetree/bindings/eeprom/at25.txt b/Documentation/devicetree/bindings/eeprom/at25.txt index 1d3447165c37..e823d90b802f 100644 --- a/Documentation/devicetree/bindings/eeprom/at25.txt +++ b/Documentation/devicetree/bindings/eeprom/at25.txt @@ -1,7 +1,12 @@ EEPROMs (SPI) compatible with Atmel at25. Required properties: -- compatible : "atmel,at25". +- compatible : Should be "<vendor>,<type>", and generic value "atmel,at25". + Example "<vendor>,<type>" values: + "microchip,25lc040" + "st,m95m02" + "st,m95256" + - reg : chip select number - spi-max-frequency : max spi frequency to use - pagesize : size of the eeprom page @@ -13,7 +18,7 @@ Optional properties: - spi-cpol : SPI inverse clock polarity, as per spi-bus bindings. - read-only : this parameter-less property disables writes to the eeprom -Obsolete legacy properties are can be used in place of "size", "pagesize", +Obsolete legacy properties can be used in place of "size", "pagesize", "address-width", and "read-only": - at25,byte-len : total eeprom size in bytes - at25,addr-mode : addr-mode flags, as defined in include/linux/spi/eeprom.h @@ -22,8 +27,8 @@ Obsolete legacy properties are can be used in place of "size", "pagesize", Additional compatible properties are also allowed. Example: - at25@0 { - compatible = "atmel,at25", "st,m95256"; + eeprom@0 { + compatible = "st,m95256", "atmel,at25"; reg = <0> spi-max-frequency = <5000000>; spi-cpha; diff --git a/Documentation/devicetree/bindings/gpio/gpio-altera.txt b/Documentation/devicetree/bindings/gpio/gpio-altera.txt index 826a7208ca93..146e554b3c67 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-altera.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-altera.txt @@ -30,7 +30,7 @@ Optional properties: Example: -gpio_altr: gpio@0xff200000 { +gpio_altr: gpio@ff200000 { compatible = "altr,pio-1.0"; reg = <0xff200000 0x10>; interrupts = <0 45 4>; diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt index 7f57271df2bc..0d0158728f89 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt @@ -27,7 +27,7 @@ Required properties: ti,tca6424 ti,tca9539 ti,tca9554 - onsemi,pca9654 + onnn,pca9654 exar,xra1202 Optional properties: diff --git a/Documentation/devicetree/bindings/hwmon/jc42.txt b/Documentation/devicetree/bindings/hwmon/jc42.txt index 07a250498fbb..f569db58f64a 100644 --- a/Documentation/devicetree/bindings/hwmon/jc42.txt +++ b/Documentation/devicetree/bindings/hwmon/jc42.txt @@ -34,6 +34,10 @@ Required properties: - reg: I2C address +Optional properties: +- smbus-timeout-disable: When set, the smbus timeout function will be disabled. + This is not supported on all chips. + Example: temp-sensor@1a { diff --git a/Documentation/devicetree/bindings/i2c/i2c-jz4780.txt b/Documentation/devicetree/bindings/i2c/i2c-jz4780.txt index 231e4cc4008c..d4a082acf92f 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-jz4780.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-jz4780.txt @@ -18,7 +18,7 @@ Optional properties: Example / { - i2c4: i2c4@0x10054000 { + i2c4: i2c4@10054000 { compatible = "ingenic,jz4780-i2c"; reg = <0x10054000 0x1000>; diff --git a/Documentation/devicetree/bindings/iio/pressure/hp03.txt b/Documentation/devicetree/bindings/iio/pressure/hp03.txt index 54e7e70bcea5..831dbee7a5c3 100644 --- a/Documentation/devicetree/bindings/iio/pressure/hp03.txt +++ b/Documentation/devicetree/bindings/iio/pressure/hp03.txt @@ -10,7 +10,7 @@ Required properties: Example: -hp03@0x77 { +hp03@77 { compatible = "hoperf,hp03"; reg = <0x77>; xclr-gpio = <&portc 0 0x0>; diff --git a/Documentation/devicetree/bindings/input/touchscreen/bu21013.txt b/Documentation/devicetree/bindings/input/touchscreen/bu21013.txt index ca5a2c86480c..56d835242af2 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/bu21013.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/bu21013.txt @@ -15,7 +15,7 @@ Optional properties: Example: i2c@80110000 { - bu21013_tp@0x5c { + bu21013_tp@5c { compatible = "rohm,bu21013_tp"; reg = <0x5c>; touch-gpio = <&gpio2 20 0x4>; diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic.txt b/Documentation/devicetree/bindings/interrupt-controller/arm,gic.txt index 560d8a727b8f..2f3244648646 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/arm,gic.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic.txt @@ -155,7 +155,7 @@ Example: <0x0 0xe112f000 0 0x02000>, <0x0 0xe1140000 0 0x10000>, <0x0 0xe1160000 0 0x10000>; - v2m0: v2m@0x8000 { + v2m0: v2m@8000 { compatible = "arm,gic-v2m-frame"; msi-controller; reg = <0x0 0x80000 0 0x1000>; @@ -163,7 +163,7 @@ Example: .... - v2mN: v2m@0x9000 { + v2mN: v2m@9000 { compatible = "arm,gic-v2m-frame"; msi-controller; reg = <0x0 0x90000 0 0x1000>; diff --git a/Documentation/devicetree/bindings/interrupt-controller/img,meta-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/img,meta-intc.txt index 80994adab392..42431f44697f 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/img,meta-intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/img,meta-intc.txt @@ -71,7 +71,7 @@ Example 2: * An interrupt generating device that is wired to a Meta external * trigger block. */ - uart1: uart@0x02004c00 { + uart1: uart@02004c00 { // Interrupt source '5' that is level-sensitive. // Note that there are only two cells as specified in the // interrupt parent's '#interrupt-cells' property. diff --git a/Documentation/devicetree/bindings/interrupt-controller/img,pdc-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/img,pdc-intc.txt index a69118550344..5dc2a55ad811 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/img,pdc-intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/img,pdc-intc.txt @@ -51,7 +51,7 @@ Example 1: /* * TZ1090 PDC block */ - pdc: pdc@0x02006000 { + pdc: pdc@02006000 { // This is an interrupt controller node. interrupt-controller; diff --git a/Documentation/devicetree/bindings/interrupt-controller/st,spear3xx-shirq.txt b/Documentation/devicetree/bindings/interrupt-controller/st,spear3xx-shirq.txt index 715a013ed4bd..2ab0ea39867b 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/st,spear3xx-shirq.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/st,spear3xx-shirq.txt @@ -39,7 +39,7 @@ Example: The following is an example from the SPEAr320 SoC dtsi file. -shirq: interrupt-controller@0xb3000000 { +shirq: interrupt-controller@b3000000 { compatible = "st,spear320-shirq"; reg = <0xb3000000 0x1000>; interrupts = <28 29 30 1>; diff --git a/Documentation/devicetree/bindings/mailbox/altera-mailbox.txt b/Documentation/devicetree/bindings/mailbox/altera-mailbox.txt index c2619797ce0c..49cfc8c337c4 100644 --- a/Documentation/devicetree/bindings/mailbox/altera-mailbox.txt +++ b/Documentation/devicetree/bindings/mailbox/altera-mailbox.txt @@ -14,7 +14,7 @@ Optional properties: depends on the interrupt controller parent. Example: - mbox_tx: mailbox@0x100 { + mbox_tx: mailbox@100 { compatible = "altr,mailbox-1.0"; reg = <0x100 0x8>; interrupt-parent = < &gic_0 >; @@ -22,7 +22,7 @@ Example: #mbox-cells = <1>; }; - mbox_rx: mailbox@0x200 { + mbox_rx: mailbox@200 { compatible = "altr,mailbox-1.0"; reg = <0x200 0x8>; interrupt-parent = < &gic_0 >; @@ -40,7 +40,7 @@ support only one channel).The equivalent "mbox-names" property value can be used to give a name to the communication channel to be used by the client user. Example: - mclient0: mclient0@0x400 { + mclient0: mclient0@400 { compatible = "client-1.0"; reg = <0x400 0x10>; mbox-names = "mbox-tx", "mbox-rx"; diff --git a/Documentation/devicetree/bindings/mailbox/brcm,iproc-pdc-mbox.txt b/Documentation/devicetree/bindings/mailbox/brcm,iproc-pdc-mbox.txt index 0f3ee81d92c2..9bcdf2087625 100644 --- a/Documentation/devicetree/bindings/mailbox/brcm,iproc-pdc-mbox.txt +++ b/Documentation/devicetree/bindings/mailbox/brcm,iproc-pdc-mbox.txt @@ -15,7 +15,7 @@ Optional properties: - brcm,use-bcm-hdr: present if a BCM header precedes each frame. Example: - pdc0: iproc-pdc0@0x612c0000 { + pdc0: iproc-pdc0@612c0000 { compatible = "brcm,iproc-pdc-mbox"; reg = <0 0x612c0000 0 0x445>; /* PDC FS0 regs */ interrupts = <GIC_SPI 187 IRQ_TYPE_LEVEL_HIGH>; diff --git a/Documentation/devicetree/bindings/media/exynos5-gsc.txt b/Documentation/devicetree/bindings/media/exynos5-gsc.txt index 0d4fdaedc6f1..bc963a6d305a 100644 --- a/Documentation/devicetree/bindings/media/exynos5-gsc.txt +++ b/Documentation/devicetree/bindings/media/exynos5-gsc.txt @@ -17,7 +17,7 @@ Optional properties: Example: -gsc_0: gsc@0x13e00000 { +gsc_0: gsc@13e00000 { compatible = "samsung,exynos5250-gsc"; reg = <0x13e00000 0x1000>; interrupts = <0 85 0>; diff --git a/Documentation/devicetree/bindings/media/mediatek-vcodec.txt b/Documentation/devicetree/bindings/media/mediatek-vcodec.txt index 46c15c54175d..2a615d84a682 100644 --- a/Documentation/devicetree/bindings/media/mediatek-vcodec.txt +++ b/Documentation/devicetree/bindings/media/mediatek-vcodec.txt @@ -68,7 +68,7 @@ vcodec_dec: vcodec@16000000 { "vdec_bus_clk_src"; }; - vcodec_enc: vcodec@0x18002000 { + vcodec_enc: vcodec@18002000 { compatible = "mediatek,mt8173-vcodec-enc"; reg = <0 0x18002000 0 0x1000>, /*VENC_SYS*/ <0 0x19002000 0 0x1000>; /*VENC_LT_SYS*/ diff --git a/Documentation/devicetree/bindings/media/rcar_vin.txt b/Documentation/devicetree/bindings/media/rcar_vin.txt index 6e4ef8caf759..19357d0bbe65 100644 --- a/Documentation/devicetree/bindings/media/rcar_vin.txt +++ b/Documentation/devicetree/bindings/media/rcar_vin.txt @@ -44,7 +44,7 @@ Device node example vin0 = &vin0; }; - vin0: vin@0xe6ef0000 { + vin0: vin@e6ef0000 { compatible = "renesas,vin-r8a7790", "renesas,rcar-gen2-vin"; clocks = <&mstp8_clks R8A7790_CLK_VIN0>; reg = <0 0xe6ef0000 0 0x1000>; diff --git a/Documentation/devicetree/bindings/media/samsung-fimc.txt b/Documentation/devicetree/bindings/media/samsung-fimc.txt index e4e15d8d7521..48c599dacbdf 100644 --- a/Documentation/devicetree/bindings/media/samsung-fimc.txt +++ b/Documentation/devicetree/bindings/media/samsung-fimc.txt @@ -138,7 +138,7 @@ Example: }; /* MIPI CSI-2 bus IF sensor */ - s5c73m3: sensor@0x1a { + s5c73m3: sensor@1a { compatible = "samsung,s5c73m3"; reg = <0x1a>; vddio-supply = <...>; diff --git a/Documentation/devicetree/bindings/media/sh_mobile_ceu.txt b/Documentation/devicetree/bindings/media/sh_mobile_ceu.txt index 1ce4e46bcbb7..17a8e81ca0cc 100644 --- a/Documentation/devicetree/bindings/media/sh_mobile_ceu.txt +++ b/Documentation/devicetree/bindings/media/sh_mobile_ceu.txt @@ -8,7 +8,7 @@ Bindings, specific for the sh_mobile_ceu_camera.c driver: Example: -ceu0: ceu@0xfe910000 { +ceu0: ceu@fe910000 { compatible = "renesas,sh-mobile-ceu"; reg = <0xfe910000 0xa0>; interrupt-parent = <&intcs>; diff --git a/Documentation/devicetree/bindings/media/video-interfaces.txt b/Documentation/devicetree/bindings/media/video-interfaces.txt index 3994b0143dd1..258b8dfddf48 100644 --- a/Documentation/devicetree/bindings/media/video-interfaces.txt +++ b/Documentation/devicetree/bindings/media/video-interfaces.txt @@ -154,7 +154,7 @@ imx074 is linked to ceu0 through the MIPI CSI-2 receiver (csi2). ceu0 has a 'port' node which may indicate that at any time only one of the following data pipelines can be active: ov772x -> ceu0 or imx074 -> csi2 -> ceu0. - ceu0: ceu@0xfe910000 { + ceu0: ceu@fe910000 { compatible = "renesas,sh-mobile-ceu"; reg = <0xfe910000 0xa0>; interrupts = <0x880>; @@ -193,9 +193,9 @@ pipelines can be active: ov772x -> ceu0 or imx074 -> csi2 -> ceu0. }; }; - i2c0: i2c@0xfff20000 { + i2c0: i2c@fff20000 { ... - ov772x_1: camera@0x21 { + ov772x_1: camera@21 { compatible = "ovti,ov772x"; reg = <0x21>; vddio-supply = <®ulator1>; @@ -219,7 +219,7 @@ pipelines can be active: ov772x -> ceu0 or imx074 -> csi2 -> ceu0. }; }; - imx074: camera@0x1a { + imx074: camera@1a { compatible = "sony,imx074"; reg = <0x1a>; vddio-supply = <®ulator1>; @@ -239,7 +239,7 @@ pipelines can be active: ov772x -> ceu0 or imx074 -> csi2 -> ceu0. }; }; - csi2: csi2@0xffc90000 { + csi2: csi2@ffc90000 { compatible = "renesas,sh-mobile-csi2"; reg = <0xffc90000 0x1000>; interrupts = <0x17a0>; diff --git a/Documentation/devicetree/bindings/memory-controllers/ti/emif.txt b/Documentation/devicetree/bindings/memory-controllers/ti/emif.txt index fd823d6091b2..152eeccbde1c 100644 --- a/Documentation/devicetree/bindings/memory-controllers/ti/emif.txt +++ b/Documentation/devicetree/bindings/memory-controllers/ti/emif.txt @@ -46,7 +46,7 @@ Optional properties: Example: -emif1: emif@0x4c000000 { +emif1: emif@4c000000 { compatible = "ti,emif-4d"; ti,hwmods = "emif2"; phy-type = <1>; diff --git a/Documentation/devicetree/bindings/mfd/ti-keystone-devctrl.txt b/Documentation/devicetree/bindings/mfd/ti-keystone-devctrl.txt index 20963c76b4bc..71a1f5963936 100644 --- a/Documentation/devicetree/bindings/mfd/ti-keystone-devctrl.txt +++ b/Documentation/devicetree/bindings/mfd/ti-keystone-devctrl.txt @@ -13,7 +13,7 @@ Required properties: Example: -devctrl: device-state-control@0x02620000 { +devctrl: device-state-control@02620000 { compatible = "ti,keystone-devctrl", "syscon"; reg = <0x02620000 0x1000>; }; diff --git a/Documentation/devicetree/bindings/misc/brcm,kona-smc.txt b/Documentation/devicetree/bindings/misc/brcm,kona-smc.txt index 6c9f176f3571..05b47232ed9e 100644 --- a/Documentation/devicetree/bindings/misc/brcm,kona-smc.txt +++ b/Documentation/devicetree/bindings/misc/brcm,kona-smc.txt @@ -9,7 +9,7 @@ Required properties: - reg : Location and size of bounce buffer Example: - smc@0x3404c000 { + smc@3404c000 { compatible = "brcm,bcm11351-smc", "brcm,kona-smc"; reg = <0x3404c000 0x400>; //1 KiB in SRAM }; diff --git a/Documentation/devicetree/bindings/mmc/brcm,kona-sdhci.txt b/Documentation/devicetree/bindings/mmc/brcm,kona-sdhci.txt index aaba2483b4ff..7f5dd83f5bd9 100644 --- a/Documentation/devicetree/bindings/mmc/brcm,kona-sdhci.txt +++ b/Documentation/devicetree/bindings/mmc/brcm,kona-sdhci.txt @@ -12,7 +12,7 @@ Refer to clocks/clock-bindings.txt for generic clock consumer properties. Example: -sdio2: sdio@0x3f1a0000 { +sdio2: sdio@3f1a0000 { compatible = "brcm,kona-sdhci"; reg = <0x3f1a0000 0x10000>; clocks = <&sdio3_clk>; diff --git a/Documentation/devicetree/bindings/mmc/brcm,sdhci-iproc.txt b/Documentation/devicetree/bindings/mmc/brcm,sdhci-iproc.txt index 954561d09a8e..fa90d253dc7e 100644 --- a/Documentation/devicetree/bindings/mmc/brcm,sdhci-iproc.txt +++ b/Documentation/devicetree/bindings/mmc/brcm,sdhci-iproc.txt @@ -24,7 +24,7 @@ Optional properties: Example: -sdhci0: sdhci@0x18041000 { +sdhci0: sdhci@18041000 { compatible = "brcm,sdhci-iproc-cygnus"; reg = <0x18041000 0x100>; interrupts = <GIC_SPI 108 IRQ_TYPE_LEVEL_HIGH>; diff --git a/Documentation/devicetree/bindings/mmc/ti-omap-hsmmc.txt b/Documentation/devicetree/bindings/mmc/ti-omap-hsmmc.txt index 3a4ac401e6f9..19f5508a7569 100644 --- a/Documentation/devicetree/bindings/mmc/ti-omap-hsmmc.txt +++ b/Documentation/devicetree/bindings/mmc/ti-omap-hsmmc.txt @@ -55,7 +55,7 @@ Examples: [hwmod populated DMA resources] - mmc1: mmc@0x4809c000 { + mmc1: mmc@4809c000 { compatible = "ti,omap4-hsmmc"; reg = <0x4809c000 0x400>; ti,hwmods = "mmc1"; @@ -67,7 +67,7 @@ Examples: [generic DMA request binding] - mmc1: mmc@0x4809c000 { + mmc1: mmc@4809c000 { compatible = "ti,omap4-hsmmc"; reg = <0x4809c000 0x400>; ti,hwmods = "mmc1"; diff --git a/Documentation/devicetree/bindings/mtd/gpmc-nor.txt b/Documentation/devicetree/bindings/mtd/gpmc-nor.txt index 131d3a74d0bd..c8567b40fe13 100644 --- a/Documentation/devicetree/bindings/mtd/gpmc-nor.txt +++ b/Documentation/devicetree/bindings/mtd/gpmc-nor.txt @@ -82,15 +82,15 @@ gpmc: gpmc@6e000000 { label = "bootloader-nor"; reg = <0 0x40000>; }; - partition@0x40000 { + partition@40000 { label = "params-nor"; reg = <0x40000 0x40000>; }; - partition@0x80000 { + partition@80000 { label = "kernel-nor"; reg = <0x80000 0x200000>; }; - partition@0x280000 { + partition@280000 { label = "filesystem-nor"; reg = <0x240000 0x7d80000>; }; diff --git a/Documentation/devicetree/bindings/mtd/mtk-nand.txt b/Documentation/devicetree/bindings/mtd/mtk-nand.txt index dbf9e054c11c..0431841de781 100644 --- a/Documentation/devicetree/bindings/mtd/mtk-nand.txt +++ b/Documentation/devicetree/bindings/mtd/mtk-nand.txt @@ -131,7 +131,7 @@ Example: read-only; reg = <0x00000000 0x00400000>; }; - android@0x00400000 { + android@00400000 { label = "android"; reg = <0x00400000 0x12c00000>; }; diff --git a/Documentation/devicetree/bindings/net/altera_tse.txt b/Documentation/devicetree/bindings/net/altera_tse.txt index a706297998e9..0e21df94a53f 100644 --- a/Documentation/devicetree/bindings/net/altera_tse.txt +++ b/Documentation/devicetree/bindings/net/altera_tse.txt @@ -52,7 +52,7 @@ Optional properties: Example: - tse_sub_0_eth_tse_0: ethernet@0x1,00000000 { + tse_sub_0_eth_tse_0: ethernet@1,00000000 { compatible = "altr,tse-msgdma-1.0"; reg = <0x00000001 0x00000000 0x00000400>, <0x00000001 0x00000460 0x00000020>, @@ -90,7 +90,7 @@ Example: }; }; - tse_sub_1_eth_tse_0: ethernet@0x1,00001000 { + tse_sub_1_eth_tse_0: ethernet@1,00001000 { compatible = "altr,tse-msgdma-1.0"; reg = <0x00000001 0x00001000 0x00000400>, <0x00000001 0x00001460 0x00000020>, diff --git a/Documentation/devicetree/bindings/net/mdio.txt b/Documentation/devicetree/bindings/net/mdio.txt index 96a53f89aa6e..e3e1603f256c 100644 --- a/Documentation/devicetree/bindings/net/mdio.txt +++ b/Documentation/devicetree/bindings/net/mdio.txt @@ -18,7 +18,7 @@ Example : This example shows these optional properties, plus other properties required for the TI Davinci MDIO driver. - davinci_mdio: ethernet@0x5c030000 { + davinci_mdio: ethernet@5c030000 { compatible = "ti,davinci_mdio"; reg = <0x5c030000 0x1000>; #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/net/socfpga-dwmac.txt b/Documentation/devicetree/bindings/net/socfpga-dwmac.txt index b30d04b54ee9..17d6819669c8 100644 --- a/Documentation/devicetree/bindings/net/socfpga-dwmac.txt +++ b/Documentation/devicetree/bindings/net/socfpga-dwmac.txt @@ -28,7 +28,7 @@ Required properties: Example: -gmii_to_sgmii_converter: phy@0x100000240 { +gmii_to_sgmii_converter: phy@100000240 { compatible = "altr,gmii-to-sgmii-2.0"; reg = <0x00000001 0x00000240 0x00000008>, <0x00000001 0x00000200 0x00000040>; diff --git a/Documentation/devicetree/bindings/nios2/nios2.txt b/Documentation/devicetree/bindings/nios2/nios2.txt index d6d0a94cb3bb..b95e831bcba3 100644 --- a/Documentation/devicetree/bindings/nios2/nios2.txt +++ b/Documentation/devicetree/bindings/nios2/nios2.txt @@ -36,7 +36,7 @@ Optional properties: Example: -cpu@0x0 { +cpu@0 { device_type = "cpu"; compatible = "altr,nios2-1.0"; reg = <0>; diff --git a/Documentation/devicetree/bindings/pci/altera-pcie.txt b/Documentation/devicetree/bindings/pci/altera-pcie.txt index 495880193adc..a1dc9366a8fc 100644 --- a/Documentation/devicetree/bindings/pci/altera-pcie.txt +++ b/Documentation/devicetree/bindings/pci/altera-pcie.txt @@ -25,7 +25,7 @@ Optional properties: - bus-range: PCI bus numbers covered Example - pcie_0: pcie@0xc00000000 { + pcie_0: pcie@c00000000 { compatible = "altr,pcie-root-port-1.0"; reg = <0xc0000000 0x20000000>, <0xff220000 0x00004000>; diff --git a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt index 7b1e48bf172b..149d8f7f86b0 100644 --- a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt +++ b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt @@ -52,7 +52,7 @@ Additional required properties for imx7d-pcie: Example: - pcie@0x01000000 { + pcie@01000000 { compatible = "fsl,imx6q-pcie", "snps,dw-pcie"; reg = <0x01ffc000 0x04000>, <0x01f00000 0x80000>; diff --git a/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt b/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt index bdb7ab39d2d7..7bf9df047a1e 100644 --- a/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt +++ b/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt @@ -21,7 +21,7 @@ Optional properties: - dma-coherent: Present if DMA operations are coherent. Hip05 Example (note that Hip06 is the same except compatible): - pcie@0xb0080000 { + pcie@b0080000 { compatible = "hisilicon,hip05-pcie", "snps,dw-pcie"; reg = <0 0xb0080000 0 0x10000>, <0x220 0x00000000 0 0x2000>; reg-names = "rc_dbi", "config"; diff --git a/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt b/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt index cbc7847dbf6c..c1ce5a0a652e 100644 --- a/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt +++ b/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt @@ -45,7 +45,7 @@ Optional properties: - usb3_vbus-supply : regulator phandle for controller usb3 vbus Example: - usbphy: phy@0x01c13400 { + usbphy: phy@01c13400 { #phy-cells = <1>; compatible = "allwinner,sun4i-a10-usb-phy"; /* phy base regs, phy1 pmu reg, phy2 pmu reg */ diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,cygnus-pinmux.txt b/Documentation/devicetree/bindings/pinctrl/brcm,cygnus-pinmux.txt index 3600d5c6c4d7..3914529a3214 100644 --- a/Documentation/devicetree/bindings/pinctrl/brcm,cygnus-pinmux.txt +++ b/Documentation/devicetree/bindings/pinctrl/brcm,cygnus-pinmux.txt @@ -25,7 +25,7 @@ Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt For example: - pinmux: pinmux@0x0301d0c8 { + pinmux: pinmux@0301d0c8 { compatible = "brcm,cygnus-pinmux"; reg = <0x0301d0c8 0x1b0>; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-atlas7.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-atlas7.txt index eecf028ff485..bf9b07016c87 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-atlas7.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-atlas7.txt @@ -96,14 +96,14 @@ For example, pinctrl might have subnodes like the following: For a specific board, if it wants to use sd1, it can add the following to its board-specific .dts file. -sd1: sd@0x12340000 { +sd1: sd@12340000 { pinctrl-names = "default"; pinctrl-0 = <&sd1_pmx0>; } or -sd1: sd@0x12340000 { +sd1: sd@12340000 { pinctrl-names = "default"; pinctrl-0 = <&sd1_pmx1>; } diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-sirf.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-sirf.txt index 5f55be59d914..f8420520e14b 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-sirf.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-sirf.txt @@ -41,7 +41,7 @@ For example, pinctrl might have subnodes like the following: For a specific board, if it wants to use uart2 without hardware flow control, it can add the following to its board-specific .dts file. -uart2: uart@0xb0070000 { +uart2: uart@b0070000 { pinctrl-names = "default"; pinctrl-0 = <&uart2_noflow_pins_a>; } diff --git a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt index 4864e3a74de3..a01a3b8a2363 100644 --- a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt @@ -136,7 +136,7 @@ Example for rk3188: #size-cells = <1>; ranges; - gpio0: gpio0@0x2000a000 { + gpio0: gpio0@2000a000 { compatible = "rockchip,rk3188-gpio-bank0"; reg = <0x2000a000 0x100>; interrupts = <GIC_SPI 54 IRQ_TYPE_LEVEL_HIGH>; @@ -149,7 +149,7 @@ Example for rk3188: #interrupt-cells = <2>; }; - gpio1: gpio1@0x2003c000 { + gpio1: gpio1@2003c000 { compatible = "rockchip,gpio-bank"; reg = <0x2003c000 0x100>; interrupts = <GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH>; diff --git a/Documentation/devicetree/bindings/regulator/regulator.txt b/Documentation/devicetree/bindings/regulator/regulator.txt index 378f6dc8b8bd..3cbf56ce66ea 100644 --- a/Documentation/devicetree/bindings/regulator/regulator.txt +++ b/Documentation/devicetree/bindings/regulator/regulator.txt @@ -107,7 +107,7 @@ regulators (twl_reg1 and twl_reg2), ... }; - mmc: mmc@0x0 { + mmc: mmc@0 { ... ... vmmc-supply = <&twl_reg1>; diff --git a/Documentation/devicetree/bindings/serial/efm32-uart.txt b/Documentation/devicetree/bindings/serial/efm32-uart.txt index 8adbab268ca3..4f8d8fde0c1c 100644 --- a/Documentation/devicetree/bindings/serial/efm32-uart.txt +++ b/Documentation/devicetree/bindings/serial/efm32-uart.txt @@ -12,7 +12,7 @@ Optional properties: Example: -uart@0x4000c400 { +uart@4000c400 { compatible = "energymicro,efm32-uart"; reg = <0x4000c400 0x400>; interrupts = <15>; diff --git a/Documentation/devicetree/bindings/serio/allwinner,sun4i-ps2.txt b/Documentation/devicetree/bindings/serio/allwinner,sun4i-ps2.txt index f311472990a7..75996b6111bb 100644 --- a/Documentation/devicetree/bindings/serio/allwinner,sun4i-ps2.txt +++ b/Documentation/devicetree/bindings/serio/allwinner,sun4i-ps2.txt @@ -14,7 +14,7 @@ Required properties: Example: - ps20: ps2@0x01c2a000 { + ps20: ps2@01c2a000 { compatible = "allwinner,sun4i-a10-ps2"; reg = <0x01c2a000 0x400>; interrupts = <0 62 4>; diff --git a/Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt b/Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt index 64c66a5644e7..77cd42cc5f54 100644 --- a/Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt +++ b/Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt @@ -220,7 +220,7 @@ qmss: qmss@2a40000 { #address-cells = <1>; #size-cells = <1>; ranges; - pdsp0@0x2a10000 { + pdsp0@2a10000 { reg = <0x2a10000 0x1000>, <0x2a0f000 0x100>, <0x2a0c000 0x3c8>, diff --git a/Documentation/devicetree/bindings/sound/adi,axi-i2s.txt b/Documentation/devicetree/bindings/sound/adi,axi-i2s.txt index 5875ca459ed1..4248b662deff 100644 --- a/Documentation/devicetree/bindings/sound/adi,axi-i2s.txt +++ b/Documentation/devicetree/bindings/sound/adi,axi-i2s.txt @@ -21,7 +21,7 @@ please check: Example: - i2s: i2s@0x77600000 { + i2s: i2s@77600000 { compatible = "adi,axi-i2s-1.00.a"; reg = <0x77600000 0x1000>; clocks = <&clk 15>, <&audio_clock>; diff --git a/Documentation/devicetree/bindings/sound/adi,axi-spdif-tx.txt b/Documentation/devicetree/bindings/sound/adi,axi-spdif-tx.txt index 4eb7997674a0..7b664e7cb4ae 100644 --- a/Documentation/devicetree/bindings/sound/adi,axi-spdif-tx.txt +++ b/Documentation/devicetree/bindings/sound/adi,axi-spdif-tx.txt @@ -20,7 +20,7 @@ please check: Example: - spdif: spdif@0x77400000 { + spdif: spdif@77400000 { compatible = "adi,axi-spdif-tx-1.00.a"; reg = <0x77600000 0x1000>; clocks = <&clk 15>, <&audio_clock>; diff --git a/Documentation/devicetree/bindings/sound/ak4613.txt b/Documentation/devicetree/bindings/sound/ak4613.txt index 1783f9ef0930..49a2e74fd9cb 100644 --- a/Documentation/devicetree/bindings/sound/ak4613.txt +++ b/Documentation/devicetree/bindings/sound/ak4613.txt @@ -20,7 +20,7 @@ Optional properties: Example: &i2c { - ak4613: ak4613@0x10 { + ak4613: ak4613@10 { compatible = "asahi-kasei,ak4613"; reg = <0x10>; }; diff --git a/Documentation/devicetree/bindings/sound/ak4642.txt b/Documentation/devicetree/bindings/sound/ak4642.txt index 340784db6808..58e48ee97175 100644 --- a/Documentation/devicetree/bindings/sound/ak4642.txt +++ b/Documentation/devicetree/bindings/sound/ak4642.txt @@ -17,7 +17,7 @@ Optional properties: Example 1: &i2c { - ak4648: ak4648@0x12 { + ak4648: ak4648@12 { compatible = "asahi-kasei,ak4642"; reg = <0x12>; }; diff --git a/Documentation/devicetree/bindings/sound/max98371.txt b/Documentation/devicetree/bindings/sound/max98371.txt index 6c285235e64b..8b2b2704b574 100644 --- a/Documentation/devicetree/bindings/sound/max98371.txt +++ b/Documentation/devicetree/bindings/sound/max98371.txt @@ -10,7 +10,7 @@ Required properties: Example: &i2c { - max98371: max98371@0x31 { + max98371: max98371@31 { compatible = "maxim,max98371"; reg = <0x31>; }; diff --git a/Documentation/devicetree/bindings/sound/max9867.txt b/Documentation/devicetree/bindings/sound/max9867.txt index 394cd4eb17ec..b8bd914ee697 100644 --- a/Documentation/devicetree/bindings/sound/max9867.txt +++ b/Documentation/devicetree/bindings/sound/max9867.txt @@ -10,7 +10,7 @@ Required properties: Example: &i2c { - max9867: max9867@0x18 { + max9867: max9867@18 { compatible = "maxim,max9867"; reg = <0x18>; }; diff --git a/Documentation/devicetree/bindings/sound/renesas,fsi.txt b/Documentation/devicetree/bindings/sound/renesas,fsi.txt index 0d0ab51105b0..0cf0f819b823 100644 --- a/Documentation/devicetree/bindings/sound/renesas,fsi.txt +++ b/Documentation/devicetree/bindings/sound/renesas,fsi.txt @@ -20,7 +20,7 @@ Required properties: Example: -sh_fsi2: sh_fsi2@0xec230000 { +sh_fsi2: sh_fsi2@ec230000 { compatible = "renesas,sh_fsi2"; reg = <0xec230000 0x400>; interrupts = <0 146 0x4>; diff --git a/Documentation/devicetree/bindings/sound/rockchip-spdif.txt b/Documentation/devicetree/bindings/sound/rockchip-spdif.txt index 0a1dc4e1815c..ec20c1271e92 100644 --- a/Documentation/devicetree/bindings/sound/rockchip-spdif.txt +++ b/Documentation/devicetree/bindings/sound/rockchip-spdif.txt @@ -33,7 +33,7 @@ Required properties on RK3288: Example for the rk3188 SPDIF controller: -spdif: spdif@0x1011e000 { +spdif: spdif@1011e000 { compatible = "rockchip,rk3188-spdif", "rockchip,rk3066-spdif"; reg = <0x1011e000 0x2000>; interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>; diff --git a/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt b/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt index 40068ec0e9a5..9c1ee52fed5b 100644 --- a/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt +++ b/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt @@ -51,7 +51,7 @@ Optional properties: Example: - sti_uni_player1: sti-uni-player@0x8D81000 { + sti_uni_player1: sti-uni-player@8D81000 { compatible = "st,stih407-uni-player-hdmi"; #sound-dai-cells = <0>; st,syscfg = <&syscfg_core>; @@ -63,7 +63,7 @@ Example: st,tdm-mode = <1>; }; - sti_uni_player2: sti-uni-player@0x8D82000 { + sti_uni_player2: sti-uni-player@8D82000 { compatible = "st,stih407-uni-player-pcm-out"; #sound-dai-cells = <0>; st,syscfg = <&syscfg_core>; @@ -74,7 +74,7 @@ Example: dma-names = "tx"; }; - sti_uni_player3: sti-uni-player@0x8D85000 { + sti_uni_player3: sti-uni-player@8D85000 { compatible = "st,stih407-uni-player-spdif"; #sound-dai-cells = <0>; st,syscfg = <&syscfg_core>; @@ -85,7 +85,7 @@ Example: dma-names = "tx"; }; - sti_uni_reader1: sti-uni-reader@0x8D84000 { + sti_uni_reader1: sti-uni-reader@8D84000 { compatible = "st,stih407-uni-reader-hdmi"; #sound-dai-cells = <0>; st,syscfg = <&syscfg_core>; diff --git a/Documentation/devicetree/bindings/spi/efm32-spi.txt b/Documentation/devicetree/bindings/spi/efm32-spi.txt index 2c1e6a43930b..e0fa61a1be0c 100644 --- a/Documentation/devicetree/bindings/spi/efm32-spi.txt +++ b/Documentation/devicetree/bindings/spi/efm32-spi.txt @@ -19,7 +19,7 @@ Recommended properties : Example: -spi1: spi@0x4000c400 { /* USART1 */ +spi1: spi@4000c400 { /* USART1 */ #address-cells = <1>; #size-cells = <0>; compatible = "energymicro,efm32-spi"; diff --git a/Documentation/devicetree/bindings/thermal/thermal.txt b/Documentation/devicetree/bindings/thermal/thermal.txt index 88b6ea1ad290..44d7cb2cb2c0 100644 --- a/Documentation/devicetree/bindings/thermal/thermal.txt +++ b/Documentation/devicetree/bindings/thermal/thermal.txt @@ -239,7 +239,7 @@ cpus { * A simple fan controller which supports 10 speeds of operation * (represented as 0-9). */ - fan0: fan@0x48 { + fan0: fan@48 { ... cooling-min-level = <0>; cooling-max-level = <9>; @@ -252,7 +252,7 @@ ocp { /* * A simple IC with a single bandgap temperature sensor. */ - bandgap0: bandgap@0x0000ED00 { + bandgap0: bandgap@0000ED00 { ... #thermal-sensor-cells = <0>; }; @@ -330,7 +330,7 @@ ocp { /* * A simple IC with several bandgap temperature sensors. */ - bandgap0: bandgap@0x0000ED00 { + bandgap0: bandgap@0000ED00 { ... #thermal-sensor-cells = <1>; }; @@ -447,7 +447,7 @@ one thermal zone. /* * A simple IC with a single temperature sensor. */ - adc: sensor@0x49 { + adc: sensor@49 { ... #thermal-sensor-cells = <0>; }; @@ -458,7 +458,7 @@ ocp { /* * A simple IC with a single bandgap temperature sensor. */ - bandgap0: bandgap@0x0000ED00 { + bandgap0: bandgap@0000ED00 { ... #thermal-sensor-cells = <0>; }; @@ -516,7 +516,7 @@ with many sensors and many cooling devices. /* * An IC with several temperature sensor. */ - adc_dummy: sensor@0x50 { + adc_dummy: sensor@50 { ... #thermal-sensor-cells = <1>; /* sensor internal ID */ }; diff --git a/Documentation/devicetree/bindings/ufs/ufs-qcom.txt b/Documentation/devicetree/bindings/ufs/ufs-qcom.txt index 1f69ee1a61ea..21d9a93db2e9 100644 --- a/Documentation/devicetree/bindings/ufs/ufs-qcom.txt +++ b/Documentation/devicetree/bindings/ufs/ufs-qcom.txt @@ -32,7 +32,7 @@ Optional properties: Example: - ufsphy1: ufsphy@0xfc597000 { + ufsphy1: ufsphy@fc597000 { compatible = "qcom,ufs-phy-qmp-20nm"; reg = <0xfc597000 0x800>; reg-names = "phy_mem"; @@ -53,7 +53,7 @@ Example: <&clock_gcc clk_gcc_ufs_rx_cfg_clk>; }; - ufshc@0xfc598000 { + ufshc@fc598000 { ... phys = <&ufsphy1>; phy-names = "ufsphy"; diff --git a/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt b/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt index a99ed5565b26..c39dfef76a18 100644 --- a/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt +++ b/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt @@ -46,7 +46,7 @@ Note: If above properties are not defined it can be assumed that the supply regulators or clocks are always on. Example: - ufshc@0xfc598000 { + ufshc@fc598000 { compatible = "jedec,ufs-1.1"; reg = <0xfc598000 0x800>; interrupts = <0 28 0>; diff --git a/Documentation/devicetree/bindings/usb/am33xx-usb.txt b/Documentation/devicetree/bindings/usb/am33xx-usb.txt index 7a33f22c815a..7a198a30408a 100644 --- a/Documentation/devicetree/bindings/usb/am33xx-usb.txt +++ b/Documentation/devicetree/bindings/usb/am33xx-usb.txt @@ -95,6 +95,7 @@ usb: usb@47400000 { reg = <0x47401300 0x100>; reg-names = "phy"; ti,ctrl_mod = <&ctrl_mod>; + #phy-cells = <0>; }; usb0: usb@47401000 { @@ -141,6 +142,7 @@ usb: usb@47400000 { reg = <0x47401b00 0x100>; reg-names = "phy"; ti,ctrl_mod = <&ctrl_mod>; + #phy-cells = <0>; }; usb1: usb@47401800 { diff --git a/Documentation/devicetree/bindings/usb/ehci-st.txt b/Documentation/devicetree/bindings/usb/ehci-st.txt index 9feea6c3e4d9..065c91d955ad 100644 --- a/Documentation/devicetree/bindings/usb/ehci-st.txt +++ b/Documentation/devicetree/bindings/usb/ehci-st.txt @@ -22,7 +22,7 @@ See: Documentation/devicetree/bindings/reset/reset.txt Example: - ehci1: usb@0xfe203e00 { + ehci1: usb@fe203e00 { compatible = "st,st-ehci-300x"; reg = <0xfe203e00 0x100>; interrupts = <GIC_SPI 148 IRQ_TYPE_NONE>; diff --git a/Documentation/devicetree/bindings/usb/ohci-st.txt b/Documentation/devicetree/bindings/usb/ohci-st.txt index d893ec9131c3..44c998c16f85 100644 --- a/Documentation/devicetree/bindings/usb/ohci-st.txt +++ b/Documentation/devicetree/bindings/usb/ohci-st.txt @@ -20,7 +20,7 @@ See: Documentation/devicetree/bindings/reset/reset.txt Example: - ohci0: usb@0xfe1ffc00 { + ohci0: usb@fe1ffc00 { compatible = "st,st-ohci-300x"; reg = <0xfe1ffc00 0x100>; interrupts = <GIC_SPI 149 IRQ_TYPE_NONE>; diff --git a/Documentation/devicetree/bindings/watchdog/ingenic,jz4740-wdt.txt b/Documentation/devicetree/bindings/watchdog/ingenic,jz4740-wdt.txt index e27763ef0049..3c7a1cd13b10 100644 --- a/Documentation/devicetree/bindings/watchdog/ingenic,jz4740-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/ingenic,jz4740-wdt.txt @@ -6,7 +6,7 @@ reg: Register address and length for watchdog registers Example: -watchdog: jz4740-watchdog@0x10002000 { +watchdog: jz4740-watchdog@10002000 { compatible = "ingenic,jz4740-watchdog"; reg = <0x10002000 0x100>; }; diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 0268335414ce..722d4525f7cf 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -112,16 +112,17 @@ Example kernel-doc function comment:: /** * foobar() - Brief description of foobar. - * @arg: Description of argument of foobar. + * @argument1: Description of parameter argument1 of foobar. + * @argument2: Description of parameter argument2 of foobar. * * Longer description of foobar. * * Return: Description of return value of foobar. */ - int foobar(int arg) + int foobar(int argument1, char *argument2) The format is similar for documentation for structures, enums, paragraphs, -etc. See the sections below for details. +etc. See the sections below for specific details of each type. The kernel-doc structure is extracted from the comments, and proper `Sphinx C Domain`_ function and type descriptions with anchors are generated for them. The @@ -130,6 +131,226 @@ cross-references. See below for details. .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html + +Parameters and member arguments +------------------------------- + +The kernel-doc function comments describe each parameter to the function and +function typedefs or each member of struct/union, in order, with the +``@argument:`` descriptions. For each non-private member argument, one +``@argument`` definition is needed. + +The ``@argument:`` descriptions begin on the very next line following +the opening brief function description line, with no intervening blank +comment lines. + +The ``@argument:`` descriptions may span multiple lines. + +.. note:: + + If the ``@argument`` description has multiple lines, the continuation + of the description should be starting exactly at the same column as + the previous line, e. g.:: + + * @argument: some long description + * that continues on next lines + + or:: + + * @argument: + * some long description + * that continues on next lines + +If a function or typedef parameter argument is ``...`` (e. g. a variable +number of arguments), its description should be listed in kernel-doc +notation as:: + + * @...: description + +Private members +~~~~~~~~~~~~~~~ + +Inside a struct or union description, you can use the ``private:`` and +``public:`` comment tags. Structure fields that are inside a ``private:`` +area are not listed in the generated output documentation. + +The ``private:`` and ``public:`` tags must begin immediately following a +``/*`` comment marker. They may optionally include comments between the +``:`` and the ending ``*/`` marker. + +Example:: + + /** + * struct my_struct - short description + * @a: first member + * @b: second member + * @d: fourth member + * + * Longer description + */ + struct my_struct { + int a; + int b; + /* private: internal use only */ + int c; + /* public: the next one is public */ + int d; + }; + +Function documentation +---------------------- + +The general format of a function and function-like macro kernel-doc comment is:: + + /** + * function_name() - Brief description of function. + * @arg1: Describe the first argument. + * @arg2: Describe the second argument. + * One can provide multiple line descriptions + * for arguments. + * + * A longer description, with more discussion of the function function_name() + * that might be useful to those using or modifying it. Begins with an + * empty comment line, and may include additional embedded empty + * comment lines. + * + * The longer description may have multiple paragraphs. + * + * Return: Describe the return value of foobar. + * + * The return value description can also have multiple paragraphs, and should + * be placed at the end of the comment block. + */ + +The brief description following the function name may span multiple lines, and +ends with an argument description, a blank comment line, or the end of the +comment block. + +Return values +~~~~~~~~~~~~~ + +The return value, if any, should be described in a dedicated section +named ``Return``. + +.. note:: + + #) The multi-line descriptive text you provide does *not* recognize + line breaks, so if you try to format some text nicely, as in:: + + * Return: + * 0 - OK + * -EINVAL - invalid argument + * -ENOMEM - out of memory + + this will all run together and produce:: + + Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory + + So, in order to produce the desired line breaks, you need to use a + ReST list, e. g.:: + + * Return: + * * 0 - OK to runtime suspend the device + * * -EBUSY - Device should not be runtime suspended + + #) If the descriptive text you provide has lines that begin with + some phrase followed by a colon, each of those phrases will be taken + as a new section heading, with probably won't produce the desired + effect. + +Structure, union, and enumeration documentation +----------------------------------------------- + +The general format of a struct, union, and enum kernel-doc comment is:: + + /** + * struct struct_name - Brief description. + * @argument: Description of member member_name. + * + * Description of the structure. + */ + +On the above, ``struct`` is used to mean structs. You can also use ``union`` +and ``enum`` to describe unions and enums. ``argument`` is used +to mean struct and union member names as well as enumerations in an enum. + +The brief description following the structure name may span multiple lines, and +ends with a member description, a blank comment line, or the end of the +comment block. + +The kernel-doc data structure comments describe each member of the structure, +in order, with the member descriptions. + +Nested structs/unions +~~~~~~~~~~~~~~~~~~~~~ + +It is possible to document nested structs unions, like:: + + /** + * struct nested_foobar - a struct with nested unions and structs + * @arg1: - first argument of anonymous union/anonymous struct + * @arg2: - second argument of anonymous union/anonymous struct + * @arg3: - third argument of anonymous union/anonymous struct + * @arg4: - fourth argument of anonymous union/anonymous struct + * @bar.st1.arg1 - first argument of struct st1 on union bar + * @bar.st1.arg2 - second argument of struct st1 on union bar + * @bar.st2.arg1 - first argument of struct st2 on union bar + * @bar.st2.arg2 - second argument of struct st2 on union bar + struct nested_foobar { + /* Anonymous union/struct*/ + union { + struct { + int arg1; + int arg2; + } + struct { + void *arg3; + int arg4; + } + } + union { + struct { + int arg1; + int arg2; + } st1; + struct { + void *arg1; + int arg2; + } st2; + } bar; + }; + +.. note:: + + #) When documenting nested structs or unions, if the struct/union ``foo`` + is named, the argument ``bar`` inside it should be documented as + ``@foo.bar:`` + #) When the nested struct/union is anonymous, the argument ``bar`` on it + should be documented as ``@bar:`` + +Typedef documentation +--------------------- + +The general format of a typedef kernel-doc comment is:: + + /** + * typedef type_name - Brief description. + * + * Description of the type. + */ + +Typedefs with function prototypes can also be documented:: + + /** + * typedef type_name - Brief description. + * @arg1: description of arg1 + * @arg2: description of arg2 + * + * Description of the type. + */ + typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); + + Highlights and cross-references ------------------------------- @@ -201,70 +422,7 @@ cross-references. For further details, please refer to the `Sphinx C Domain`_ documentation. -Function documentation ----------------------- - -The general format of a function and function-like macro kernel-doc comment is:: - - /** - * function_name() - Brief description of function. - * @arg1: Describe the first argument. - * @arg2: Describe the second argument. - * One can provide multiple line descriptions - * for arguments. - * - * A longer description, with more discussion of the function function_name() - * that might be useful to those using or modifying it. Begins with an - * empty comment line, and may include additional embedded empty - * comment lines. - * - * The longer description may have multiple paragraphs. - * - * Return: Describe the return value of foobar. - * - * The return value description can also have multiple paragraphs, and should - * be placed at the end of the comment block. - */ - -The brief description following the function name may span multiple lines, and -ends with an ``@argument:`` description, a blank comment line, or the end of the -comment block. - -The kernel-doc function comments describe each parameter to the function, in -order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions -must begin on the very next line following the opening brief function -description line, with no intervening blank comment lines. The ``@argument:`` -descriptions may span multiple lines. The continuation lines may contain -indentation. If a function parameter is ``...`` (varargs), it should be listed -in kernel-doc notation as: ``@...:``. - -The return value, if any, should be described in a dedicated section at the end -of the comment starting with "Return:". - -Structure, union, and enumeration documentation ------------------------------------------------ - -The general format of a struct, union, and enum kernel-doc comment is:: - - /** - * struct struct_name - Brief description. - * @member_name: Description of member member_name. - * - * Description of the structure. - */ - -Below, "struct" is used to mean structs, unions and enums, and "member" is used -to mean struct and union members as well as enumerations in an enum. - -The brief description following the structure name may span multiple lines, and -ends with a ``@member:`` description, a blank comment line, or the end of the -comment block. -The kernel-doc data structure comments describe each member of the structure, in -order, with the ``@member:`` descriptions. The ``@member:`` descriptions must -begin on the very next line following the opening brief function description -line, with no intervening blank comment lines. The ``@member:`` descriptions may -span multiple lines. The continuation lines may contain indentation. In-line member documentation comments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -294,42 +452,6 @@ on a line of their own, like all other kernel-doc comments:: int foobar; } -Private members -~~~~~~~~~~~~~~~ - -Inside a struct description, you can use the "private:" and "public:" comment -tags. Structure fields that are inside a "private:" area are not listed in the -generated output documentation. The "private:" and "public:" tags must begin -immediately following a ``/*`` comment marker. They may optionally include -comments between the ``:`` and the ending ``*/`` marker. - -Example:: - - /** - * struct my_struct - short description - * @a: first member - * @b: second member - * - * Longer description - */ - struct my_struct { - int a; - int b; - /* private: internal use only */ - int c; - }; - - -Typedef documentation ---------------------- - -The general format of a typedef kernel-doc comment is:: - - /** - * typedef type_name - Brief description. - * - * Description of the type. - */ Overview documentation comments ------------------------------- @@ -376,3 +498,37 @@ file. Data structures visible in kernel include files should also be documented using kernel-doc formatted comments. + +How to use kernel-doc to generate man pages +------------------------------------------- + +If you just want to use kernel-doc to generate man pages you can do this +from the Kernel git tree:: + + $ scripts/kernel-doc -man $(git grep -l '/\*\*' |grep -v Documentation/) | ./split-man.pl /tmp/man + +Using the small ``split-man.pl`` script below:: + + + #!/usr/bin/perl + + if ($#ARGV < 0) { + die "where do I put the results?\n"; + } + + mkdir $ARGV[0],0777; + $state = 0; + while (<STDIN>) { + if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) { + if ($state == 1) { close OUT } + $state = 1; + $fn = "$ARGV[0]/$1.9"; + print STDERR "Creating $fn\n"; + open OUT, ">$fn" or die "can't open $fn: $!\n"; + print OUT $_; + } elsif ($state != 0) { + print OUT $_; + } + } + + close OUT; diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst index 73fa7d42bbba..826e85d50a16 100644 --- a/Documentation/driver-api/basics.rst +++ b/Documentation/driver-api/basics.rst @@ -13,12 +13,6 @@ Driver device table .. kernel-doc:: include/linux/mod_devicetable.h :internal: -Atomic and pointer manipulation -------------------------------- - -.. kernel-doc:: arch/x86/include/asm/atomic.h - :internal: - Delaying, scheduling, and timer routines ---------------------------------------- @@ -85,6 +79,21 @@ Internal Functions .. kernel-doc:: kernel/kthread.c :export: +Reference counting +------------------ + +.. kernel-doc:: include/linux/refcount.h + :internal: + +.. kernel-doc:: lib/refcount.c + :export: + +Atomics +------- + +.. kernel-doc:: arch/x86/include/asm/atomic.h + :internal: + Kernel objects manipulation --------------------------- diff --git a/Documentation/driver-api/dmaengine/client.rst b/Documentation/driver-api/dmaengine/client.rst index 6245c99af8c1..fbbb2831f29f 100644 --- a/Documentation/driver-api/dmaengine/client.rst +++ b/Documentation/driver-api/dmaengine/client.rst @@ -185,7 +185,7 @@ The details of these operations are: void dma_async_issue_pending(struct dma_chan *chan); Further APIs: ------------- +------------- 1. Terminate APIs diff --git a/Documentation/driver-api/pci.rst b/Documentation/driver-api/pci.rst index 01a6c8b7d3a7..ca85e5e78b2c 100644 --- a/Documentation/driver-api/pci.rst +++ b/Documentation/driver-api/pci.rst @@ -25,9 +25,6 @@ PCI Support Library .. kernel-doc:: drivers/pci/irq.c :export: -.. kernel-doc:: drivers/pci/htirq.c - :export: - .. kernel-doc:: drivers/pci/probe.c :export: diff --git a/Documentation/driver-api/usb/usb3-debug-port.rst b/Documentation/driver-api/usb/usb3-debug-port.rst index feb1a36a65b7..b9fd131f4723 100644 --- a/Documentation/driver-api/usb/usb3-debug-port.rst +++ b/Documentation/driver-api/usb/usb3-debug-port.rst @@ -98,3 +98,55 @@ you to check the sanity of the setup. cat /dev/ttyUSB0 done ===== end of bash scripts =============== + +Serial TTY +========== + +The DbC support has been added to the xHCI driver. You can get a +debug device provided by the DbC at runtime. + +In order to use this, you need to make sure your kernel has been +configured to support USB_XHCI_DBGCAP. A sysfs attribute under +the xHCI device node is used to enable or disable DbC. By default, +DbC is disabled:: + + root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc + disabled + +Enable DbC with the following command:: + + root@target:/sys/bus/pci/devices/0000:00:14.0# echo enable > dbc + +You can check the DbC state at anytime:: + + root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc + enabled + +Connect the debug target to the debug host with a USB 3.0 super- +speed A-to-A debugging cable. You can see /dev/ttyDBC0 created +on the debug target. You will see below kernel message lines:: + + root@target: tail -f /var/log/kern.log + [ 182.730103] xhci_hcd 0000:00:14.0: DbC connected + [ 191.169420] xhci_hcd 0000:00:14.0: DbC configured + [ 191.169597] xhci_hcd 0000:00:14.0: DbC now attached to /dev/ttyDBC0 + +Accordingly, the DbC state has been brought up to:: + + root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc + configured + +On the debug host, you will see the debug device has been enumerated. +You will see below kernel message lines:: + + root@host: tail -f /var/log/kern.log + [ 79.454780] usb 2-2.1: new SuperSpeed USB device number 3 using xhci_hcd + [ 79.475003] usb 2-2.1: LPM exit latency is zeroed, disabling LPM. + [ 79.475389] usb 2-2.1: New USB device found, idVendor=1d6b, idProduct=0010 + [ 79.475390] usb 2-2.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3 + [ 79.475391] usb 2-2.1: Product: Linux USB Debug Target + [ 79.475392] usb 2-2.1: Manufacturer: Linux Foundation + [ 79.475393] usb 2-2.1: SerialNumber: 0001 + +The debug device works now. You can use any communication or debugging +program to talk between the host and the target. diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst index 69f077dcdb78..4fe1c06b6a13 100644 --- a/Documentation/driver-api/usb/writing_usb_driver.rst +++ b/Documentation/driver-api/usb/writing_usb_driver.rst @@ -321,6 +321,6 @@ linux-usb-devel Mailing List Archives: http://marc.theaimsgroup.com/?l=linux-usb-devel Programming Guide for Linux USB Device Drivers: -http://usb.cs.tum.edu/usbdoc +http://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf USB Home Page: http://www.usb.org diff --git a/Documentation/filesystems/vfat.txt b/Documentation/filesystems/vfat.txt index cf51360e3a9f..91031298beb1 100644 --- a/Documentation/filesystems/vfat.txt +++ b/Documentation/filesystems/vfat.txt @@ -344,4 +344,4 @@ the following: characters in the final slot are set to Unicode 0xFFFF. Finally, note that the extended name is stored in Unicode. Each Unicode -character takes two bytes. +character takes either two or four bytes, UTF-16LE encoded. diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface index 5ff19447ac44..d04e6e4964ee 100644 --- a/Documentation/i2c/dev-interface +++ b/Documentation/i2c/dev-interface @@ -17,13 +17,16 @@ i2c-10, ...). All 256 minor device numbers are reserved for i2c. C example ========= -So let's say you want to access an i2c adapter from a C program. The -first thing to do is "#include <linux/i2c-dev.h>". Please note that -there are two files named "i2c-dev.h" out there, one is distributed -with the Linux kernel and is meant to be included from kernel -driver code, the other one is distributed with i2c-tools and is -meant to be included from user-space programs. You obviously want -the second one here. +So let's say you want to access an i2c adapter from a C program. +First, you need to include these two headers: + + #include <linux/i2c-dev.h> + #include <i2c/smbus.h> + +(Please note that there are two files named "i2c-dev.h" out there. One is +distributed with the Linux kernel and the other one is included in the +source tree of i2c-tools. They used to be different in content but since 2012 +they're identical. You should use "linux/i2c-dev.h"). Now, you have to decide which adapter you want to access. You should inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this. diff --git a/Documentation/index.rst b/Documentation/index.rst index cb7f1ba5b3b1..a4fb34dddcf3 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -52,6 +52,7 @@ merged much easier. dev-tools/index doc-guide/index kernel-hacking/index + maintainer/index Kernel API documentation ------------------------ diff --git a/Documentation/kbuild/kconfig-language.txt b/Documentation/kbuild/kconfig-language.txt index 262722d8867b..688e41ebb4da 100644 --- a/Documentation/kbuild/kconfig-language.txt +++ b/Documentation/kbuild/kconfig-language.txt @@ -77,6 +77,27 @@ applicable everywhere (see syntax). Optionally, dependencies only for this default value can be added with "if". + The default value deliberately defaults to 'n' in order to avoid bloating the + build. With few exceptions, new config options should not change this. The + intent is for "make oldconfig" to add as little as possible to the config from + release to release. + + Note: + Things that merit "default y/m" include: + + a) A new Kconfig option for something that used to always be built + should be "default y". + + b) A new gatekeeping Kconfig option that hides/shows other Kconfig + options (but does not generate any code of its own), should be + "default y" so people will see those other options. + + c) Sub-driver behavior or similar options for a driver that is + "default n". This allows you to provide sane defaults. + + d) Hardware or infrastructure that everybody expects, such as CONFIG_NET + or CONFIG_BLOCK. These are rare exceptions. + - type definition + default value: "def_bool"/"def_tristate" <expr> ["if" <expr>] This is a shorthand notation for a type definition plus a value. diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt deleted file mode 100644 index c23e2c5ab80d..000000000000 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ /dev/null @@ -1,322 +0,0 @@ -NOTE: this document is outdated and will eventually be removed. See -Documentation/doc-guide/ for current information. - -kernel-doc nano-HOWTO -===================== - -How to format kernel-doc comments ---------------------------------- - -In order to provide embedded, 'C' friendly, easy to maintain, -but consistent and extractable documentation of the functions and -data structures in the Linux kernel, the Linux kernel has adopted -a consistent style for documenting functions and their parameters, -and structures and their members. - -The format for this documentation is called the kernel-doc format. -It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file. - -This style embeds the documentation within the source files, using -a few simple conventions. The scripts/kernel-doc perl script, the -Documentation/sphinx/kerneldoc.py Sphinx extension and other tools understand -these conventions, and are used to extract this embedded documentation -into various documents. - -In order to provide good documentation of kernel functions and data -structures, please use the following conventions to format your -kernel-doc comments in Linux kernel source. - -We definitely need kernel-doc formatted documentation for functions -that are exported to loadable modules using EXPORT_SYMBOL. - -We also look to provide kernel-doc formatted documentation for -functions externally visible to other kernel files (not marked -"static"). - -We also recommend providing kernel-doc formatted documentation -for private (file "static") routines, for consistency of kernel -source code layout. But this is lower priority and at the -discretion of the MAINTAINER of that kernel source file. - -Data structures visible in kernel include files should also be -documented using kernel-doc formatted comments. - -The opening comment mark "/**" is reserved for kernel-doc comments. -Only comments so marked will be considered by the kernel-doc scripts, -and any comment so marked must be in kernel-doc format. Do not use -"/**" to be begin a comment block unless the comment block contains -kernel-doc formatted comments. The closing comment marker for -kernel-doc comments can be either "*/" or "**/", but "*/" is -preferred in the Linux kernel tree. - -Kernel-doc comments should be placed just before the function -or data structure being described. - -Example kernel-doc function comment: - -/** - * foobar() - short function description of foobar - * @arg1: Describe the first argument to foobar. - * @arg2: Describe the second argument to foobar. - * One can provide multiple line descriptions - * for arguments. - * - * A longer description, with more discussion of the function foobar() - * that might be useful to those using or modifying it. Begins with - * empty comment line, and may include additional embedded empty - * comment lines. - * - * The longer description can have multiple paragraphs. - * - * Return: Describe the return value of foobar. - */ - -The short description following the subject can span multiple lines -and ends with an @argument description, an empty line or the end of -the comment block. - -The @argument descriptions must begin on the very next line following -this opening short function description line, with no intervening -empty comment lines. - -If a function parameter is "..." (varargs), it should be listed in -kernel-doc notation as: - * @...: description - -The return value, if any, should be described in a dedicated section -named "Return". - -Example kernel-doc data structure comment. - -/** - * struct blah - the basic blah structure - * @mem1: describe the first member of struct blah - * @mem2: describe the second member of struct blah, - * perhaps with more lines and words. - * - * Longer description of this structure. - */ - -The kernel-doc function comments describe each parameter to the -function, in order, with the @name lines. - -The kernel-doc data structure comments describe each structure member -in the data structure, with the @name lines. - -The longer description formatting is "reflowed", losing your line -breaks. So presenting carefully formatted lists within these -descriptions won't work so well; derived documentation will lose -the formatting. - -See the section below "How to add extractable documentation to your -source files" for more details and notes on how to format kernel-doc -comments. - -Components of the kernel-doc system ------------------------------------ - -Many places in the source tree have extractable documentation in the -form of block comments above functions. The components of this system -are: - -- scripts/kernel-doc - - This is a perl script that hunts for the block comments and can mark - them up directly into DocBook, ReST, man, text, and HTML. (No, not - texinfo.) - -- scripts/docproc.c - - This is a program for converting SGML template files into SGML - files. When a file is referenced it is searched for symbols - exported (EXPORT_SYMBOL), to be able to distinguish between internal - and external functions. - It invokes kernel-doc, giving it the list of functions that - are to be documented. - Additionally it is used to scan the SGML template files to locate - all the files referenced herein. This is used to generate dependency - information as used by make. - -- Makefile - - The targets 'xmldocs', 'latexdocs', 'pdfdocs', 'epubdocs'and 'htmldocs' - are used to build XML DocBook files, LaTeX files, PDF files, - ePub files and html files in Documentation/. - -How to extract the documentation --------------------------------- - -If you just want to read the ready-made books on the various -subsystems, just type 'make epubdocs', or 'make pdfdocs', or 'make htmldocs', -depending on your preference. If you would rather read a different format, -you can type 'make xmldocs' and then use DocBook tools to convert -Documentation/output/*.xml to a format of your choice (for example, -'db2html ...' if 'make htmldocs' was not defined). - -If you want to see man pages instead, you can do this: - -$ cd linux -$ scripts/kernel-doc -man $(find -name '*.c') | split-man.pl /tmp/man -$ scripts/kernel-doc -man $(find -name '*.h') | split-man.pl /tmp/man - -Here is split-man.pl: - ---> -#!/usr/bin/perl - -if ($#ARGV < 0) { - die "where do I put the results?\n"; -} - -mkdir $ARGV[0],0777; -$state = 0; -while (<STDIN>) { - if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) { - if ($state == 1) { close OUT } - $state = 1; - $fn = "$ARGV[0]/$1.9"; - print STDERR "Creating $fn\n"; - open OUT, ">$fn" or die "can't open $fn: $!\n"; - print OUT $_; - } elsif ($state != 0) { - print OUT $_; - } -} - -close OUT; -<-- - -If you just want to view the documentation for one function in one -file, you can do this: - -$ scripts/kernel-doc -man -function fn file | nroff -man | less - -or this: - -$ scripts/kernel-doc -text -function fn file - - -How to add extractable documentation to your source files ---------------------------------------------------------- - -The format of the block comment is like this: - -/** - * function_name(:)? (- short description)? -(* @parameterx(space)*: (description of parameter x)?)* -(* a blank line)? - * (Description:)? (Description of function)? - * (section header: (section description)? )* -(*)?*/ - -All "description" text can span multiple lines, although the -function_name & its short description are traditionally on a single line. -Description text may also contain blank lines (i.e., lines that contain -only a "*"). - -"section header:" names must be unique per function (or struct, -union, typedef, enum). - -Use the section header "Return" for sections describing the return value -of a function. - -Avoid putting a spurious blank line after the function name, or else the -description will be repeated! - -All descriptive text is further processed, scanning for the following special -patterns, which are highlighted appropriately. - -'funcname()' - function -'$ENVVAR' - environment variable -'&struct_name' - name of a structure (up to two words including 'struct') -'@parameter' - name of a parameter -'%CONST' - name of a constant. - -NOTE 1: The multi-line descriptive text you provide does *not* recognize -line breaks, so if you try to format some text nicely, as in: - - Return: - 0 - cool - 1 - invalid arg - 2 - out of memory - -this will all run together and produce: - - Return: 0 - cool 1 - invalid arg 2 - out of memory - -NOTE 2: If the descriptive text you provide has lines that begin with -some phrase followed by a colon, each of those phrases will be taken as -a new section heading, which means you should similarly try to avoid text -like: - - Return: - 0: cool - 1: invalid arg - 2: out of memory - -every line of which would start a new section. Again, probably not -what you were after. - -Take a look around the source tree for examples. - - -kernel-doc for structs, unions, enums, and typedefs ---------------------------------------------------- - -Beside functions you can also write documentation for structs, unions, -enums and typedefs. Instead of the function name you must write the name -of the declaration; the struct/union/enum/typedef must always precede -the name. Nesting of declarations is not supported. -Use the argument mechanism to document members or constants. - -Inside a struct description, you can use the "private:" and "public:" -comment tags. Structure fields that are inside a "private:" area -are not listed in the generated output documentation. The "private:" -and "public:" tags must begin immediately following a "/*" comment -marker. They may optionally include comments between the ":" and the -ending "*/" marker. - -Example: - -/** - * struct my_struct - short description - * @a: first member - * @b: second member - * - * Longer description - */ -struct my_struct { - int a; - int b; -/* private: internal use only */ - int c; -}; - - -Including documentation blocks in source files ----------------------------------------------- - -To facilitate having source code and comments close together, you can -include kernel-doc documentation blocks that are free-form comments -instead of being kernel-doc for functions, structures, unions, -enums, or typedefs. This could be used for something like a -theory of operation for a driver or library code, for example. - -This is done by using a DOC: section keyword with a section title. E.g.: - -/** - * DOC: Theory of Operation - * - * The whizbang foobar is a dilly of a gizmo. It can do whatever you - * want it to do, at any time. It reads your mind. Here's how it works. - * - * foo bar splat - * - * The only drawback to this gizmo is that is can sometimes damage - * hardware, software, or its subject(s). - */ - -DOC: sections are used in ReST files. - -Tim. -*/ <twaugh@redhat.com> diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst index daf3883b2694..5192d7f78eca 100644 --- a/Documentation/kernel-hacking/hacking.rst +++ b/Documentation/kernel-hacking/hacking.rst @@ -523,7 +523,7 @@ this expression is true, or ``-ERESTARTSYS`` if a signal is received. The Waking Up Queued Tasks ---------------------- -Call :c:func:`wake_up()` (``include/linux/wait.h``);, which will wake +Call :c:func:`wake_up()` (``include/linux/wait.h``), which will wake up every process in the queue. The exception is if one has ``TASK_EXCLUSIVE`` set, in which case the remainder of the queue will not be woken. There are other variants of this basic function available diff --git a/Documentation/maintainer/conf.py b/Documentation/maintainer/conf.py new file mode 100644 index 000000000000..81e9eb7a7884 --- /dev/null +++ b/Documentation/maintainer/conf.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8; mode: python -*- + +project = 'Linux Kernel Development Documentation' + +tags.add("subproject") + +latex_documents = [ + ('index', 'maintainer.tex', 'Linux Kernel Development Documentation', + 'The kernel development community', 'manual'), +] diff --git a/Documentation/maintainer/configure-git.rst b/Documentation/maintainer/configure-git.rst new file mode 100644 index 000000000000..78bbbb0d2c84 --- /dev/null +++ b/Documentation/maintainer/configure-git.rst @@ -0,0 +1,34 @@ +.. _configuregit: + +Configure Git +============= + +This chapter describes maintainer level git configuration. + +Tagged branches used in :ref:`Documentation/maintainer/pull-requests.rst +<pullrequests>` should be signed with the developers public GPG key. Signed +tags can be created by passing the ``-u`` flag to ``git tag``. However, +since you would *usually* use the same key for the same project, you can +set it once with +:: + + git config user.signingkey "keyname" + +Alternatively, edit your ``.git/config`` or ``~/.gitconfig`` file by hand: +:: + + [user] + name = Jane Developer + email = jd@domain.org + signingkey = jd@domain.org + +You may need to tell ``git`` to use ``gpg2`` +:: + + [gpg] + program = /path/to/gpg2 + +You may also like to tell ``gpg`` which ``tty`` to use (add to your shell rc file) +:: + + export GPG_TTY=$(tty) diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst new file mode 100644 index 000000000000..2a14916930cb --- /dev/null +++ b/Documentation/maintainer/index.rst @@ -0,0 +1,14 @@ +========================== +Kernel Maintainer Handbook +========================== + +This document is the humble beginning of a manual for kernel maintainers. +There is a lot yet to go here! Please feel free to propose (and write) +additions to this manual. + +.. toctree:: + :maxdepth: 2 + + configure-git + pull-requests + diff --git a/Documentation/maintainer/pull-requests.rst b/Documentation/maintainer/pull-requests.rst new file mode 100644 index 000000000000..a19db3458b56 --- /dev/null +++ b/Documentation/maintainer/pull-requests.rst @@ -0,0 +1,178 @@ +.. _pullrequests: + +Creating Pull Requests +====================== + +This chapter describes how maintainers can create and submit pull requests +to other maintainers. This is useful for transferring changes from one +maintainers tree to another maintainers tree. + +This document was written by Tobin C. Harding (who at that time, was not an +experienced maintainer) primarily from comments made by Greg Kroah-Hartman +and Linus Torvalds on LKML. Suggestions and fixes by Jonathan Corbet and +Mauro Carvalho Chehab. Misrepresentation was unintentional but inevitable, +please direct abuse to Tobin C. Harding <me@tobin.cc>. + +Original email thread:: + + http://lkml.kernel.org/r/20171114110500.GA21175@kroah.com + + +Create Branch +------------- + +To start with you will need to have all the changes you wish to include in +the pull request on a separate branch. Typically you will base this branch +off of a branch in the developers tree whom you intend to send the pull +request to. + +In order to create the pull request you must first tag the branch that you +have just created. It is recommended that you choose a meaningful tag name, +in a way that you and others can understand, even after some time. A good +practice is to include in the name an indicator of the sybsystem of origin +and the target kernel version. + +Greg offers the following. A pull request with miscellaneous stuff for +drivers/char, to be applied at the Kernel version 4.15-rc1 could be named +as ``char-misc-4.15-rc1``. If such tag would be produced from a branch +named ``char-misc-next``, you would be using the following command:: + + git tag -s char-misc-4.15-rc1 char-misc-next + +that will create a signed tag called ``char-misc-4.15-rc1`` based on the +last commit in the ``char-misc-next`` branch, and sign it with your gpg key +(see :ref:`Documentation/maintainer/configure_git.rst <configuregit>`). + +Linus will only accept pull requests based on a signed tag. Other +maintainers may differ. + +When you run the above command ``git`` will drop you into an editor and ask +you to describe the tag. In this case, you are describing a pull request, +so outline what is contained here, why it should be merged, and what, if +any, testing has been done. All of this information will end up in the tag +itself, and then in the merge commit that the maintainer makes if/when they +merge the pull request. So write it up well, as it will be in the kernel +tree for forever. + +As said by Linus:: + + Anyway, at least to me, the important part is the *message*. I want + to understand what I'm pulling, and why I should pull it. I also + want to use that message as the message for the merge, so it should + not just make sense to me, but make sense as a historical record + too. + + Note that if there is something odd about the pull request, that + should very much be in the explanation. If you're touching files + that you don't maintain, explain _why_. I will see it in the + diffstat anyway, and if you didn't mention it, I'll just be extra + suspicious. And when you send me new stuff after the merge window + (or even bug-fixes, but ones that look scary), explain not just + what they do and why they do it, but explain the _timing_. What + happened that this didn't go through the merge window.. + + I will take both what you write in the email pull request _and_ in + the signed tag, so depending on your workflow, you can either + describe your work in the signed tag (which will also automatically + make it into the pull request email), or you can make the signed + tag just a placeholder with nothing interesting in it, and describe + the work later when you actually send me the pull request. + + And yes, I will edit the message. Partly because I tend to do just + trivial formatting (the whole indentation and quoting etc), but + partly because part of the message may make sense for me at pull + time (describing the conflicts and your personal issues for sending + it right now), but may not make sense in the context of a merge + commit message, so I will try to make it all make sense. I will + also fix any speeling mistaeks and bad grammar I notice, + particularly for non-native speakers (but also for native ones + ;^). But I may miss some, or even add some. + + Linus + +Greg gives, as an example pull request:: + + Char/Misc patches for 4.15-rc1 + + Here is the big char/misc patch set for the 4.15-rc1 merge window. + Contained in here is the normal set of new functions added to all + of these crazy drivers, as well as the following brand new + subsystems: + - time_travel_controller: Finally a set of drivers for the + latest time travel bus architecture that provides i/o to + the CPU before it asked for it, allowing uninterrupted + processing + - relativity_shifters: due to the affect that the + time_travel_controllers have on the overall system, there + was a need for a new set of relativity shifter drivers to + accommodate the newly formed black holes that would + threaten to suck CPUs into them. This subsystem handles + this in a way to successfully neutralize the problems. + There is a Kconfig option to force these to be enabled + when needed, so problems should not occur. + + All of these patches have been successfully tested in the latest + linux-next releases, and the original problems that it found have + all been resolved (apologies to anyone living near Canberra for the + lack of the Kconfig options in the earlier versions of the + linux-next tree creations.) + + Signed-off-by: Your-name-here <your_email@domain> + + +The tag message format is just like a git commit id. One line at the top +for a "summary subject" and be sure to sign-off at the bottom. + +Now that you have a local signed tag, you need to push it up to where it +can be retrieved:: + + git push origin char-misc-4.15-rc1 + + +Create Pull Request +------------------- + +The last thing to do is create the pull request message. ``git`` handily +will do this for you with the ``git request-pull`` command, but it needs a +bit of help determining what you want to pull, and on what to base the pull +against (to show the correct changes to be pulled and the diffstat). The +following command(s) will generate a pull request:: + + git request-pull master git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc.git/ char-misc-4.15-rc1 + +Quoting Greg:: + + This is asking git to compare the difference from the + 'char-misc-4.15-rc1' tag location, to the head of the 'master' + branch (which in my case points to the last location in Linus's + tree that I diverged from, usually a -rc release) and to use the + git:// protocol to pull from. If you wish to use https://, that + can be used here instead as well (but note that some people behind + firewalls will have problems with https git pulls). + + If the char-misc-4.15-rc1 tag is not present in the repo that I am + asking to be pulled from, git will complain saying it is not there, + a handy way to remember to actually push it to a public location. + + The output of 'git request-pull' will contain the location of the + git tree and specific tag to pull from, and the full text + description of that tag (which is why you need to provide good + information in that tag). It will also create a diffstat of the + pull request, and a shortlog of the individual commits that the + pull request will provide. + +Linus responded that he tends to prefer the ``git://`` protocol. Other +maintainers may have different preferences. Also, note that if you are +creating pull requests without a signed tag then ``https://`` may be a +better choice. Please see the original thread for the full discussion. + + +Submit Pull Request +------------------- + +A pull request is submitted in the same way as an ordinary patch. Send as +inline email to the maintainer and CC LKML and any sub-system specific +lists if required. Pull requests to Linus typically have a subject line +something like:: + + [GIT PULL] <subsystem> changes for v4.15-rc1 diff --git a/Documentation/process/kernel-enforcement-statement.rst b/Documentation/process/kernel-enforcement-statement.rst index b3170671a1df..a0db6e40fb80 100644 --- a/Documentation/process/kernel-enforcement-statement.rst +++ b/Documentation/process/kernel-enforcement-statement.rst @@ -68,6 +68,7 @@ we might work for today, have in the past, or will in the future. - Paul Burton - Javier Martinez Canillas - Rob Clark + - Kees Cook (Google) - Jonathan Corbet - Dennis Dalessandro - Vivien Didelot (Savoir-faire Linux) @@ -136,6 +137,7 @@ we might work for today, have in the past, or will in the future. - Anna Schumaker - Jes Sorensen - K.Y. Srinivasan + - David Sterba (SUSE) - Heiko Stuebner - Jiri Kosina (SUSE) - Willy Tarreau @@ -143,6 +145,7 @@ we might work for today, have in the past, or will in the future. - Linus Torvalds - Thierry Reding - Rik van Riel + - Luis R. Rodriguez - Geert Uytterhoeven (Glider bvba) - Eduardo Valentin (Amazon.com) - Daniel Vetter diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index a0d9d34bfb6d..367353c54949 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -37,7 +37,9 @@ and elsewhere regarding submitting Linux kernel patches. You should be able to justify all violations that remain in your patch. -6) Any new or modified ``CONFIG`` options don't muck up the config menu. +6) Any new or modified ``CONFIG`` options do not muck up the config menu and + default to off unless they meet the exception criteria documented in + ``Documentation/kbuild/kconfig-language.txt`` Menu attributes: default value. 7) All new ``Kconfig`` options have help text. diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt index 6338400eed73..2c31d9ee6776 100644 --- a/Documentation/scsi/scsi_mid_low_api.txt +++ b/Documentation/scsi/scsi_mid_low_api.txt @@ -319,12 +319,12 @@ struct Scsi_Host: instance. If the reference count reaches 0 then the given instance is freed -The Scsi_device structure has had reference counting infrastructure added. -This effectively spreads the ownership of struct Scsi_device instances +The scsi_device structure has had reference counting infrastructure added. +This effectively spreads the ownership of struct scsi_device instances across the various SCSI layers which use them. Previously such instances were exclusively owned by the mid level. See the access functions declared towards the end of include/scsi/scsi_device.h . If an LLD wants to keep -a copy of a pointer to a Scsi_device instance it should use scsi_device_get() +a copy of a pointer to a scsi_device instance it should use scsi_device_get() to bump its reference count. When it is finished with the pointer it can use scsi_device_put() to decrement its reference count (and potentially delete it). diff --git a/Documentation/security/self-protection.rst b/Documentation/security/self-protection.rst index 60c8bd8b77bf..0f53826c78b9 100644 --- a/Documentation/security/self-protection.rst +++ b/Documentation/security/self-protection.rst @@ -270,6 +270,21 @@ attacks, it is important to defend against exposure of both kernel memory addresses and kernel memory contents (since they may contain kernel addresses or other sensitive things like canary values). +Kernel addresses +---------------- + +Printing kernel addresses to userspace leaks sensitive information about +the kernel memory layout. Care should be exercised when using any printk +specifier that prints the raw address, currently %px, %p[ad], (and %p[sSb] +in certain circumstances [*]). Any file written to using one of these +specifiers should be readable only by privileged processes. + +Kernels 4.14 and older printed the raw address using %p. As of 4.15-rc1 +addresses printed with the specifier %p are hashed before printing. + +[*] If KALLSYMS is enabled and symbol lookup fails, the raw address is +printed. If KALLSYMS is not enabled the raw address is printed. + Unique identifiers ------------------ diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index 694968c7523c..412314eebda6 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -34,6 +34,7 @@ show up in /proc/sys/kernel: - hostname - hotplug - hardlockup_all_cpu_backtrace +- hardlockup_panic - hung_task_panic - hung_task_check_count - hung_task_timeout_secs @@ -313,6 +314,19 @@ will be initiated. 1: on detection capture more debug information. ============================================================== +hardlockup_panic: + +This parameter can be used to control whether the kernel panics +when a hard lockup is detected. + + 0 - don't panic on hard lockup + 1 - panic on hard lockup + +See Documentation/lockup-watchdogs.txt for more information. This can +also be set using the nmi_watchdog kernel parameter. + +============================================================== + hotplug: Path for the hotplug policy agent. @@ -377,7 +391,8 @@ kptr_restrict: This toggle indicates whether restrictions are placed on exposing kernel addresses via /proc and other interfaces. -When kptr_restrict is set to (0), the default, there are no restrictions. +When kptr_restrict is set to 0 (the default) the address is hashed before +printing. (This is the equivalent to %p.) When kptr_restrict is set to (1), kernel pointers printed using the %pK format specifier will be replaced with 0's unless the user has CAP_SYSLOG diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt index b920423f88cb..5025ff9307e6 100644 --- a/Documentation/sysctl/vm.txt +++ b/Documentation/sysctl/vm.txt @@ -158,10 +158,6 @@ Note: the minimum value allowed for dirty_bytes is two pages (in bytes); any value lower than this limit will be ignored and the old configuration will be retained. -Note: the value of dirty_bytes also must be set greater than -dirty_background_bytes or the amount of memory corresponding to -dirty_background_ratio. - ============================================================== dirty_expire_centisecs @@ -181,9 +177,6 @@ generating disk writes will itself start writing out dirty data. The total available memory is not equal to total system memory. -Note: dirty_ratio must be set greater than dirty_background_ratio or -ratio corresponding to dirty_background_bytes. - ============================================================== dirty_writeback_centisecs diff --git a/Documentation/trace/ftrace-uses.rst b/Documentation/trace/ftrace-uses.rst index 8494a801d341..3aed560a12ee 100644 --- a/Documentation/trace/ftrace-uses.rst +++ b/Documentation/trace/ftrace-uses.rst @@ -42,9 +42,9 @@ as well as what protections the callback will perform and not require ftrace to handle. There is only one field that is needed to be set when registering -an ftrace_ops with ftrace:: +an ftrace_ops with ftrace: -.. code-block: c +.. code-block:: c struct ftrace_ops ops = { .func = my_callback_func, @@ -81,12 +81,12 @@ may take some time to finish. The callback function ===================== -The prototype of the callback function is as follows (as of v4.14):: +The prototype of the callback function is as follows (as of v4.14): -.. code-block: c +.. code-block:: c - void callback_func(unsigned long ip, unsigned long parent_ip, - struct ftrace_ops *op, struct pt_regs *regs); + void callback_func(unsigned long ip, unsigned long parent_ip, + struct ftrace_ops *op, struct pt_regs *regs); @ip This is the instruction pointer of the function that is being traced. @@ -176,10 +176,10 @@ Filtering which functions to trace If a callback is only to be called from specific functions, a filter must be set up. The filters are added by name, or ip if it is known. -.. code-block: c +.. code-block:: c - int ftrace_set_filter(struct ftrace_ops *ops, unsigned char *buf, - int len, int reset); + int ftrace_set_filter(struct ftrace_ops *ops, unsigned char *buf, + int len, int reset); @ops The ops to set the filter with @@ -202,9 +202,9 @@ See Filter Commands in :file:`Documentation/trace/ftrace.txt`. To just trace the schedule function:: -.. code-block: c +.. code-block:: c - ret = ftrace_set_filter(&ops, "schedule", strlen("schedule"), 0); + ret = ftrace_set_filter(&ops, "schedule", strlen("schedule"), 0); To add more functions, call the ftrace_set_filter() more than once with the @reset parameter set to zero. To remove the current filter set and replace it @@ -212,17 +212,17 @@ with new functions defined by @buf, have @reset be non-zero. To remove all the filtered functions and trace all functions:: -.. code-block: c +.. code-block:: c - ret = ftrace_set_filter(&ops, NULL, 0, 1); + ret = ftrace_set_filter(&ops, NULL, 0, 1); Sometimes more than one function has the same name. To trace just a specific function in this case, ftrace_set_filter_ip() can be used. -.. code-block: c +.. code-block:: c - ret = ftrace_set_filter_ip(&ops, ip, 0, 0); + ret = ftrace_set_filter_ip(&ops, ip, 0, 0); Although the ip must be the address where the call to fentry or mcount is located in the function. This function is used by perf and kprobes that @@ -237,10 +237,10 @@ be called by any function. An empty "notrace" list means to allow all functions defined by the filter to be traced. -.. code-block: c +.. code-block:: c - int ftrace_set_notrace(struct ftrace_ops *ops, unsigned char *buf, - int len, int reset); + int ftrace_set_notrace(struct ftrace_ops *ops, unsigned char *buf, + int len, int reset); This takes the same parameters as ftrace_set_filter() but will add the functions it finds to not be traced. This is a separate list from the @@ -251,7 +251,7 @@ that match @buf to it. Clearing the "notrace" list is the same as clearing the filter list -.. code-block: c +.. code-block:: c ret = ftrace_set_notrace(&ops, NULL, 0, 1); @@ -264,29 +264,29 @@ If a filter is in place, and the @reset is non-zero, and @buf contains a matching glob to functions, the switch will happen during the time of the ftrace_set_filter() call. At no time will all functions call the callback. -.. code-block: c +.. code-block:: c - ftrace_set_filter(&ops, "schedule", strlen("schedule"), 1); + ftrace_set_filter(&ops, "schedule", strlen("schedule"), 1); - register_ftrace_function(&ops); + register_ftrace_function(&ops); - msleep(10); + msleep(10); - ftrace_set_filter(&ops, "try_to_wake_up", strlen("try_to_wake_up"), 1); + ftrace_set_filter(&ops, "try_to_wake_up", strlen("try_to_wake_up"), 1); is not the same as: -.. code-block: c +.. code-block:: c - ftrace_set_filter(&ops, "schedule", strlen("schedule"), 1); + ftrace_set_filter(&ops, "schedule", strlen("schedule"), 1); - register_ftrace_function(&ops); + register_ftrace_function(&ops); - msleep(10); + msleep(10); - ftrace_set_filter(&ops, NULL, 0, 1); + ftrace_set_filter(&ops, NULL, 0, 1); - ftrace_set_filter(&ops, "try_to_wake_up", strlen("try_to_wake_up"), 0); + ftrace_set_filter(&ops, "try_to_wake_up", strlen("try_to_wake_up"), 0); As the latter will have a short time where all functions will call the callback, between the time of the reset, and the time of the diff --git a/Documentation/usb/chipidea.txt b/Documentation/usb/chipidea.txt index edf7cdfddc88..d1eedc01b00a 100644 --- a/Documentation/usb/chipidea.txt +++ b/Documentation/usb/chipidea.txt @@ -23,13 +23,13 @@ cat /sys/kernel/debug/ci_hdrc.0/registers 2) Connect 2 boards with usb cable with one end is micro A plug, the other end is micro B plug. - The A-device(with micro A plug inserted) should enumrate B-device. + The A-device(with micro A plug inserted) should enumerate B-device. 3) Role switch On B-device: echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req - B-device should take host role and enumrate A-device. + B-device should take host role and enumerate A-device. 4) A-device switch back to host. On B-device: @@ -40,13 +40,13 @@ cat /sys/kernel/debug/ci_hdrc.0/registers side by answering the polling from B-Host, this can be done on A-device: echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req - A-device should switch back to host and enumrate B-device. + A-device should switch back to host and enumerate B-device. 5) Remove B-device(unplug micro B plug) and insert again in 10 seconds, - A-device should enumrate B-device again. + A-device should enumerate B-device again. 6) Remove B-device(unplug micro B plug) and insert again after 10 seconds, - A-device should NOT enumrate B-device. + A-device should NOT enumerate B-device. if A-device wants to use bus: On A-device: @@ -67,7 +67,7 @@ cat /sys/kernel/debug/ci_hdrc.0/registers On B-device: echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req - A-device should resume usb bus and enumrate B-device. + A-device should resume usb bus and enumerate B-device. 1.3 Reference document ---------------------- diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt index f670e4b9e7f3..57d3ee9e4bde 100644 --- a/Documentation/virtual/kvm/api.txt +++ b/Documentation/virtual/kvm/api.txt @@ -2901,14 +2901,19 @@ userspace buffer and its length: struct kvm_s390_irq_state { __u64 buf; - __u32 flags; + __u32 flags; /* will stay unused for compatibility reasons */ __u32 len; - __u32 reserved[4]; + __u32 reserved[4]; /* will stay unused for compatibility reasons */ }; Userspace passes in the above struct and for each pending interrupt a struct kvm_s390_irq is copied to the provided buffer. +The structure contains a flags and a reserved field for future extensions. As +the kernel never checked for flags == 0 and QEMU never pre-zeroed flags and +reserved, these fields can not be used in the future without breaking +compatibility. + If -ENOBUFS is returned the buffer provided was too small and userspace may retry with a bigger buffer. @@ -2932,10 +2937,14 @@ containing a struct kvm_s390_irq_state: struct kvm_s390_irq_state { __u64 buf; + __u32 flags; /* will stay unused for compatibility reasons */ __u32 len; - __u32 pad; + __u32 reserved[4]; /* will stay unused for compatibility reasons */ }; +The restrictions for flags and reserved apply as well. +(see KVM_S390_GET_IRQ_STATE) + The userspace memory referenced by buf contains a struct kvm_s390_irq for each interrupt to be injected into the guest. If one of the interrupts could not be injected for some reason the diff --git a/Documentation/w1/w1.generic b/Documentation/w1/w1.generic index b3ffaf8cfab2..c51b1ab012d0 100644 --- a/Documentation/w1/w1.generic +++ b/Documentation/w1/w1.generic @@ -76,7 +76,7 @@ See struct w1_bus_master definition in w1.h for details. w1 master sysfs interface ------------------------------------------------------------------ -<xx-xxxxxxxxxxxxx> - A directory for a found device. The format is family-serial +<xx-xxxxxxxxxxxx> - A directory for a found device. The format is family-serial bus - (standard) symlink to the w1 bus driver - (standard) symlink to the w1 driver w1_master_add - (rw) manually register a slave device |