diff options
Diffstat (limited to 'Documentation/core-api')
| -rw-r--r-- | Documentation/core-api/cachetlb.rst | 86 | ||||
| -rw-r--r-- | Documentation/core-api/cpu_hotplug.rst | 40 | ||||
| -rw-r--r-- | Documentation/core-api/irq/irq-domain.rst | 28 | ||||
| -rw-r--r-- | Documentation/core-api/printk-basics.rst | 5 | ||||
| -rw-r--r-- | Documentation/core-api/printk-formats.rst | 1 |
5 files changed, 89 insertions, 71 deletions
diff --git a/Documentation/core-api/cachetlb.rst b/Documentation/core-api/cachetlb.rst index fe4290e26729..8aed9103e48a 100644 --- a/Documentation/core-api/cachetlb.rst +++ b/Documentation/core-api/cachetlb.rst @@ -271,10 +271,15 @@ maps this page at its virtual address. ``void flush_dcache_page(struct page *page)`` - Any time the kernel writes to a page cache page, _OR_ - the kernel is about to read from a page cache page and - user space shared/writable mappings of this page potentially - exist, this routine is called. + This routines must be called when: + + a) the kernel did write to a page that is in the page cache page + and / or in high memory + b) the kernel is about to read from a page cache page and user space + shared/writable mappings of this page potentially exist. Note + that {get,pin}_user_pages{_fast} already call flush_dcache_page + on any page found in the user address space and thus driver + code rarely needs to take this into account. .. note:: @@ -284,38 +289,34 @@ maps this page at its virtual address. handling vfs symlinks in the page cache need not call this interface at all. - The phrase "kernel writes to a page cache page" means, - specifically, that the kernel executes store instructions - that dirty data in that page at the page->virtual mapping - of that page. It is important to flush here to handle - D-cache aliasing, to make sure these kernel stores are - visible to user space mappings of that page. - - The corollary case is just as important, if there are users - which have shared+writable mappings of this file, we must make - sure that kernel reads of these pages will see the most recent - stores done by the user. - - If D-cache aliasing is not an issue, this routine may - simply be defined as a nop on that architecture. - - There is a bit set aside in page->flags (PG_arch_1) as - "architecture private". The kernel guarantees that, - for pagecache pages, it will clear this bit when such - a page first enters the pagecache. - - This allows these interfaces to be implemented much more - efficiently. It allows one to "defer" (perhaps indefinitely) - the actual flush if there are currently no user processes - mapping this page. See sparc64's flush_dcache_page and - update_mmu_cache implementations for an example of how to go - about doing this. - - The idea is, first at flush_dcache_page() time, if - page->mapping->i_mmap is an empty tree, just mark the architecture - private page flag bit. Later, in update_mmu_cache(), a check is - made of this flag bit, and if set the flush is done and the flag - bit is cleared. + The phrase "kernel writes to a page cache page" means, specifically, + that the kernel executes store instructions that dirty data in that + page at the page->virtual mapping of that page. It is important to + flush here to handle D-cache aliasing, to make sure these kernel stores + are visible to user space mappings of that page. + + The corollary case is just as important, if there are users which have + shared+writable mappings of this file, we must make sure that kernel + reads of these pages will see the most recent stores done by the user. + + If D-cache aliasing is not an issue, this routine may simply be defined + as a nop on that architecture. + + There is a bit set aside in page->flags (PG_arch_1) as "architecture + private". The kernel guarantees that, for pagecache pages, it will + clear this bit when such a page first enters the pagecache. + + This allows these interfaces to be implemented much more efficiently. + It allows one to "defer" (perhaps indefinitely) the actual flush if + there are currently no user processes mapping this page. See sparc64's + flush_dcache_page and update_mmu_cache implementations for an example + of how to go about doing this. + + The idea is, first at flush_dcache_page() time, if page_file_mapping() + returns a mapping, and mapping_mapped on that mapping returns %false, + just mark the architecture private page flag bit. Later, in + update_mmu_cache(), a check is made of this flag bit, and if set the + flush is done and the flag bit is cleared. .. important:: @@ -351,19 +352,6 @@ maps this page at its virtual address. architectures). For incoherent architectures, it should flush the cache of the page at vmaddr. - ``void flush_kernel_dcache_page(struct page *page)`` - - When the kernel needs to modify a user page is has obtained - with kmap, it calls this function after all modifications are - complete (but before kunmapping it) to bring the underlying - page up to date. It is assumed here that the user has no - incoherent cached copies (i.e. the original page was obtained - from a mechanism like get_user_pages()). The default - implementation is a nop and should remain so on all coherent - architectures. On incoherent architectures, this should flush - the kernel cache for page (using page_address(page)). - - ``void flush_icache_range(unsigned long start, unsigned long end)`` When the kernel stores into addresses that it will execute diff --git a/Documentation/core-api/cpu_hotplug.rst b/Documentation/core-api/cpu_hotplug.rst index a2c96bec5ee8..b66e3cae1472 100644 --- a/Documentation/core-api/cpu_hotplug.rst +++ b/Documentation/core-api/cpu_hotplug.rst @@ -91,9 +91,10 @@ Never use anything other than ``cpumask_t`` to represent bitmap of CPUs. Using CPU hotplug ================= + The kernel option *CONFIG_HOTPLUG_CPU* needs to be enabled. It is currently available on multiple architectures including ARM, MIPS, PowerPC and X86. The -configuration is done via the sysfs interface: :: +configuration is done via the sysfs interface:: $ ls -lh /sys/devices/system/cpu total 0 @@ -113,14 +114,14 @@ configuration is done via the sysfs interface: :: The files *offline*, *online*, *possible*, *present* represent the CPU masks. Each CPU folder contains an *online* file which controls the logical on (1) and -off (0) state. To logically shutdown CPU4: :: +off (0) state. To logically shutdown CPU4:: $ echo 0 > /sys/devices/system/cpu/cpu4/online smpboot: CPU 4 is now offline Once the CPU is shutdown, it will be removed from */proc/interrupts*, */proc/cpuinfo* and should also not be shown visible by the *top* command. To -bring CPU4 back online: :: +bring CPU4 back online:: $ echo 1 > /sys/devices/system/cpu/cpu4/online smpboot: Booting Node 0 Processor 4 APIC 0x1 @@ -142,6 +143,7 @@ The CPU hotplug coordination The offline case ---------------- + Once a CPU has been logically shutdown the teardown callbacks of registered hotplug states will be invoked, starting with ``CPUHP_ONLINE`` and terminating at state ``CPUHP_OFFLINE``. This includes: @@ -158,9 +160,10 @@ at state ``CPUHP_OFFLINE``. This includes: Using the hotplug API --------------------- + It is possible to receive notifications once a CPU is offline or onlined. This might be important to certain drivers which need to perform some kind of setup -or clean up functions based on the number of available CPUs: :: +or clean up functions based on the number of available CPUs:: #include <linux/cpuhotplug.h> @@ -186,9 +189,10 @@ During the removal of a hotplug state the teardown callback will be invoked. Multiple instances ~~~~~~~~~~~~~~~~~~ + If a driver has multiple instances and each instance needs to perform the callback independently then it is likely that a ''multi-state'' should be used. -First a multi-state state needs to be registered: :: +First a multi-state state needs to be registered:: ret = cpuhp_setup_state_multi(CPUHP_AP_ONLINE_DYN, "X/Y:online, Y_online, Y_prepare_down); @@ -197,7 +201,7 @@ First a multi-state state needs to be registered: :: The ``cpuhp_setup_state_multi()`` behaves similar to ``cpuhp_setup_state()`` except it prepares the callbacks for a multi state and does not invoke the callbacks. This is a one time setup. -Once a new instance is allocated, you need to register this new instance: :: +Once a new instance is allocated, you need to register this new instance:: ret = cpuhp_state_add_instance(Y_hp_online, &d->node); @@ -206,7 +210,8 @@ This function will add this instance to your previously allocated (*Y_online*) on all online CPUs. The *node* element is a ``struct hlist_node`` member of your per-instance data structure. -On removal of the instance: :: +On removal of the instance:: + cpuhp_state_remove_instance(Y_hp_online, &d->node) should be invoked which will invoke the teardown callback on all online @@ -214,18 +219,20 @@ CPUs. Manual setup ~~~~~~~~~~~~ + Usually it is handy to invoke setup and teardown callbacks on registration or removal of a state because usually the operation needs to performed once a CPU goes online (offline) and during initial setup (shutdown) of the driver. However each registration and removal function is also available with a ``_nocalls`` suffix which does not invoke the provided callbacks if the invocation of the callbacks is not desired. During the manual setup (or teardown) the functions -``get_online_cpus()`` and ``put_online_cpus()`` should be used to inhibit CPU +``cpus_read_lock()`` and ``cpus_read_unlock()`` should be used to inhibit CPU hotplug operations. The ordering of the events -------------------------- + The hotplug states are defined in ``include/linux/cpuhotplug.h``: * The states *CPUHP_OFFLINE* … *CPUHP_AP_OFFLINE* are invoked before the @@ -248,13 +255,14 @@ another hotplug event. Testing of hotplug states ========================= + One way to verify whether a custom state is working as expected or not is to shutdown a CPU and then put it online again. It is also possible to put the CPU to certain state (for instance *CPUHP_AP_ONLINE*) and then go back to *CPUHP_ONLINE*. This would simulate an error one state after *CPUHP_AP_ONLINE* which would lead to rollback to the online state. -All registered states are enumerated in ``/sys/devices/system/cpu/hotplug/states``: :: +All registered states are enumerated in ``/sys/devices/system/cpu/hotplug/states`` :: $ tail /sys/devices/system/cpu/hotplug/states 138: mm/vmscan:online @@ -268,7 +276,7 @@ All registered states are enumerated in ``/sys/devices/system/cpu/hotplug/states 168: sched:active 169: online -To rollback CPU4 to ``lib/percpu_cnt:online`` and back online just issue: :: +To rollback CPU4 to ``lib/percpu_cnt:online`` and back online just issue:: $ cat /sys/devices/system/cpu/cpu4/hotplug/state 169 @@ -276,14 +284,14 @@ To rollback CPU4 to ``lib/percpu_cnt:online`` and back online just issue: :: $ cat /sys/devices/system/cpu/cpu4/hotplug/state 140 -It is important to note that the teardown callbac of state 140 have been -invoked. And now get back online: :: +It is important to note that the teardown callback of state 140 have been +invoked. And now get back online:: $ echo 169 > /sys/devices/system/cpu/cpu4/hotplug/target $ cat /sys/devices/system/cpu/cpu4/hotplug/state 169 -With trace events enabled, the individual steps are visible, too: :: +With trace events enabled, the individual steps are visible, too:: # TASK-PID CPU# TIMESTAMP FUNCTION # | | | | | @@ -318,6 +326,7 @@ trace. Architecture's requirements =========================== + The following functions and configurations are required: ``CONFIG_HOTPLUG_CPU`` @@ -339,11 +348,12 @@ The following functions and configurations are required: User Space Notification ======================= -After CPU successfully onlined or offline udev events are sent. A udev rule like: :: + +After CPU successfully onlined or offline udev events are sent. A udev rule like:: SUBSYSTEM=="cpu", DRIVERS=="processor", DEVPATH=="/devices/system/cpu/*", RUN+="the_hotplug_receiver.sh" -will receive all events. A script like: :: +will receive all events. A script like:: #!/bin/sh diff --git a/Documentation/core-api/irq/irq-domain.rst b/Documentation/core-api/irq/irq-domain.rst index 53283b3729a1..6979b4af2c1f 100644 --- a/Documentation/core-api/irq/irq-domain.rst +++ b/Documentation/core-api/irq/irq-domain.rst @@ -55,8 +55,24 @@ exist then it will allocate a new Linux irq_desc, associate it with the hwirq, and call the .map() callback so the driver can perform any required hardware setup. -When an interrupt is received, irq_find_mapping() function should -be used to find the Linux IRQ number from the hwirq number. +Once a mapping has been established, it can be retrieved or used via a +variety of methods: + +- irq_resolve_mapping() returns a pointer to the irq_desc structure + for a given domain and hwirq number, and NULL if there was no + mapping. +- irq_find_mapping() returns a Linux IRQ number for a given domain and + hwirq number, and 0 if there was no mapping +- irq_linear_revmap() is now identical to irq_find_mapping(), and is + deprecated +- generic_handle_domain_irq() handles an interrupt described by a + domain and a hwirq number +- handle_domain_irq() does the same thing for root interrupt + controllers and deals with the set_irq_reg()/irq_enter() sequences + that most architecture requires + +Note that irq domain lookups must happen in contexts that are +compatible with a RCU read-side critical section. The irq_create_mapping() function must be called *atleast once* before any call to irq_find_mapping(), lest the descriptor will not @@ -137,7 +153,9 @@ required. Calling irq_create_direct_mapping() will allocate a Linux IRQ number and call the .map() callback so that driver can program the Linux IRQ number into the hardware. -Most drivers cannot use this mapping. +Most drivers cannot use this mapping, and it is now gated on the +CONFIG_IRQ_DOMAIN_NOMAP option. Please refrain from introducing new +users of this API. Legacy ------ @@ -157,6 +175,10 @@ for IRQ numbers that are passed to struct device registrations. In that case the Linux IRQ numbers cannot be dynamically assigned and the legacy mapping should be used. +As the name implies, the *_legacy() functions are deprecated and only +exist to ease the support of ancient platforms. No new users should be +added. + The legacy map assumes a contiguous range of IRQ numbers has already been allocated for the controller and that the IRQ number can be calculated by adding a fixed offset to the hwirq number, and diff --git a/Documentation/core-api/printk-basics.rst b/Documentation/core-api/printk-basics.rst index 965e4281eddd..2dde24ca7d9f 100644 --- a/Documentation/core-api/printk-basics.rst +++ b/Documentation/core-api/printk-basics.rst @@ -107,9 +107,6 @@ also ``CONFIG_DYNAMIC_DEBUG`` in the case of pr_debug()) is defined. Function reference ================== -.. kernel-doc:: kernel/printk/printk.c - :functions: printk - .. kernel-doc:: include/linux/printk.h - :functions: pr_emerg pr_alert pr_crit pr_err pr_warn pr_notice pr_info + :functions: printk pr_emerg pr_alert pr_crit pr_err pr_warn pr_notice pr_info pr_fmt pr_debug pr_devel pr_cont diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst index d941717a191b..e08bbe9b0cbf 100644 --- a/Documentation/core-api/printk-formats.rst +++ b/Documentation/core-api/printk-formats.rst @@ -130,6 +130,7 @@ printed after the symbol name with an extra ``b`` appended to the end of the specifier. :: + %pS versatile_init+0x0/0x110 [module_name] %pSb versatile_init+0x0/0x110 [module_name ed5019fdf5e53be37cb1ba7899292d7e143b259e] %pSRb versatile_init+0x9/0x110 [module_name ed5019fdf5e53be37cb1ba7899292d7e143b259e] |