mirror of
https://github.com/linux-msm/laptops-kernel.git
synced 2026-08-13 14:19:53 -07:00
Merge tag 'docs-5.7' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet:
"This has been a busy cycle for documentation work.
Highlights include:
- Lots of RST conversion work by Mauro, Daniel ALmeida, and others.
Maybe someday we'll get to the end of this stuff...maybe...
- Some organizational work to bring some order to the core-api
manual.
- Various new docs and additions to the existing documentation.
- Typo fixes, warning fixes, ..."
* tag 'docs-5.7' of git://git.lwn.net/linux: (123 commits)
Documentation: x86: exception-tables: document CONFIG_BUILDTIME_TABLE_SORT
MAINTAINERS: adjust to filesystem doc ReST conversion
docs: deprecated.rst: Add BUG()-family
doc: zh_CN: add translation for virtiofs
doc: zh_CN: index files in filesystems subdirectory
docs: locking: Drop :c:func: throughout
docs: locking: Add 'need' to hardirq section
docs: conf.py: avoid thousands of duplicate label warning on Sphinx
docs: prevent warnings due to autosectionlabel
docs: fix reference to core-api/namespaces.rst
docs: fix pointers to io-mapping.rst and io_ordering.rst files
Documentation: Better document the softlockup_panic sysctl
docs: hw-vuln: tsx_async_abort.rst: get rid of an unused ref
docs: perf: imx-ddr.rst: get rid of a warning
docs: filesystems: fuse.rst: supress a Sphinx warning
docs: translations: it: avoid duplicate refs at programming-language.rst
docs: driver.rst: supress two ReSt warnings
docs: trace: events.rst: convert some new stuff to ReST format
Documentation: Add io_ordering.rst to driver-api manual
Documentation: Add io-mapping.rst to driver-api manual
...
This commit is contained in:
Linus Torvalds
+1
-1
@@ -1,5 +1,5 @@
|
||||
What: /sys/kernel/uids/<uid>/cpu_shares
|
||||
Date: December 2007
|
||||
Date: December 2007, finally removed in kernel v2.6.34-rc1
|
||||
Contact: Dhaval Giani <dhaval@linux.vnet.ibm.com>
|
||||
Srivatsa Vaddagiri <vatsa@linux.vnet.ibm.com>
|
||||
Description:
|
||||
@@ -13,7 +13,7 @@ endif
|
||||
SPHINXBUILD = sphinx-build
|
||||
SPHINXOPTS =
|
||||
SPHINXDIRS = .
|
||||
_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst))
|
||||
_SPHINXDIRS = $(sort $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst)))
|
||||
SPHINX_CONF = conf.py
|
||||
PAPER =
|
||||
BUILDDIR = $(obj)/output
|
||||
|
||||
@@ -239,7 +239,7 @@ from the PCI device config space. Use the values in the pci_dev structure
|
||||
as the PCI "bus address" might have been remapped to a "host physical"
|
||||
address by the arch/chip-set specific kernel support.
|
||||
|
||||
See Documentation/io-mapping.txt for how to access device registers
|
||||
See Documentation/driver-api/io-mapping.rst for how to access device registers
|
||||
or device memory.
|
||||
|
||||
The device driver needs to call pci_request_region() to verify
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
.. _psi:
|
||||
|
||||
================================
|
||||
PSI - Pressure Stall Information
|
||||
================================
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
Kernel Support for miscellaneous (your favourite) Binary Formats v1.1
|
||||
=====================================================================
|
||||
Kernel Support for miscellaneous Binary Formats (binfmt_misc)
|
||||
=============================================================
|
||||
|
||||
This Kernel feature allows you to invoke almost (for restrictions see below)
|
||||
every program by simply typing its name in the shell.
|
||||
|
||||
@@ -251,8 +251,6 @@ line of text and contains the following stats separated by whitespace:
|
||||
|
||||
================ =============================================================
|
||||
orig_data_size uncompressed size of data stored in this disk.
|
||||
This excludes same-element-filled pages (same_pages) since
|
||||
no memory is allocated for them.
|
||||
Unit: bytes
|
||||
compr_data_size compressed size of data stored in this disk
|
||||
mem_used_total the amount of memory allocated for this disk. This
|
||||
|
||||
@@ -23,7 +23,7 @@ of dot-connected-words, and key and value are connected by ``=``. The value
|
||||
has to be terminated by semi-colon (``;``) or newline (``\n``).
|
||||
For array value, array entries are separated by comma (``,``). ::
|
||||
|
||||
KEY[.WORD[...]] = VALUE[, VALUE2[...]][;]
|
||||
KEY[.WORD[...]] = VALUE[, VALUE2[...]][;]
|
||||
|
||||
Unlike the kernel command line syntax, spaces are OK around the comma and ``=``.
|
||||
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
.. _cgroup-v1:
|
||||
|
||||
========================
|
||||
Control Groups version 1
|
||||
========================
|
||||
|
||||
@@ -9,7 +9,7 @@ This is the authoritative documentation on the design, interface and
|
||||
conventions of cgroup v2. It describes all userland-visible aspects
|
||||
of cgroup including core and specific controller behaviors. All
|
||||
future changes must be reflected in this document. Documentation for
|
||||
v1 is available under Documentation/admin-guide/cgroup-v1/.
|
||||
v1 is available under :ref:`Documentation/admin-guide/cgroup-v1/index.rst <cgroup-v1>`.
|
||||
|
||||
.. CONTENTS
|
||||
|
||||
@@ -1023,7 +1023,7 @@ All time durations are in microseconds.
|
||||
A read-only nested-key file which exists on non-root cgroups.
|
||||
|
||||
Shows pressure stall information for CPU. See
|
||||
Documentation/accounting/psi.rst for details.
|
||||
:ref:`Documentation/accounting/psi.rst <psi>` for details.
|
||||
|
||||
cpu.uclamp.min
|
||||
A read-write single value file which exists on non-root cgroups.
|
||||
@@ -1103,7 +1103,7 @@ PAGE_SIZE multiple when read back.
|
||||
proportionally to the overage, reducing reclaim pressure for
|
||||
smaller overages.
|
||||
|
||||
Effective min boundary is limited by memory.min values of
|
||||
Effective min boundary is limited by memory.min values of
|
||||
all ancestor cgroups. If there is memory.min overcommitment
|
||||
(child cgroup or cgroups are requiring more protected memory
|
||||
than parent will allow), then each child cgroup will get
|
||||
@@ -1313,53 +1313,41 @@ PAGE_SIZE multiple when read back.
|
||||
Number of major page faults incurred
|
||||
|
||||
workingset_refault
|
||||
|
||||
Number of refaults of previously evicted pages
|
||||
|
||||
workingset_activate
|
||||
|
||||
Number of refaulted pages that were immediately activated
|
||||
|
||||
workingset_nodereclaim
|
||||
|
||||
Number of times a shadow node has been reclaimed
|
||||
|
||||
pgrefill
|
||||
|
||||
Amount of scanned pages (in an active LRU list)
|
||||
|
||||
pgscan
|
||||
|
||||
Amount of scanned pages (in an inactive LRU list)
|
||||
|
||||
pgsteal
|
||||
|
||||
Amount of reclaimed pages
|
||||
|
||||
pgactivate
|
||||
|
||||
Amount of pages moved to the active LRU list
|
||||
|
||||
pgdeactivate
|
||||
|
||||
Amount of pages moved to the inactive LRU list
|
||||
|
||||
pglazyfree
|
||||
|
||||
Amount of pages postponed to be freed under memory pressure
|
||||
|
||||
pglazyfreed
|
||||
|
||||
Amount of reclaimed lazyfree pages
|
||||
|
||||
thp_fault_alloc
|
||||
|
||||
Number of transparent hugepages which were allocated to satisfy
|
||||
a page fault, including COW faults. This counter is not present
|
||||
when CONFIG_TRANSPARENT_HUGEPAGE is not set.
|
||||
|
||||
thp_collapse_alloc
|
||||
|
||||
Number of transparent hugepages which were allocated to allow
|
||||
collapsing an existing range of pages. This counter is not
|
||||
present when CONFIG_TRANSPARENT_HUGEPAGE is not set.
|
||||
@@ -1403,7 +1391,7 @@ PAGE_SIZE multiple when read back.
|
||||
A read-only nested-key file which exists on non-root cgroups.
|
||||
|
||||
Shows pressure stall information for memory. See
|
||||
Documentation/accounting/psi.rst for details.
|
||||
:ref:`Documentation/accounting/psi.rst <psi>` for details.
|
||||
|
||||
|
||||
Usage Guidelines
|
||||
@@ -1478,7 +1466,7 @@ IO Interface Files
|
||||
dios Number of discard IOs
|
||||
====== =====================
|
||||
|
||||
An example read output follows:
|
||||
An example read output follows::
|
||||
|
||||
8:16 rbytes=1459200 wbytes=314773504 rios=192 wios=353 dbytes=0 dios=0
|
||||
8:0 rbytes=90430464 wbytes=299008000 rios=8950 wios=1252 dbytes=50331648 dios=3021
|
||||
@@ -1643,7 +1631,7 @@ IO Interface Files
|
||||
A read-only nested-key file which exists on non-root cgroups.
|
||||
|
||||
Shows pressure stall information for IO. See
|
||||
Documentation/accounting/psi.rst for details.
|
||||
:ref:`Documentation/accounting/psi.rst <psi>` for details.
|
||||
|
||||
|
||||
Writeback
|
||||
@@ -1853,7 +1841,7 @@ Cpuset Interface Files
|
||||
from the requested CPUs.
|
||||
|
||||
The CPU numbers are comma-separated numbers or ranges.
|
||||
For example:
|
||||
For example::
|
||||
|
||||
# cat cpuset.cpus
|
||||
0-4,6,8-10
|
||||
@@ -1892,7 +1880,7 @@ Cpuset Interface Files
|
||||
from the requested memory nodes.
|
||||
|
||||
The memory node numbers are comma-separated numbers or ranges.
|
||||
For example:
|
||||
For example::
|
||||
|
||||
# cat cpuset.mems
|
||||
0-1,3
|
||||
|
||||
@@ -11,11 +11,13 @@ Today, with the advent of Kernel Mode Setting, a graphics board is
|
||||
either correctly working because all components follow the standards -
|
||||
or the computer is unusable, because the screen remains dark after
|
||||
booting or it displays the wrong area. Cases when this happens are:
|
||||
|
||||
- The graphics board does not recognize the monitor.
|
||||
- The graphics board is unable to detect any EDID data.
|
||||
- The graphics board incorrectly forwards EDID data to the driver.
|
||||
- The monitor sends no or bogus EDID data.
|
||||
- A KVM sends its own EDID data instead of querying the connected monitor.
|
||||
|
||||
Adding the kernel parameter "nomodeset" helps in most cases, but causes
|
||||
restrictions later on.
|
||||
|
||||
@@ -32,7 +34,7 @@ individual data for a specific misbehaving monitor, commented sources
|
||||
and a Makefile environment are given here.
|
||||
|
||||
To create binary EDID and C source code files from the existing data
|
||||
material, simply type "make".
|
||||
material, simply type "make" in tools/edid/.
|
||||
|
||||
If you want to create your own EDID file, copy the file 1024x768.S,
|
||||
replace the settings with your own data and add a new target to the
|
||||
@@ -136,8 +136,6 @@ enables the mitigation by default.
|
||||
The mitigation can be controlled at boot time via a kernel command line option.
|
||||
See :ref:`taa_mitigation_control_command_line`.
|
||||
|
||||
.. _virt_mechanism:
|
||||
|
||||
Virtualization mitigation
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
@@ -75,6 +75,7 @@ configure specific aspects of kernel behavior to your liking.
|
||||
cputopology
|
||||
dell_rbu
|
||||
device-mapper/index
|
||||
edid
|
||||
efi-stub
|
||||
ext4
|
||||
nfs/index
|
||||
|
||||
@@ -1099,6 +1099,12 @@
|
||||
A valid base address must be provided, and the serial
|
||||
port must already be setup and configured.
|
||||
|
||||
ec_imx21,<addr>
|
||||
ec_imx6q,<addr>
|
||||
Start an early, polled-mode, output-only console on the
|
||||
Freescale i.MX UART at the specified address. The UART
|
||||
must already be setup and configured.
|
||||
|
||||
ar3700_uart,<addr>
|
||||
Start an early, polled-mode console on the
|
||||
Armada 3700 serial port at the specified
|
||||
@@ -1779,7 +1785,7 @@
|
||||
provided by tboot because it makes the system
|
||||
vulnerable to DMA attacks.
|
||||
nobounce [Default off]
|
||||
Disable bounce buffer for unstrusted devices such as
|
||||
Disable bounce buffer for untrusted devices such as
|
||||
the Thunderbolt devices. This will treat the untrusted
|
||||
devices as the trusted ones, hence might expose security
|
||||
risks of DMA attacks.
|
||||
@@ -1883,7 +1889,7 @@
|
||||
No delay
|
||||
|
||||
ip= [IP_PNP]
|
||||
See Documentation/filesystems/nfs/nfsroot.txt.
|
||||
See Documentation/admin-guide/nfs/nfsroot.rst.
|
||||
|
||||
ipcmni_extend [KNL] Extend the maximum number of unique System V
|
||||
IPC identifiers from 32,768 to 16,777,216.
|
||||
@@ -2795,7 +2801,7 @@
|
||||
<name>,<region-number>[,<base>,<size>,<buswidth>,<altbuswidth>]
|
||||
|
||||
mtdparts= [MTD]
|
||||
See drivers/mtd/cmdlinepart.c.
|
||||
See drivers/mtd/parsers/cmdlinepart.c
|
||||
|
||||
multitce=off [PPC] This parameter disables the use of the pSeries
|
||||
firmware feature for updating multiple TCE entries
|
||||
@@ -2853,13 +2859,13 @@
|
||||
Default value is 0.
|
||||
|
||||
nfsaddrs= [NFS] Deprecated. Use ip= instead.
|
||||
See Documentation/filesystems/nfs/nfsroot.txt.
|
||||
See Documentation/admin-guide/nfs/nfsroot.rst.
|
||||
|
||||
nfsroot= [NFS] nfs root filesystem for disk-less boxes.
|
||||
See Documentation/filesystems/nfs/nfsroot.txt.
|
||||
See Documentation/admin-guide/nfs/nfsroot.rst.
|
||||
|
||||
nfsrootdebug [NFS] enable nfsroot debugging messages.
|
||||
See Documentation/filesystems/nfs/nfsroot.txt.
|
||||
See Documentation/admin-guide/nfs/nfsroot.rst.
|
||||
|
||||
nfs.callback_nr_threads=
|
||||
[NFSv4] set the total number of threads that the
|
||||
@@ -4514,10 +4520,10 @@
|
||||
Format: <integer>
|
||||
|
||||
A nonzero value instructs the soft-lockup detector
|
||||
to panic the machine when a soft-lockup occurs. This
|
||||
is also controlled by CONFIG_BOOTPARAM_SOFTLOCKUP_PANIC
|
||||
which is the respective build-time switch to that
|
||||
functionality.
|
||||
to panic the machine when a soft-lockup occurs. It is
|
||||
also controlled by the kernel.softlockup_panic sysctl
|
||||
and CONFIG_BOOTPARAM_SOFTLOCKUP_PANIC, which is the
|
||||
respective build-time switch to that functionality.
|
||||
|
||||
softlockup_all_cpu_backtrace=
|
||||
[KNL] Should the soft-lockup detector generate
|
||||
|
||||
@@ -234,7 +234,7 @@ To reduce its OS jitter, do any of the following:
|
||||
Such a workqueue can be confined to a given subset of the
|
||||
CPUs using the ``/sys/devices/virtual/workqueue/*/cpumask`` sysfs
|
||||
files. The set of WQ_SYSFS workqueues can be displayed using
|
||||
"ls sys/devices/virtual/workqueue". That said, the workqueues
|
||||
"ls /sys/devices/virtual/workqueue". That said, the workqueues
|
||||
maintainer would like to caution people against indiscriminately
|
||||
sprinkling WQ_SYSFS across all the workqueues. The reason for
|
||||
caution is that it is easy to add WQ_SYSFS, but because sysfs is
|
||||
|
||||
@@ -43,7 +43,8 @@ value 1 for supported.
|
||||
|
||||
AXI_ID and AXI_MASKING are mapped on DPCR1 register in performance counter.
|
||||
When non-masked bits are matching corresponding AXI_ID bits then counter is
|
||||
incremented. Perf counter is incremented if
|
||||
incremented. Perf counter is incremented if::
|
||||
|
||||
AxID && AXI_MASKING == AXI_ID && AXI_MASKING
|
||||
|
||||
This filter doesn't support filter different AXI ID for axid-read and axid-write
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -4,18 +4,18 @@ ARM TCM (Tightly-Coupled Memory) handling in Linux
|
||||
|
||||
Written by Linus Walleij <linus.walleij@stericsson.com>
|
||||
|
||||
Some ARM SoC:s have a so-called TCM (Tightly-Coupled Memory).
|
||||
Some ARM SoCs have a so-called TCM (Tightly-Coupled Memory).
|
||||
This is usually just a few (4-64) KiB of RAM inside the ARM
|
||||
processor.
|
||||
|
||||
Due to being embedded inside the CPU The TCM has a
|
||||
Due to being embedded inside the CPU, the TCM has a
|
||||
Harvard-architecture, so there is an ITCM (instruction TCM)
|
||||
and a DTCM (data TCM). The DTCM can not contain any
|
||||
instructions, but the ITCM can actually contain data.
|
||||
The size of DTCM or ITCM is minimum 4KiB so the typical
|
||||
minimum configuration is 4KiB ITCM and 4KiB DTCM.
|
||||
|
||||
ARM CPU:s have special registers to read out status, physical
|
||||
ARM CPUs have special registers to read out status, physical
|
||||
location and size of TCM memories. arch/arm/include/asm/cputype.h
|
||||
defines a CPUID_TCM register that you can read out from the
|
||||
system control coprocessor. Documentation from ARM can be found
|
||||
|
||||
@@ -38,7 +38,11 @@ needs_sphinx = '1.3'
|
||||
# ones.
|
||||
extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain',
|
||||
'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
|
||||
'maintainers_include']
|
||||
'maintainers_include', 'sphinx.ext.autosectionlabel' ]
|
||||
|
||||
# Ensure that autosectionlabel will produce unique names
|
||||
autosectionlabel_prefix_document = True
|
||||
autosectionlabel_maxdepth = 2
|
||||
|
||||
# The name of the math extension changed on Sphinx 1.4
|
||||
if (major == 1 and minor > 3) or (major > 1):
|
||||
|
||||
@@ -8,41 +8,81 @@ This is the beginning of a manual for core kernel APIs. The conversion
|
||||
Core utilities
|
||||
==============
|
||||
|
||||
This section has general and "core core" documentation. The first is a
|
||||
massive grab-bag of kerneldoc info left over from the docbook days; it
|
||||
should really be broken up someday when somebody finds the energy to do
|
||||
it.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
kernel-api
|
||||
assoc_array
|
||||
atomic_ops
|
||||
cachetlb
|
||||
refcount-vs-atomic
|
||||
cpu_hotplug
|
||||
idr
|
||||
local_ops
|
||||
workqueue
|
||||
genericirq
|
||||
xarray
|
||||
librs
|
||||
genalloc
|
||||
errseq
|
||||
packing
|
||||
printk-formats
|
||||
symbol-namespaces
|
||||
|
||||
Data structures and low-level utilities
|
||||
=======================================
|
||||
|
||||
Library functionality that is used throughout the kernel.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
kobject
|
||||
assoc_array
|
||||
xarray
|
||||
idr
|
||||
circular-buffers
|
||||
generic-radix-tree
|
||||
packing
|
||||
timekeeping
|
||||
errseq
|
||||
|
||||
Concurrency primitives
|
||||
======================
|
||||
|
||||
How Linux keeps everything from happening at the same time. See
|
||||
:doc:`/locking/index` for more related documentation.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
atomic_ops
|
||||
refcount-vs-atomic
|
||||
local_ops
|
||||
padata
|
||||
../RCU/index
|
||||
|
||||
Low-level hardware management
|
||||
=============================
|
||||
|
||||
Cache management, managing CPU hotplug, etc.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
cachetlb
|
||||
cpu_hotplug
|
||||
memory-hotplug
|
||||
genericirq
|
||||
protection-keys
|
||||
|
||||
Memory management
|
||||
=================
|
||||
|
||||
How to allocate and use memory in the kernel. Note that there is a lot
|
||||
more memory-management documentation in :doc:`/vm/index`.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
memory-allocation
|
||||
mm-api
|
||||
genalloc
|
||||
pin_user_pages
|
||||
gfp_mask-from-fs-io
|
||||
timekeeping
|
||||
boot-time-mm
|
||||
memory-hotplug
|
||||
protection-keys
|
||||
../RCU/index
|
||||
gcc-plugins
|
||||
symbol-namespaces
|
||||
padata
|
||||
ioctl
|
||||
|
||||
gfp_mask-from-fs-io
|
||||
|
||||
Interfaces for kernel debugging
|
||||
===============================
|
||||
@@ -53,6 +93,16 @@ Interfaces for kernel debugging
|
||||
debug-objects
|
||||
tracepoint
|
||||
|
||||
Everything else
|
||||
===============
|
||||
|
||||
Documents that don't fit elsewhere or which have yet to be categorized.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
librs
|
||||
|
||||
.. only:: subproject and html
|
||||
|
||||
Indices
|
||||
|
||||
@@ -25,7 +25,7 @@ some terms we will be working with.
|
||||
usually embedded within some other structure which contains the stuff
|
||||
the code is really interested in.
|
||||
|
||||
No structure should EVER have more than one kobject embedded within it.
|
||||
No structure should **EVER** have more than one kobject embedded within it.
|
||||
If it does, the reference counting for the object is sure to be messed
|
||||
up and incorrect, and your code will be buggy. So do not do this.
|
||||
|
||||
@@ -55,7 +55,7 @@ a larger, domain-specific object. To this end, kobjects will be found
|
||||
embedded in other structures. If you are used to thinking of things in
|
||||
object-oriented terms, kobjects can be seen as a top-level, abstract class
|
||||
from which other classes are derived. A kobject implements a set of
|
||||
capabilities which are not particularly useful by themselves, but which are
|
||||
capabilities which are not particularly useful by themselves, but are
|
||||
nice to have in other objects. The C language does not allow for the
|
||||
direct expression of inheritance, so other techniques - such as structure
|
||||
embedding - must be used.
|
||||
@@ -65,12 +65,12 @@ this is analogous as to how "list_head" structs are rarely useful on
|
||||
their own, but are invariably found embedded in the larger objects of
|
||||
interest.)
|
||||
|
||||
So, for example, the UIO code in drivers/uio/uio.c has a structure that
|
||||
So, for example, the UIO code in ``drivers/uio/uio.c`` has a structure that
|
||||
defines the memory region associated with a uio device::
|
||||
|
||||
struct uio_map {
|
||||
struct kobject kobj;
|
||||
struct uio_mem *mem;
|
||||
struct kobject kobj;
|
||||
struct uio_mem *mem;
|
||||
};
|
||||
|
||||
If you have a struct uio_map structure, finding its embedded kobject is
|
||||
@@ -78,30 +78,30 @@ just a matter of using the kobj member. Code that works with kobjects will
|
||||
often have the opposite problem, however: given a struct kobject pointer,
|
||||
what is the pointer to the containing structure? You must avoid tricks
|
||||
(such as assuming that the kobject is at the beginning of the structure)
|
||||
and, instead, use the container_of() macro, found in <linux/kernel.h>::
|
||||
and, instead, use the container_of() macro, found in ``<linux/kernel.h>``::
|
||||
|
||||
container_of(pointer, type, member)
|
||||
|
||||
where:
|
||||
|
||||
* "pointer" is the pointer to the embedded kobject,
|
||||
* "type" is the type of the containing structure, and
|
||||
* "member" is the name of the structure field to which "pointer" points.
|
||||
* ``pointer`` is the pointer to the embedded kobject,
|
||||
* ``type`` is the type of the containing structure, and
|
||||
* ``member`` is the name of the structure field to which ``pointer`` points.
|
||||
|
||||
The return value from container_of() is a pointer to the corresponding
|
||||
container type. So, for example, a pointer "kp" to a struct kobject
|
||||
embedded *within* a struct uio_map could be converted to a pointer to the
|
||||
*containing* uio_map structure with::
|
||||
container type. So, for example, a pointer ``kp`` to a struct kobject
|
||||
embedded **within** a struct uio_map could be converted to a pointer to the
|
||||
**containing** uio_map structure with::
|
||||
|
||||
struct uio_map *u_map = container_of(kp, struct uio_map, kobj);
|
||||
|
||||
For convenience, programmers often define a simple macro for "back-casting"
|
||||
For convenience, programmers often define a simple macro for **back-casting**
|
||||
kobject pointers to the containing type. Exactly this happens in the
|
||||
earlier drivers/uio/uio.c, as you can see here::
|
||||
earlier ``drivers/uio/uio.c``, as you can see here::
|
||||
|
||||
struct uio_map {
|
||||
struct kobject kobj;
|
||||
struct uio_mem *mem;
|
||||
struct kobject kobj;
|
||||
struct uio_mem *mem;
|
||||
};
|
||||
|
||||
#define to_map(map) container_of(map, struct uio_map, kobj)
|
||||
@@ -125,7 +125,7 @@ must have an associated kobj_type. After calling kobject_init(), to
|
||||
register the kobject with sysfs, the function kobject_add() must be called::
|
||||
|
||||
int kobject_add(struct kobject *kobj, struct kobject *parent,
|
||||
const char *fmt, ...);
|
||||
const char *fmt, ...);
|
||||
|
||||
This sets up the parent of the kobject and the name for the kobject
|
||||
properly. If the kobject is to be associated with a specific kset,
|
||||
@@ -172,13 +172,13 @@ call to kobject_uevent()::
|
||||
|
||||
int kobject_uevent(struct kobject *kobj, enum kobject_action action);
|
||||
|
||||
Use the KOBJ_ADD action for when the kobject is first added to the kernel.
|
||||
Use the **KOBJ_ADD** action for when the kobject is first added to the kernel.
|
||||
This should be done only after any attributes or children of the kobject
|
||||
have been initialized properly, as userspace will instantly start to look
|
||||
for them when this call happens.
|
||||
|
||||
When the kobject is removed from the kernel (details on how to do that are
|
||||
below), the uevent for KOBJ_REMOVE will be automatically created by the
|
||||
below), the uevent for **KOBJ_REMOVE** will be automatically created by the
|
||||
kobject core, so the caller does not have to worry about doing that by
|
||||
hand.
|
||||
|
||||
@@ -238,7 +238,7 @@ Both types of attributes used here, with a kobject that has been created
|
||||
with the kobject_create_and_add(), can be of type kobj_attribute, so no
|
||||
special custom attribute is needed to be created.
|
||||
|
||||
See the example module, samples/kobject/kobject-example.c for an
|
||||
See the example module, ``samples/kobject/kobject-example.c`` for an
|
||||
implementation of a simple kobject and attributes.
|
||||
|
||||
|
||||
@@ -270,10 +270,10 @@ such a method has a form like::
|
||||
|
||||
void my_object_release(struct kobject *kobj)
|
||||
{
|
||||
struct my_object *mine = container_of(kobj, struct my_object, kobj);
|
||||
struct my_object *mine = container_of(kobj, struct my_object, kobj);
|
||||
|
||||
/* Perform any additional cleanup on this object, then... */
|
||||
kfree(mine);
|
||||
/* Perform any additional cleanup on this object, then... */
|
||||
kfree(mine);
|
||||
}
|
||||
|
||||
One important point cannot be overstated: every kobject must have a
|
||||
@@ -297,11 +297,11 @@ instead, it is associated with the ktype. So let us introduce struct
|
||||
kobj_type::
|
||||
|
||||
struct kobj_type {
|
||||
void (*release)(struct kobject *kobj);
|
||||
const struct sysfs_ops *sysfs_ops;
|
||||
struct attribute **default_attrs;
|
||||
const struct kobj_ns_type_operations *(*child_ns_type)(struct kobject *kobj);
|
||||
const void *(*namespace)(struct kobject *kobj);
|
||||
void (*release)(struct kobject *kobj);
|
||||
const struct sysfs_ops *sysfs_ops;
|
||||
struct attribute **default_attrs;
|
||||
const struct kobj_ns_type_operations *(*child_ns_type)(struct kobject *kobj);
|
||||
const void *(*namespace)(struct kobject *kobj);
|
||||
};
|
||||
|
||||
This structure is used to describe a particular type of kobject (or, more
|
||||
@@ -352,8 +352,8 @@ created and never declared statically or on the stack. To create a new
|
||||
kset use::
|
||||
|
||||
struct kset *kset_create_and_add(const char *name,
|
||||
struct kset_uevent_ops *u,
|
||||
struct kobject *parent);
|
||||
struct kset_uevent_ops *u,
|
||||
struct kobject *parent);
|
||||
|
||||
When you are finished with the kset, call::
|
||||
|
||||
@@ -365,16 +365,16 @@ Because other references to the kset may still exist, the release may happen
|
||||
after kset_unregister() returns.
|
||||
|
||||
An example of using a kset can be seen in the
|
||||
samples/kobject/kset-example.c file in the kernel tree.
|
||||
``samples/kobject/kset-example.c`` file in the kernel tree.
|
||||
|
||||
If a kset wishes to control the uevent operations of the kobjects
|
||||
associated with it, it can use the struct kset_uevent_ops to handle it::
|
||||
|
||||
struct kset_uevent_ops {
|
||||
int (*filter)(struct kset *kset, struct kobject *kobj);
|
||||
const char *(*name)(struct kset *kset, struct kobject *kobj);
|
||||
int (*uevent)(struct kset *kset, struct kobject *kobj,
|
||||
struct kobj_uevent_env *env);
|
||||
int (*filter)(struct kset *kset, struct kobject *kobj);
|
||||
const char *(*name)(struct kset *kset, struct kobject *kobj);
|
||||
int (*uevent)(struct kset *kset, struct kobject *kobj,
|
||||
struct kobj_uevent_env *env);
|
||||
};
|
||||
|
||||
|
||||
@@ -408,8 +408,8 @@ Kobject removal
|
||||
After a kobject has been registered with the kobject core successfully, it
|
||||
must be cleaned up when the code is finished with it. To do that, call
|
||||
kobject_put(). By doing this, the kobject core will automatically clean up
|
||||
all of the memory allocated by this kobject. If a KOBJ_ADD uevent has been
|
||||
sent for the object, a corresponding KOBJ_REMOVE uevent will be sent, and
|
||||
all of the memory allocated by this kobject. If a ``KOBJ_ADD`` uevent has been
|
||||
sent for the object, a corresponding ``KOBJ_REMOVE`` uevent will be sent, and
|
||||
any other sysfs housekeeping will be handled for the caller properly.
|
||||
|
||||
If you need to do a two-stage delete of the kobject (say you are not
|
||||
@@ -430,5 +430,5 @@ Example code to copy from
|
||||
=========================
|
||||
|
||||
For a more complete example of using ksets and kobjects properly, see the
|
||||
example programs samples/kobject/{kobject-example.c,kset-example.c},
|
||||
which will be built as loadable modules if you select CONFIG_SAMPLE_KOBJECT.
|
||||
example programs ``samples/kobject/{kobject-example.c,kset-example.c}``,
|
||||
which will be built as loadable modules if you select ``CONFIG_SAMPLE_KOBJECT``.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user