Commit 8c79f4cd authored by Linus Torvalds's avatar Linus Torvalds

Merge tag 'docs-5.2' of git://git.lwn.net/linux

Pull documentation updates from Jonathan Corbet:
 "A reasonably busy cycle for docs, including:

   - Lots of work on the Chinese and Italian translations

   - Some license-rules clarifications from Christoph

   - Various build-script fixes

   - A new document on memory models

   - RST conversion of the live-patching docs

   - The usual collection of typo fixes and corrections"

* tag 'docs-5.2' of git://git.lwn.net/linux: (140 commits)
  docs/livepatch: Unify style of livepatch documentation in the ReST format
  docs: livepatch: convert docs to ReST and rename to *.rst
  scripts/documentation-file-ref-check: detect broken :doc:`foo`
  scripts/documentation-file-ref-check: don't parse Next/ dir
  LICENSES: Rename other to deprecated
  LICENSES: Clearly mark dual license only licenses
  docs: Don't reference the ZLib license in license-rules.rst
  docs/vm: Minor editorial changes in the THP and hugetlbfs
  docs/vm: add documentation of memory models
  doc:it_IT: translation alignment
  doc: fix typo in PGP guide
  dontdiff: update with Kconfig build artifacts
  docs/zh_CN: fix typos in 1.Intro.rst file
  docs/zh_CN: redirect CoC docs to Chinese version
  doc: mm: migration doesn't use FOLL_SPLIT anymore
  docs: doc-guide: remove the extension from .rst files
  doc: kselftest: Fix KBUILD_OUTPUT usage instructions
  docs: trace: fix some Sphinx warnings
  docs: speculation.txt: mark example blocks as such
  docs: ntb.txt: add blank lines to clean up some Sphinx warnings
  ...
parents 2646719a d9defe44
......@@ -16,6 +16,8 @@ Alan Cox <alan@lxorguk.ukuu.org.uk>
Alan Cox <root@hraefn.swansea.linux.org.uk>
Aleksey Gorelov <aleksey_gorelov@phoenix.com>
Aleksandar Markovic <aleksandar.markovic@mips.com> <aleksandar.markovic@imgtec.com>
Alex Shi <alex.shi@linux.alibaba.com> <alex.shi@intel.com>
Alex Shi <alex.shi@linux.alibaba.com> <alex.shi@linaro.org>
Alexei Starovoitov <ast@kernel.org> <ast@plumgrid.com>
Alexei Starovoitov <ast@kernel.org> <alexei.starovoitov@gmail.com>
Alexei Starovoitov <ast@kernel.org> <ast@fb.com>
......@@ -126,6 +128,8 @@ Leonid I Ananiev <leonid.i.ananiev@intel.com>
Linas Vepstas <linas@austin.ibm.com>
Linus Lüssing <linus.luessing@c0d3.blue> <linus.luessing@web.de>
Linus Lüssing <linus.luessing@c0d3.blue> <linus.luessing@ascom.ch>
Li Yang <leoyang.li@nxp.com> <leo@zh-kernel.org>
Li Yang <leoyang.li@nxp.com> <leoli@freescale.com>
Maciej W. Rozycki <macro@mips.com> <macro@imgtec.com>
Marcin Nowakowski <marcin.nowakowski@mips.com> <marcin.nowakowski@imgtec.com>
Mark Brown <broonie@sirena.org.uk>
......@@ -217,6 +221,8 @@ Tejun Heo <htejun@gmail.com>
Thomas Graf <tgraf@suug.ch>
Thomas Pedersen <twp@codeaurora.org>
Tony Luck <tony.luck@intel.com>
TripleX Chung <xxx.phy@gmail.com> <zhongyu@18mail.cn>
TripleX Chung <xxx.phy@gmail.com> <triplex@zh-kernel.org>
Tsuneo Yoshioka <Tsuneo.Yoshioka@f-secure.com>
Uwe Kleine-König <ukleinek@informatik.uni-freiburg.de>
Uwe Kleine-König <ukl@pengutronix.de>
......
......@@ -45,7 +45,7 @@ Description:
use this feature without a clearance from a patch
distributor. Removal (rmmod) of patch modules is permanently
disabled when the feature is used. See
Documentation/livepatch/livepatch.txt for more information.
Documentation/livepatch/livepatch.rst for more information.
What: /sys/kernel/livepatch/<patch>/<object>
Date: Nov 2014
......
......@@ -147,7 +147,7 @@ networking subsystems make sure that the buffers they use are valid
for you to DMA from/to.
DMA addressing capabilities
==========================
===========================
By default, the kernel assumes that your device can address 32-bits of DMA
addressing. For a 64-bit capable device, this needs to be increased, and for
......
......@@ -28,8 +28,13 @@ ifeq ($(HAVE_SPHINX),0)
else # HAVE_SPHINX
# User-friendly check for pdflatex
# User-friendly check for pdflatex and latexmk
HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)
HAVE_LATEXMK := $(shell if which latexmk >/dev/null 2>&1; then echo 1; else echo 0; fi)
ifeq ($(HAVE_LATEXMK),1)
PDFLATEX := latexmk -$(PDFLATEX)
endif #HAVE_LATEXMK
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
......@@ -82,7 +87,7 @@ pdfdocs:
else # HAVE_PDFLATEX
pdfdocs: latexdocs
$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
endif # HAVE_PDFLATEX
......
On atomic bitops.
=============
Atomic bitops
=============
While our bitmap_{}() functions are non-atomic, we have a number of operations
operating on single bits in a bitmap that are atomic.
......
Clearing WARN_ONCE
------------------
WARN_ONCE / WARN_ON_ONCE / printk_once only emit a message once.
......
......@@ -22,7 +22,6 @@ Core utilities
workqueue
genericirq
xarray
flexible-arrays
librs
genalloc
errseq
......
......@@ -7,6 +7,11 @@ directory. These are intended to be small tests to exercise individual code
paths in the kernel. Tests are intended to be run after building, installing
and booting a kernel.
You can find additional information on Kselftest framework, how to
write new tests using the framework on Kselftest wiki:
https://kselftest.wiki.kernel.org/
On some systems, hot-plug tests could hang forever waiting for cpu and
memory to be ready to be offlined. A special hot-plug target is created
to run the full range of hot-plug tests. In default mode, hot-plug tests run
......@@ -35,17 +40,32 @@ To build and run the tests with a single command, use::
Note that some tests will require root privileges.
Build and run from user specific object directory (make O=dir)::
Kselftest supports saving output files in a separate directory and then
running tests. To locate output files in a separate directory two syntaxes
are supported. In both cases the working directory must be the root of the
kernel src. This is applicable to "Running a subset of selftests" section
below.
To build, save output files in a separate directory with O= ::
$ make O=/tmp/kselftest kselftest
Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
To build, save output files in a separate directory with KBUILD_OUTPUT ::
$ export KBUILD_OUTPUT=/tmp/kselftest; make kselftest
$ make KBUILD_OUTPUT=/tmp/kselftest kselftest
The O= assignment takes precedence over the KBUILD_OUTPUT environment
variable.
The above commands run the tests and print pass/fail summary to make it
easier to understand the test results. Please find the detailed individual
test results for each test in /tmp/testname file(s).
The above commands by default run the tests and print full pass/fail report.
Kselftest supports "summary" option to make it easier to understand the test
results. Please find the detailed individual test results for each test in
/tmp/testname file(s) when summary option is specified. This is applicable
to "Running a subset of selftests" section below.
To run kselftest with summary option enabled ::
$ make summary=1 kselftest
Running a subset of selftests
=============================
......@@ -61,17 +81,13 @@ You can specify multiple tests to build and run::
$ make TARGETS="size timers" kselftest
Build and run from user specific object directory (make O=dir)::
To build, save output files in a separate directory with O= ::
$ make O=/tmp/kselftest TARGETS="size timers" kselftest
Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
$ make KBUILD_OUTPUT=/tmp/kselftest TARGETS="size timers" kselftest
To build, save output files in a separate directory with KBUILD_OUTPUT ::
The above commands run the tests and print pass/fail summary to make it
easier to understand the test results. Please find the detailed individual
test results for each test in /tmp/testname file(s).
$ export KBUILD_OUTPUT=/tmp/kselftest; make TARGETS="size timers" kselftest
See the top-level tools/testing/selftests/Makefile for the list of all
possible targets.
......
......@@ -7,9 +7,9 @@ How to write kernel documentation
.. toctree::
:maxdepth: 1
sphinx.rst
kernel-doc.rst
parse-headers.rst
sphinx
kernel-doc
parse-headers
.. only:: subproject and html
......
......@@ -127,7 +127,7 @@ flask.h
fore200e_mkfirm
fore200e_pca_fw.c*
gconf
gconf.glade.h
gconf-cfg
gen-devlist
gen_crc32table
gen_init_cpio
......@@ -148,24 +148,22 @@ int32.c
int4.c
int8.c
kallsyms
kconfig
keywords.c
ksym.c*
ksym.h*
kxgettext
*lex.c
*lex.*.c
linux
logo_*.c
logo_*_clut224.c
logo_*_mono.c
lxdialog
mach-types
mach-types.h
machtypes.h
map
map_hugetlb
mconf
mconf-cfg
miboot*
mk_elfconfig
mkboot
......@@ -183,6 +181,7 @@ modules.builtin.modinfo
modules.order
modversions.h*
nconf
nconf-cfg
ncscope.*
offset.h
oui.c*
......@@ -202,6 +201,7 @@ pnmtologo
ppc_defs.h*
pss_boot.h
qconf
qconf-cfg
r100_reg_safe.h
r200_reg_safe.h
r300_reg_safe.h
......
......@@ -201,7 +201,7 @@ Bus implements below API for allocate a stream which needs to be called once
per stream. From ASoC DPCM framework, this stream state maybe linked to
.startup() operation.
.. code-block:: c
.. code-block:: c
int sdw_alloc_stream(char * stream_name);
......@@ -228,7 +228,7 @@ the respective Master(s) and Slave(s) associated with stream. These APIs can
only be invoked once by respective Master(s) and Slave(s). From ASoC DPCM
framework, this stream state is linked to .hw_params() operation.
.. code-block:: c
.. code-block:: c
int sdw_stream_add_master(struct sdw_bus * bus,
struct sdw_stream_config * stream_config,
......@@ -274,7 +274,7 @@ Bus implements below API for PREPARE state which needs to be called once per
stream. From ASoC DPCM framework, this stream state is linked to
.prepare() operation.
.. code-block:: c
.. code-block:: c
int sdw_prepare_stream(struct sdw_stream_runtime * stream);
......@@ -304,7 +304,7 @@ Bus implements below API for ENABLE state which needs to be called once per
stream. From ASoC DPCM framework, this stream state is linked to
.trigger() start operation.
.. code-block:: c
.. code-block:: c
int sdw_enable_stream(struct sdw_stream_runtime * stream);
......@@ -332,7 +332,7 @@ Bus implements below API for DISABLED state which needs to be called once
per stream. From ASoC DPCM framework, this stream state is linked to
.trigger() stop operation.
.. code-block:: c
.. code-block:: c
int sdw_disable_stream(struct sdw_stream_runtime * stream);
......@@ -357,7 +357,7 @@ Bus implements below API for DEPREPARED state which needs to be called once
per stream. From ASoC DPCM framework, this stream state is linked to
.trigger() stop operation.
.. code-block:: c
.. code-block:: c
int sdw_deprepare_stream(struct sdw_stream_runtime * stream);
......@@ -382,7 +382,7 @@ Bus implements below APIs for RELEASE state which needs to be called by
all the Master(s) and Slave(s) associated with stream. From ASoC DPCM
framework, this stream state is linked to .hw_free() operation.
.. code-block:: c
.. code-block:: c
int sdw_stream_remove_master(struct sdw_bus * bus,
struct sdw_stream_runtime * stream);
......@@ -395,7 +395,7 @@ stream assigned as part of ALLOCATED state.
In .shutdown() the data structure maintaining stream state are freed up.
.. code-block:: c
.. code-block:: c
void sdw_release_stream(struct sdw_stream_runtime * stream);
......
......@@ -4,7 +4,7 @@
Livepatch (un)patch-callbacks provide a mechanism for livepatch modules
to execute callback functions when a kernel object is (un)patched. They
can be considered a "power feature" that extends livepatching abilities
can be considered a **power feature** that **extends livepatching abilities**
to include:
- Safe updates to global data
......@@ -17,6 +17,9 @@ In most cases, (un)patch callbacks will need to be used in conjunction
with memory barriers and kernel synchronization primitives, like
mutexes/spinlocks, or even stop_machine(), to avoid concurrency issues.
1. Motivation
=============
Callbacks differ from existing kernel facilities:
- Module init/exit code doesn't run when disabling and re-enabling a
......@@ -28,21 +31,31 @@ Callbacks are part of the klp_object structure and their implementation
is specific to that klp_object. Other livepatch objects may or may not
be patched, irrespective of the target klp_object's current state.
2. Callback types
=================
Callbacks can be registered for the following livepatch actions:
* Pre-patch - before a klp_object is patched
* Pre-patch
- before a klp_object is patched
* Post-patch - after a klp_object has been patched and is active
* Post-patch
- after a klp_object has been patched and is active
across all tasks
* Pre-unpatch - before a klp_object is unpatched (ie, patched code is
* Pre-unpatch
- before a klp_object is unpatched (ie, patched code is
active), used to clean up post-patch callback
resources
* Post-unpatch - after a klp_object has been patched, all code has
* Post-unpatch
- after a klp_object has been patched, all code has
been restored and no tasks are running patched code,
used to cleanup pre-patch callback resources
3. How it works
===============
Each callback is optional, omitting one does not preclude specifying any
other. However, the livepatching core executes the handlers in
symmetry: pre-patch callbacks have a post-unpatch counterpart and
......@@ -86,11 +99,14 @@ If the object did successfully patch, but the patch transition never
started for some reason (e.g., if another object failed to patch),
only the post-unpatch callback will be called.
4. Use cases
============
Example Use-cases
=================
Sample livepatch modules demonstrating the callback API can be found in
samples/livepatch/ directory. These samples were modified for use in
kselftests and can be found in the lib/livepatch directory.
Update global data
Global data update
------------------
A pre-patch callback can be useful to update a global variable. For
......@@ -103,24 +119,15 @@ patch the data *after* patching is complete with a post-patch callback,
so that tcp_send_challenge_ack() could first be changed to read
sysctl_tcp_challenge_ack_limit with READ_ONCE.
Support __init and probe function patches
__init and probe function patches support
-----------------------------------------
Although __init and probe functions are not directly livepatch-able, it
may be possible to implement similar updates via pre/post-patch
callbacks.
48900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST") change the way that
The commit ``48900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST")`` change the way that
virtnet_probe() initialized its driver's net_device features. A
pre/post-patch callback could iterate over all such devices, making a
similar change to their hw_features value. (Client functions of the
value may need to be updated accordingly.)
Other Examples
==============
Sample livepatch modules demonstrating the callback API can be found in
samples/livepatch/ directory. These samples were modified for use in
kselftests and can be found in the lib/livepatch directory.
......@@ -18,7 +18,7 @@ Usage
-----
The atomic replace can be enabled by setting "replace" flag in struct klp_patch,
for example:
for example::
static struct klp_patch patch = {
.mod = THIS_MODULE,
......@@ -49,19 +49,19 @@ Features
The atomic replace allows:
+ Atomically revert some functions in a previous patch while
- Atomically revert some functions in a previous patch while
upgrading other functions.
+ Remove eventual performance impact caused by core redirection
- Remove eventual performance impact caused by core redirection
for functions that are no longer patched.
+ Decrease user confusion about dependencies between livepatches.
- Decrease user confusion about dependencies between livepatches.
Limitations:
------------
+ Once the operation finishes, there is no straightforward way
- Once the operation finishes, there is no straightforward way
to reverse it and restore the replaced patches atomically.
A good practice is to set .replace flag in any released livepatch.
......@@ -74,7 +74,7 @@ Limitations:
only when the transition was not forced.
+ Only the (un)patching callbacks from the _new_ cumulative livepatch are
- Only the (un)patching callbacks from the _new_ cumulative livepatch are
executed. Any callbacks from the replaced patches are ignored.
In other words, the cumulative patch is responsible for doing any actions
......@@ -93,7 +93,7 @@ Limitations:
enabled patches were called.
+ There is no special handling of shadow variables. Livepatch authors
- There is no special handling of shadow variables. Livepatch authors
must create their own rules how to pass them from one cumulative
patch to the other. Especially that they should not blindly remove
them in module_exit() functions.
......
:orphan:
===================
Kernel Livepatching
===================
.. toctree::
:maxdepth: 1
livepatch
callbacks
cumulative-patches
module-elf-format
shadow-vars
.. only:: subproject and html
Indices
=======
* :ref:`genindex`
......@@ -4,22 +4,22 @@ Livepatch
This document outlines basic information about kernel livepatching.
Table of Contents:
.. Table of Contents:
1. Motivation
2. Kprobes, Ftrace, Livepatching
3. Consistency model
4. Livepatch module
1. Motivation
2. Kprobes, Ftrace, Livepatching
3. Consistency model
4. Livepatch module
4.1. New functions
4.2. Metadata
5. Livepatch life-cycle
5. Livepatch life-cycle
5.1. Loading
5.2. Enabling
5.3. Replacing
5.4. Disabling
5.5. Removing
6. Sysfs
7. Limitations
6. Sysfs
7. Limitations
1. Motivation
......@@ -40,14 +40,14 @@ There are multiple mechanisms in the Linux kernel that are directly related
to redirection of code execution; namely: kernel probes, function tracing,
and livepatching:
+ The kernel probes are the most generic. The code can be redirected by
- The kernel probes are the most generic. The code can be redirected by
putting a breakpoint instruction instead of any instruction.
+ The function tracer calls the code from a predefined location that is
- The function tracer calls the code from a predefined location that is
close to the function entry point. This location is generated by the
compiler using the '-pg' gcc option.
+ Livepatching typically needs to redirect the code at the very beginning
- Livepatching typically needs to redirect the code at the very beginning
of the function entry before the function parameters or the stack
are in any way modified.
......@@ -249,7 +249,7 @@ The patch contains only functions that are really modified. But they
might want to access functions or data from the original source file
that may only be locally accessible. This can be solved by a special
relocation section in the generated livepatch module, see
Documentation/livepatch/module-elf-format.txt for more details.
Documentation/livepatch/module-elf-format.rst for more details.
4.2. Metadata
......@@ -258,7 +258,7 @@ Documentation/livepatch/module-elf-format.txt for more details.
The patch is described by several structures that split the information
into three levels:
+ struct klp_func is defined for each patched function. It describes
- struct klp_func is defined for each patched function. It describes
the relation between the original and the new implementation of a
particular function.
......@@ -275,7 +275,7 @@ into three levels:
only for a particular object ( vmlinux or a kernel module ). Note that
kallsyms allows for searching symbols according to the object name.
+ struct klp_object defines an array of patched functions (struct
- struct klp_object defines an array of patched functions (struct
klp_func) in the same object. Where the object is either vmlinux
(NULL) or a module name.
......@@ -285,7 +285,7 @@ into three levels:
only when they are available.
+ struct klp_patch defines an array of patched objects (struct
- struct klp_patch defines an array of patched objects (struct
klp_object).
This structure handles all patched functions consistently and eventually,
......@@ -337,14 +337,16 @@ operation fails.
Second, livepatch enters into a transition state where tasks are converging
to the patched state. If an original function is patched for the first
time, a function specific struct klp_ops is created and an universal
ftrace handler is registered[*]. This stage is indicated by a value of '1'
ftrace handler is registered\ [#]_. This stage is indicated by a value of '1'
in /sys/kernel/livepatch/<name>/transition. For more information about
this process, see the "Consistency model" section.
Finally, once all tasks have been patched, the 'transition' value changes
to '0'.
[*] Note that functions might be patched multiple times. The ftrace handler
.. [#]
Note that functions might be patched multiple times. The ftrace handler
is registered only once for a given function. Further patches just add
an entry to the list (see field `func_stack`) of the struct klp_ops.
The right implementation is selected by the ftrace handler, see
......@@ -368,7 +370,7 @@ the ftrace handler is unregistered and the struct klp_ops is
freed when the related function is not modified by the new patch
and func_stack list becomes empty.
See Documentation/livepatch/cumulative-patches.txt for more details.
See Documentation/livepatch/cumulative-patches.rst for more details.
5.4. Disabling
......@@ -421,7 +423,7 @@ See Documentation/ABI/testing/sysfs-kernel-livepatch for more details.
The current Livepatch implementation has several limitations:
+ Only functions that can be traced could be patched.
- Only functions that can be traced could be patched.
Livepatch is based on the dynamic ftrace. In particular, functions
implementing ftrace or the livepatch ftrace handler could not be
......@@ -431,7 +433,7 @@ The current Livepatch implementation has several limitations:
+ Livepatch works reliably only when the dynamic ftrace is located at
- Livepatch works reliably only when the dynamic ftrace is located at
the very beginning of the function.
The function need to be redirected before the stack or the function
......@@ -445,7 +447,7 @@ The current Livepatch implementation has several limitations:
this is handled on the ftrace level.
+ Kretprobes using the ftrace framework conflict with the patched
- Kretprobes using the ftrace framework conflict with the patched
functions.
Both kretprobes and livepatches use a ftrace handler that modifies
......@@ -453,7 +455,7 @@ The current Livepatch implementation has several limitations:
is rejected when the handler is already in use by the other.
+ Kprobes in the original function are ignored when the code is
- Kprobes in the original function are ignored when the code is
redirected to the new implementation.
There is a work in progress to add warnings about this situation.
......@@ -27,10 +27,13 @@ A hashtable references all shadow variables. These references are
stored and retrieved through a <obj, id> pair.
* The klp_shadow variable data structure encapsulates both tracking
meta-data and shadow-data:
meta-data and shadow-data:
- meta-data
- obj - pointer to parent object
- id - data identifier
- data[] - storage for shadow data
It is important to note that the klp_shadow_alloc() and
......@@ -47,31 +50,43 @@ to do actions that can be done only once when a new variable is allocated.
* klp_shadow_alloc() - allocate and add a new shadow variable
- search hashtable for <obj, id> pair
- if exists
- WARN and return NULL
- if <obj, id> doesn't already exist
- allocate a new shadow variable
- initialize the variable using a custom constructor and data when provided
- add <obj, id> to the global hashtable
* klp_shadow_get_or_alloc() - get existing or alloc a new shadow variable
- search hashtable for <obj, id> pair
- if exists
- return existing shadow variable
- if <obj, id> doesn't already exist
- allocate a new shadow variable
- initialize the variable using a custom constructor and data when provided
- add <obj, id> pair to the global hashtable
* klp_shadow_free() - detach and free a <obj, id> shadow variable
- find and remove a <obj, id> reference from global hashtable
- if found
- call destructor function if defined
- free shadow variable
* klp_shadow_free_all() - detach and free all <*, id> shadow variables
- find and remove any <*, id> references from global hashtable
- if found
- call destructor function if defined
- free shadow variable
......@@ -102,12 +117,12 @@ parent "goes live" (ie, any shadow variable get-API requests are made
for this <obj, id> pair.)
For commit 1d147bfa6429, when a parent sta_info structure is allocated,
allocate a shadow copy of the ps_lock pointer, then initialize it:
allocate a shadow copy of the ps_lock pointer, then initialize it::
#define PS_LOCK 1
struct sta_info *sta_info_alloc(struct ieee80211_sub_if_data *sdata,
#define PS_LOCK 1
struct sta_info *sta_info_alloc(struct ieee80211_sub_if_data *sdata,
const u8 *addr, gfp_t gfp)
{
{
struct sta_info *sta;
spinlock_t *ps_lock;
......@@ -123,10 +138,10 @@ struct sta_info *sta_info_alloc(struct ieee80211_sub_if_data *sdata,
...
When requiring a ps_lock, query the shadow variable API to retrieve one
for a specific struct sta_info:
for a specific struct sta_info:::
void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta)
{
void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta)
{
spinlock_t *ps_lock;
/* sync with ieee80211_tx_h_unicast_ps_buf */
......@@ -136,10 +151,10 @@ void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta)
...
When the parent sta_info structure is freed, first free the shadow
variable:
variable::
void sta_info_free(struct ieee80211_local *local, struct sta_info *sta)
{
void sta_info_free(struct ieee80211_local *local, struct sta_info *sta)
{
klp_shadow_free(sta, PS_LOCK, NULL);
kfree(sta);
...
......@@ -155,19 +170,19 @@ these cases, the klp_shadow_get_or_alloc() call can be used to attach
shadow variables to parents already in-flight.
For commit 1d147bfa6429, a good spot to allocate a shadow spinlock is
inside ieee80211_sta_ps_deliver_wakeup():
inside ieee80211_sta_ps_deliver_wakeup()::
int ps_lock_shadow_ctor(void *obj, void *shadow_data, void *ctor_data)
{
int ps_lock_shadow_ctor(void *obj, void *shadow_data, void *ctor_data)
{
spinlock_t *lock = shadow_data;
spin_lock_init(lock);
return 0;
}
}
#define PS_LOCK 1
void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta)
{
#define PS_LOCK 1
void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta)
{
spinlock_t *ps_lock;
/* sync with ieee80211_tx_h_unicast_ps_buf */
......@@ -200,10 +215,12 @@ suggests how to handle the parent object.
=============
* https://github.com/dynup/kpatch
The livepatch implementation is based on the kpatch version of shadow
variables.
The livepatch implementation is based on the kpatch version of shadow
variables.
* http://files.mkgnu.net/files/dynamos/doc/papers/dynamos_eurosys_07.pdf
Dynamic and Adaptive Updates of Non-Quiescent Subsystems in Commodity
Operating System Kernels (Kritis Makris, Kyung Dong Ryu 2007) presented
a datatype update technique called "shadow data structures".
Dynamic and Adaptive Updates of Non-Quiescent Subsystems in Commodity
Operating System Kernels (Kritis Makris, Kyung Dong Ryu 2007) presented
a datatype update technique called "shadow data structures".
......@@ -41,9 +41,10 @@ mainly used to perform the proper memory window initialization. Typically
there are two types of memory window interfaces supported by the NTB API:
inbound translation configured on the local ntb port and outbound translation
configured by the peer, on the peer ntb port. The first type is
depicted on the next figure
depicted on the next figure::
Inbound translation:
Inbound translation:
Memory: Local NTB Port: Peer NTB Port: Peer MMIO:
____________
| dma-mapped |-ntb_mw_set_trans(addr) |
......@@ -58,9 +59,10 @@ maps corresponding outbound memory window so to have access to the shared
memory region.
The second type of interface, that implies the shared windows being
initialized by a peer device, is depicted on the figure:
initialized by a peer device, is depicted on the figure::
Outbound translation:
Outbound translation:
Memory: Local NTB Port: Peer NTB Port: Peer MMIO:
____________ ______________
| dma-mapped | | | MW base addr |<== memory-mapped IO
......@@ -75,11 +77,13 @@ outbound memory window so to have access to the shared memory region.
As one can see the described scenarios can be combined in one portable
algorithm.
Local device:
1) Allocate memory for a shared window
2) Initialize memory window by translated address of the allocated region
(it may fail if local memory window initialization is unsupported)
3) Send the translated address and memory window index to a peer device
Peer device:
1) Initialize memory window with retrieved address of the allocated
by another device memory region (it may fail if peer memory window
......@@ -88,6 +92,7 @@ algorithm.
In accordance with this scenario, the NTB Memory Window API can be used as
follows:
Local device:
1) ntb_mw_count(pidx) - retrieve number of memory ranges, which can
be allocated for memory windows between local device and peer device
......@@ -103,6 +108,7 @@ follows:
5) Send translated base address (usually together with memory window
number) to the peer device using, for instance, scratchpad or message
registers.
Peer device:
1) ntb_peer_mw_set_trans(pidx, midx) - try to set received from other
device (related to pidx) translated address for specified memory
......
......@@ -216,10 +216,12 @@ The tags in common use are:
which can be found in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
Code without a proper signoff cannot be merged into the mainline.
- Co-developed-by: states that the patch was also created by another developer
along with the original author. This is useful at times when multiple
people work on a single patch. Note, this person also needs to have a
Signed-off-by: line in the patch as well.
- Co-developed-by: states that the patch was co-created by several developers;
it is a used to give attribution to co-authors (in addition to the author
attributed by the From: tag) when multiple people work on a single patch.
Every Co-developed-by: must be immediately followed by a Signed-off-by: of
the associated co-author. Details and examples can be found in
:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
- Acked-by: indicates an agreement by another developer (often a
maintainer of the relevant code) that the patch is appropriate for
......
......@@ -843,7 +843,8 @@ used.
The kernel provides the following general purpose memory allocators:
kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
vzalloc(). Please refer to the API documentation for further information
about them.
about them. :ref:`Documentation/core-api/memory-allocation.rst
<memory_allocation>`
The preferred form for passing a size of a struct is the following:
......@@ -874,6 +875,9 @@ The preferred form for allocating a zeroed array is the following:
Both forms check for overflow on the allocation size n * sizeof(...),
and return NULL if that occurred.
These generic allocation functions all emit a stack dump on failure when used
without __GFP_NOWARN so there is no use in emitting an additional failure
message when NULL is returned.
15) The inline disease
----------------------
......
.. SPDX-License-Identifier: GPL-2.0
.. _deprecated:
=====================================================================
Deprecated Interfaces, Language Features, Attributes, and Conventions
=====================================================================
......
......@@ -62,7 +62,7 @@ Legal Issues
The Linux kernel source code is released under the GPL. Please see the file
COPYING in the main directory of the source tree. The Linux kernel licensing
rules and how to use `SPDX <https://spdx.org/>`_ identifiers in source code are
descibed in :ref:`Documentation/process/license-rules.rst <kernel_licensing>`.
described in :ref:`Documentation/process/license-rules.rst <kernel_licensing>`.
If you have further questions about the license, please contact a lawyer, and do
not ask on the Linux kernel mailing list. The people on the mailing lists are
not lawyers, and you should not rely on their statements on legal matters.
......
......@@ -95,18 +95,6 @@ On-line docs
[...]. This paper examines some common problems for
submitting larger changes and some strategies to avoid problems.
* Title: **Overview of the Virtual File System**
:Author: Richard Gooch.
:URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt
:Date: 2007
:Keywords: VFS, File System, mounting filesystems, opening files,
dentries, dcache.
:Description: Brief introduction to the Linux Virtual File System.
What is it, how it works, operations taken when opening a file or
mounting a file system and description of important data
structures explaining the purpose of each of their entries.
* Title: **Linux Device Drivers, Third Edition**
:Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman
......
......@@ -234,13 +234,13 @@ kernel, can be broken down into:
|
2. Not recommended licenses:
2. Deprecated licenses:
These licenses should only be used for existing code or for importing
code from a different project. These licenses are available from the
directory::
LICENSES/other/
LICENSES/deprecated/
in the kernel source tree.
......@@ -250,14 +250,14 @@ kernel, can be broken down into:
Examples::
LICENSES/other/ISC
LICENSES/deprecated/ISC
Contains the Internet Systems Consortium license text and the required
metatags::
LICENSES/other/ZLib
LICENSES/deprecated/GPL-1.0
Contains the ZLIB license text and the required metatags.
Contains the GPL version 1 license text and the required metatags.
Metatags:
......@@ -281,7 +281,56 @@ kernel, can be broken down into:
|
3. _`Exceptions`:
3. Dual Licensing Only
These licenses should only be used to dual license code with another
license in addition to a preferred license. These licenses are available
from the directory::
LICENSES/dual/
in the kernel source tree.
The files in this directory contain the full license text and
`Metatags`_. The file names are identical to the SPDX license
identifier which shall be used for the license in source files.
Examples::
LICENSES/dual/MPL-1.1
Contains the Mozilla Public License version 1.1 license text and the
required metatags::
LICENSES/dual/Apache-2.0
Contains the Apache License version 2.0 license text and the required
metatags.
Metatags:
The metatag requirements for 'other' licenses are identical to the
requirements of the `Preferred licenses`_.
File format example::
Valid-License-Identifier: MPL-1.1
SPDX-URL: https://spdx.org/licenses/MPL-1.1.html
Usage-Guide:
Do NOT use. The MPL-1.1 is not GPL2 compatible. It may only be used for
dual-licensed files where the other license is GPL2 compatible.
If you end up using this it MUST be used together with a GPL2 compatible
license using "OR".
To use the Mozilla Public License version 1.1 put the following SPDX
tag/value pair into a comment according to the placement guidelines in
the licensing rules documentation:
SPDX-License-Identifier: MPL-1.1
License-Text:
Full license text
|
4. _`Exceptions`:
Some licenses can be amended with exceptions which grant certain rights
which the original license does not. These exceptions are available
......
......@@ -943,7 +943,7 @@ have on your keyring::
Next, open the `PGP pathfinder`_. In the "From" field, paste the key
fingerprint of Linus Torvalds from the output above. In the "To" field,
paste they key-id you found via ``gpg --search`` of the unknown key, and
paste the key-id you found via ``gpg --search`` of the unknown key, and
check the results:
- `Finding paths to Linus`_
......
......@@ -60,8 +60,8 @@ not in any lower subdirectory.
To create a patch for a single file, it is often sufficient to do::
SRCTREE= linux
MYFILE= drivers/net/mydriver.c
SRCTREE=linux
MYFILE=drivers/net/mydriver.c
cd $SRCTREE
cp $MYFILE $MYFILE.orig
......@@ -73,7 +73,7 @@ To create a patch for multiple files, you should unpack a "vanilla",
or unmodified kernel source tree, and generate a ``diff`` against your
own source tree. For example::
MYSRC= /devel/linux
MYSRC=/devel/linux
tar xvfz linux-3.19.tar.gz
mv linux-3.19 linux-3.19-vanilla
......@@ -545,10 +545,40 @@ person it names - but it should indicate that this person was copied on the
patch. This tag documents that potentially interested parties
have been included in the discussion.
A Co-developed-by: states that the patch was also created by another developer
along with the original author. This is useful at times when multiple people
work on a single patch. Note, this person also needs to have a Signed-off-by:
line in the patch as well.
Co-developed-by: states that the patch was co-created by multiple developers;
it is a used to give attribution to co-authors (in addition to the author
attributed by the From: tag) when several people work on a single patch. Since
Co-developed-by: denotes authorship, every Co-developed-by: must be immediately
followed by a Signed-off-by: of the associated co-author. Standard sign-off
procedure applies, i.e. the ordering of Signed-off-by: tags should reflect the
chronological history of the patch insofar as possible, regardless of whether
the author is attributed via From: or Co-developed-by:. Notably, the last
Signed-off-by: must always be that of the developer submitting the patch.
Note, the From: tag is optional when the From: author is also the person (and
email) listed in the From: line of the email header.
Example of a patch submitted by the From: author::
<changelog>
Co-developed-by: First Co-Author <first@coauthor.example.org>
Signed-off-by: First Co-Author <first@coauthor.example.org>
Co-developed-by: Second Co-Author <second@coauthor.example.org>
Signed-off-by: Second Co-Author <second@coauthor.example.org>
Signed-off-by: From Author <from@author.example.org>
Example of a patch submitted by a Co-developed-by: author::
From: From Author <from@author.example.org>
<changelog>
Co-developed-by: Random Co-Author <random@coauthor.example.org>
Signed-off-by: Random Co-Author <random@coauthor.example.org>
Signed-off-by: From Author <from@author.example.org>
Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
......@@ -696,7 +726,7 @@ A couple of example Subjects::
The ``from`` line must be the very first line in the message body,
and has the form:
From: Original Author <author@example.com>
From: Patch Author <author@example.com>
The ``from`` line specifies who will be credited as the author of the
patch in the permanent changelog. If the ``from`` line is missing,
......
......@@ -136,5 +136,5 @@ a high functionality RTC is integrated into the SOC. That system might read
the system clock from the discrete RTC, but use the integrated one for all
other tasks, because of its greater functionality.
Check out tools/testing/selftests/timers/rtctest.c for an example usage of the
Check out tools/testing/selftests/rtc/rtctest.c for an example usage of the
ioctl interface.
......@@ -17,7 +17,7 @@ observed to extract secret information.
For example, in the presence of branch prediction, it is possible for bounds
checks to be ignored by code which is speculatively executed. Consider the
following code:
following code::
int load_array(int *array, unsigned int index)
{
......@@ -27,7 +27,7 @@ following code:
return array[index];
}
Which, on arm64, may be compiled to an assembly sequence such as:
Which, on arm64, may be compiled to an assembly sequence such as::
CMP <index>, #MAX_ARRAY_ELEMS
B.LT less
......@@ -44,7 +44,7 @@ microarchitectural state which can be subsequently measured.
More complex sequences involving multiple dependent memory accesses may
result in sensitive information being leaked. Consider the following
code, building on the prior example:
code, building on the prior example::
int load_dependent_arrays(int *arr1, int *arr2, int index)
{
......@@ -77,7 +77,7 @@ A call to array_index_nospec(index, size) returns a sanitized index
value that is bounded to [0, size) even under cpu speculation
conditions.
This can be used to protect the earlier load_array() example:
This can be used to protect the earlier load_array() example::
int load_array(int *array, unsigned int index)
{
......
......@@ -196,7 +196,7 @@ CAP_LAST_CAP from the kernel.
core_pattern:
core_pattern is used to specify a core dumpfile pattern name.
. max length 128 characters; default value is "core"
. max length 127 characters; default value is "core"
. core_pattern is used as a pattern template for the output filename;
certain string patterns (beginning with '%') are substituted with
their actual values.
......
......@@ -1404,6 +1404,7 @@ trace has provided some very helpful debugging information.
If we prefer function graph output instead of function, we can set
display-graph option::
with echo 1 > options/display-graph
# tracer: irqsoff
......
......@@ -2133,7 +2133,7 @@ The following commonly-used handler.action pairs are available:
the end the event that triggered the snapshot (in this case you
can verify the timestamps between the sched_waking and
sched_switch events, which should match the time displayed in the
global maximum):
global maximum)::
# cat /sys/kernel/debug/tracing/snapshot
......@@ -2213,9 +2213,10 @@ The following commonly-used handler.action pairs are available:
following the rest of the fields.
If a snaphot was taken, there is also a message indicating that,
along with the value and event that triggered the snapshot:
along with the value and event that triggered the snapshot::
# cat /sys/kernel/debug/tracing/events/tcp/tcp_probe/hist
{ dport: 1521 } hitcount: 8
changed: 10 snd_wnd: 35456 srtt: 154262 rcv_wnd: 42112
......@@ -2228,7 +2229,8 @@ The following commonly-used handler.action pairs are available:
{ dport: 443 } hitcount: 211
changed: 10 snd_wnd: 26960 srtt: 17379 rcv_wnd: 28800
Snapshot taken (see tracing/snapshot). Details:
Snapshot taken (see tracing/snapshot). Details::
triggering value { onchange($cwnd) }: 10
triggered by event with key: { dport: 80 }
......@@ -2245,7 +2247,7 @@ The following commonly-used handler.action pairs are available:
the global snapshot).
And finally, looking at the snapshot data should show at or near
the end the event that triggered the snapshot:
the end the event that triggered the snapshot::
# cat /sys/kernel/debug/tracing/snapshot
......
......@@ -11,3 +11,43 @@ Translations
it_IT/index
ko_KR/index
ja_JP/index
.. _translations_disclaimer:
Disclaimer
----------
Translation's purpose is to ease reading and understanding in languages other
than English. Its aim is to help people who do not understand English or have
doubts about its interpretation. Additionally, some people prefer to read
documentation in their native language, but please bear in mind that the
*only* official documentation is the English one: :ref:`linux_doc`.
It is very unlikely that an update to :ref:`linux_doc` will be propagated
immediately to all translations. Translations' maintainers - and
contributors - follow the evolution of the official documentation and they
maintain translations aligned as much as they can. For this reason there is
no guarantee that a translation is up to date. If what you read in a
translation does not sound right compared to what you read in the code, please
inform the translation maintainer and - if you can - check also the English
documentation.
A translation is not a fork of the official documentation, therefore
translations' users should not find information that differs from the official
English documentation. Any content addition, removal or update, must be
applied to the English documents first. Afterwards and when possible, the
same change should be applied to translations. Translations' maintainers
accept only contributions that are merely translation related (e.g. new
translations, updates, fixes).
Translations try to be as accurate as possible but it is not possible to map
one language directly to all other languages. Each language has its own
grammar and culture, so the translation of an English statement may need to be
adapted to fit a different language. For this reason, when viewing
translations, you may find slight differences that carry the same message but
in a different form.
If you need to communicate with the Linux community but you do not feel
comfortable writing in English, you can ask the translation's maintainers
for help.
.. include:: ../disclaimer-ita.rst
:Original: :ref:`Documentation/core-api/memory-allocation.rst <memory_allocation>`
.. _it_memory_allocation:
================================
Guida all'allocazione di memoria
================================
.. warning::
TODO ancora da tradurre
:orphan:
.. note::
This document is maintained by Federico Vaga <federico.vaga@vaga.pv.it>.
If you find any difference between this document and the original file or a
problem with the translation, please contact the maintainer of this file.
Following people helped to translate or review:
Alessia Mantegazza <amantegazza@vaga.pv.it>
.. warning::
The purpose of this file is to be easier to read and understand for Italian
speakers and is not intended as a fork. So, if you have any comments or
updates for this file please try to update the original English file first.
In caso di dubbi sulla correttezza del contenuto di questa traduzione,
l'unico riferimento valido è la documentazione ufficiale in inglese.
Per maggiori informazioni consultate le :ref:`avvertenze <it_disclaimer>`.
......@@ -12,9 +12,9 @@ Come scrivere la documentazione del kernel
.. toctree::
:maxdepth: 1
sphinx.rst
kernel-doc.rst
parse-headers.rst
sphinx
kernel-doc
parse-headers
.. only:: subproject and html
......
......@@ -4,26 +4,49 @@
Traduzione italiana
===================
L'obiettivo di questa traduzione è di rendere più facile la lettura e
la comprensione per chi preferisce leggere in lingua italiana.
Tenete presente che la documentazione di riferimento rimane comunque
quella in lingua inglese: :ref:`linux_doc`
Questa traduzione cerca di essere il più fedele possibile all'originale ma
è ovvio che alcune frasi vadano trasformate: non aspettatevi una traduzione
letterale. Quando possibile, si eviteranno gli inglesismi ed al loro posto
verranno utilizzate le corrispettive parole italiane.
:manutentore: Federico Vaga <federico.vaga@vaga.pv.it>
Se notate che la traduzione non è più aggiornata potete contattare
direttamente il manutentore della traduzione italiana.
.. _it_disclaimer:
Se notate che la documentazione contiene errori o dimenticanze, allora
verificate la documentazione di riferimento in lingua inglese. Se il problema
è presente anche nella documentazione di riferimento, contattate il suo
manutentore. Se avete problemi a scrivere in inglese, potete comunque
riportare il problema al manutentore della traduzione italiana.
Avvertenze
==========
Manutentore della traduzione italiana: Federico Vaga <federico.vaga@vaga.pv.it>
L'obiettivo di questa traduzione è di rendere più facile la lettura e
la comprensione per chi non capisce l'inglese o ha dubbi sulla sua
interpretazione, oppure semplicemente per chi preferisce leggere in lingua
italiana. Tuttavia, tenete ben presente che l'*unica* documentazione
ufficiale è quella in lingua inglese: :ref:`linux_doc`
La propagazione simultanea a tutte le traduzioni di una modifica in
:ref:`linux_doc` è altamente improbabile. I manutentori delle traduzioni -
e i contributori - seguono l'evolversi della documentazione ufficiale e
cercano di mantenere le rispettive traduzioni allineate nel limite del
possibile. Per questo motivo non c'è garanzia che una traduzione sia
aggiornata all'ultima modifica. Se quello che leggete in una traduzione
non corrisponde a quello che leggete nel codice, informate il manutentore
della traduzione e - se potete - verificate anche la documentazione in
inglese.
Una traduzione non è un *fork* della documentazione ufficiale, perciò gli
utenti non vi troveranno alcuna informazione diversa rispetto alla versione
ufficiale. Ogni aggiunta, rimozione o modifica dei contenuti deve essere
fatta prima nei documenti in inglese. In seguito, e quando è possibile, la
stessa modifica dovrebbe essere applicata anche alle traduzioni. I manutentori
delle traduzioni accettano contributi che interessano prettamente l'attività
di traduzione (per esempio, nuove traduzioni, aggiornamenti, correzioni).
Le traduzioni cercano di essere il più possibile accurate ma non è possibile
mappare direttamente una lingua in un'altra. Ogni lingua ha la sua grammatica
e una sua cultura alle spalle, quindi la traduzione di una frase in inglese
potrebbe essere modificata per adattarla all'italiano. Per questo motivo,
quando leggete questa traduzione, potreste trovare alcune differenze di forma
ma che trasmettono comunque il messaggio originale. Nonostante la grande
diffusione di inglesismi nella lingua parlata, quando possibile, questi
verranno sostituiti dalle corrispettive parole italiane
Se avete bisogno d'aiuto per comunicare con la comunità Linux ma non vi sentite
a vostro agio nello scrivere in inglese, potete chiedere aiuto al manutentore
della traduzione.
La documentazione del kernel Linux
==================================
......@@ -47,9 +70,7 @@ I seguenti documenti descrivono la licenza usata nei sorgenti del kernel Linux
(GPLv2), come licenziare i singoli file; inoltre troverete i riferimenti al
testo integrale della licenza.
.. warning::
TODO ancora da tradurre
* :ref:`it_kernel_licensing`
Documentazione per gli utenti
-----------------------------
......@@ -90,10 +111,6 @@ vostre modifiche molto più semplice
doc-guide/index
kernel-hacking/index
.. warning::
TODO ancora da tradurre
Documentazione della API del kernel
-----------------------------------
......
.. include:: ../disclaimer-ita.rst
:Original: :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
.. _it_netdev-FAQ:
==========
netdev FAQ
==========
.. warning::
TODO ancora da tradurre
......@@ -233,10 +233,12 @@ Le etichette in uso più comuni sono:
:ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
Codice che non presenta una firma appropriata non potrà essere integrato.
- Co-developed-by: indica che la patch è stata sviluppata anche da un altro
sviluppatore assieme all'autore originale. Questo è utile quando più
persone lavorano sulla stessa patch. Da notare che questa persona deve
avere anche una riga "Signed-off-by:" nella patch.
- Co-developed-by: indica che la patch è stata cosviluppata da diversi
sviluppatori; viene usato per assegnare più autori (in aggiunta a quello
associato all'etichetta From:) quando più persone lavorano ad una patch.
Ogni Co-developed-by: dev'essere seguito immediatamente da un Signed-off-by:
del corrispondente coautore. Maggiori dettagli ed esempi sono disponibili
in :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
- Acked-by: indica il consenso di un altro sviluppatore (spesso il manutentore
del codice in oggetto) all'integrazione della patch nel kernel.
......
......@@ -859,7 +859,8 @@ racchiusa in #ifdef, potete usare printk(KERN_DEBUG ...).
Il kernel fornisce i seguenti assegnatori ad uso generico:
kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), e vzalloc().
Per maggiori informazioni, consultate la documentazione dell'API.
Per maggiori informazioni, consultate la documentazione dell'API:
:ref:`Documentation/translations/it_IT/core-api/memory-allocation.rst <it_memory_allocation>`
Il modo preferito per passare la dimensione di una struttura è il seguente:
......@@ -890,6 +891,11 @@ Il modo preferito per assegnare un vettore a zero è il seguente:
Entrambe verificano la condizione di overflow per la dimensione
d'assegnamento n * sizeof(...), se accade ritorneranno NULL.
Questi allocatori generici producono uno *stack dump* in caso di fallimento
a meno che non venga esplicitamente specificato __GFP_NOWARN. Quindi, nella
maggior parte dei casi, è inutile stampare messaggi aggiuntivi quando uno di
questi allocatori ritornano un puntatore NULL.
15) Il morbo inline
-------------------
......
.. SPDX-License-Identifier: GPL-2.0
.. include:: ../disclaimer-ita.rst
:Original: :ref:`Documentation/process/deprecated.rst <deprecated>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>
.. _it_deprecated:
==============================================================================
Interfacce deprecate, caratteristiche del linguaggio, attributi, e convenzioni
==============================================================================
In un mondo perfetto, sarebbe possibile prendere tutti gli usi di
un'interfaccia deprecata e convertirli in quella nuova, e così sarebbe
possibile rimuovere la vecchia interfaccia in un singolo ciclo di sviluppo.
Tuttavia, per via delle dimensioni del kernel, la gerarchia dei manutentori e
le tempistiche, non è sempre possibile fare questo tipo di conversione tutta
in una volta. Questo significa che nuove istanze di una vecchia interfaccia
potrebbero aggiungersi al kernel proprio quando si sta cercando di rimuoverle,
aumentando così il carico di lavoro. Al fine di istruire gli sviluppatori su
cosa è considerato deprecato (e perché), è stata create la seguente lista a cui
fare riferimento quando qualcuno propone modifiche che usano cose deprecate.
__deprecated
------------
Nonostante questo attributo marchi visibilmente un interfaccia come deprecata,
`non produce più alcun avviso durante la compilazione
<https://git.kernel.org/linus/771c035372a036f83353eef46dbb829780330234>`_
perché uno degli obiettivi del kernel è quello di compilare senza avvisi;
inoltre, nessuno stava agendo per rimuovere queste interfacce. Nonostante l'uso
di `__deprecated` in un file d'intestazione sia opportuno per segnare una
interfaccia come 'vecchia', questa non è una soluzione completa. L'interfaccia
deve essere rimossa dal kernel, o aggiunta a questo documento per scoraggiarne
l'uso.
Calcoli codificati negli argomenti di un allocatore
----------------------------------------------------
Il calcolo dinamico delle dimensioni (specialmente le moltiplicazioni) non
dovrebbero essere fatto negli argomenti di funzioni di allocazione di memoria
(o simili) per via del rischio di overflow. Questo può portare a valori più
piccoli di quelli che il chiamante si aspettava. L'uso di questo modo di
allocare può portare ad un overflow della memoria di heap e altri
malfunzionamenti. (Si fa eccezione per valori numerici per i quali il
compilatore può generare avvisi circa un potenziale overflow. Tuttavia usare
i valori numerici come suggerito di seguito è innocuo).
Per esempio, non usate ``count * size`` come argomento::
foo = kmalloc(count * size, GFP_KERNEL);
Al suo posto, si dovrebbe usare l'allocatore a due argomenti::
foo = kmalloc_array(count, size, GFP_KERNEL);
Se questo tipo di allocatore non è disponibile, allora dovrebbero essere usate
le funzioni del tipo *saturate-on-overflow*::
bar = vmalloc(array_size(count, size));
Un altro tipico caso da evitare è quello di calcolare la dimensione di una
struttura seguita da un vettore di altre strutture, come nel seguente caso::
header = kzalloc(sizeof(*header) + count * sizeof(*header->item),
GFP_KERNEL);
Invece, usate la seguente funzione::
header = kzalloc(struct_size(header, item, count), GFP_KERNEL);
Per maggiori dettagli fate riferimento a :c:func:`array_size`,
:c:func:`array3_size`, e :c:func:`struct_size`, così come la famiglia di
funzioni :c:func:`check_add_overflow` e :c:func:`check_mul_overflow`.
simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull()
----------------------------------------------------------------------
Le funzioni :c:func:`simple_strtol`, :c:func:`simple_strtoll`,
:c:func:`simple_strtoul`, e :c:func:`simple_strtoull` ignorano volutamente
i possibili overflow, e questo può portare il chiamante a generare risultati
inaspettati. Le rispettive funzioni :c:func:`kstrtol`, :c:func:`kstrtoll`,
:c:func:`kstrtoul`, e :c:func:`kstrtoull` sono da considerarsi le corrette
sostitute; tuttavia va notato che queste richiedono che la stringa sia
terminata con il carattere NUL o quello di nuova riga.
strcpy()
--------
La funzione :c:func:`strcpy` non fa controlli agli estremi del buffer
di destinazione. Questo può portare ad un overflow oltre i limiti del
buffer e generare svariati tipi di malfunzionamenti. Nonostante l'opzione
`CONFIG_FORTIFY_SOURCE=y` e svariate opzioni del compilatore aiutano
a ridurne il rischio, non c'è alcuna buona ragione per continuare ad usare
questa funzione. La versione sicura da usare è :c:func:`strscpy`.
strncpy() su stringe terminate con NUL
--------------------------------------
L'utilizzo di :c:func:`strncpy` non fornisce alcuna garanzia sul fatto che
il buffer di destinazione verrà terminato con il carattere NUL. Questo
potrebbe portare a diversi overflow di lettura o altri malfunzionamenti
causati, appunto, dalla mancanza del terminatore. Questa estende la
terminazione nel buffer di destinazione quando la stringa d'origine è più
corta; questo potrebbe portare ad una penalizzazione delle prestazioni per
chi usa solo stringe terminate. La versione sicura da usare è
:c:func:`strscpy`. (chi usa :c:func:`strscpy` e necessita di estendere la
terminazione con NUL deve aggiungere una chiamata a :c:func:`memset`)
Se il chiamate no usa stringhe terminate con NUL, allore :c:func:`strncpy()`
può continuare ad essere usata, ma i buffer di destinazione devono essere
marchiati con l'attributo `__nonstring <https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_
per evitare avvisi durante la compilazione.
strlcpy()
---------
La funzione :c:func:`strlcpy`, per prima cosa, legge interamente il buffer di
origine, magari leggendo più di quanto verrà effettivamente copiato. Questo
è inefficiente e può portare a overflow di lettura quando la stringa non è
terminata con NUL. La versione sicura da usare è :c:func:`strscpy`.
Vettori a dimensione variabile (VLA)
------------------------------------
Usare VLA sullo stack produce codice molto peggiore rispetto a quando si usano
vettori a dimensione fissa. Questi `problemi di prestazioni <https://git.kernel.org/linus/02361bc77888>`_,
tutt'altro che banali, sono già un motivo valido per eliminare i VLA; in
aggiunta sono anche un problema per la sicurezza. La crescita dinamica di un
vettore nello stack potrebbe eccedere la memoria rimanente in tale segmento.
Questo può portare a dei malfunzionamenti, potrebbe sovrascrivere
dati importanti alla fine dello stack (quando il kernel è compilato senza
`CONFIG_THREAD_INFO_IN_TASK=y`), o sovrascrivere un pezzo di memoria adiacente
allo stack (quando il kernel è compilato senza `CONFIG_VMAP_STACK=y`).
.. include:: ../disclaimer-ita.rst
:Original: :ref:`Documentation/process/kernel-enforcement-statement.rst <process_statement_kernel>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>
.. _it_process_statement_kernel:
Applicazione della licenza sul kernel Linux
===========================================
.. warning::
Come sviluppatori del kernel Linux, abbiamo un certo interessa su come il
nostro software viene usato e su come la sua licenza viene fatta rispettare.
Il rispetto reciproco degli obblighi di condivisione della GPL-2.0 è
fondamentale per la sostenibilità di lungo periodo del nostro software e
della nostra comunità.
Benché ognuno abbia il diritto a far rispettare il diritto d'autore per i
propri contributi alla nostra comunità, condividiamo l'interesse a far si che
ogni azione individuale nel far rispettare i propri diritti sia condotta in
modo da portare beneficio alla comunità e che non abbia, involontariamente,
impatti negativi sulla salute e la crescita del nostro ecosistema software.
Al fine di scoraggiare l'esecuzione di azioni inutili, concordiamo che è nel
migliore interesse della nostra comunità di sviluppo di impegnarci nel
rispettare i seguenti obblighi nei confronti degli utenti del kernel Linux
per conto nostro e di qualsiasi successore ai nostri interessi sul diritto
d'autore:
Malgrado le clausole di risoluzione della licenza GPL-2.0, abbiamo
concordato che è nel migliore interesse della nostra comunità di sviluppo
adottare le seguenti disposizioni della GPL-3.0 come permessi aggiuntivi
alla nostra licenza nei confronti di qualsiasi affermazione non difensiva
di diritti sulla licenza.
In ogni caso, se cessano tutte le violazioni di questa Licenza, allora
la tua licenza da parte di un dato detentore del copyright viene
ripristinata (a) in via cautelativa, a meno che e fino a quando il
detentore del copyright non cessa esplicitamente e definitivamente
la tua licenza, e (b) in via permanente se il detentore del copyright
non ti notifica in alcun modo la violazione entro 60 giorni dalla
cessazione della licenza.
Inoltre, la tua licenza da parte di un dato detentore del copyright
viene ripristinata in maniera permanente se il detentore del copyright
ti notifica la violazione in maniera adeguata, se questa è la prima
volta che ricevi una notifica di violazione di questa Licenza (per
qualunque Programma) dallo stesso detentore di copyright, e se rimedi
alla violazione entro 30 giorni dalla data di ricezione della notifica
di violazione.
Fornendo queste garanzie, abbiamo l'intenzione di incoraggiare l'uso del
software. Vogliamo che le aziende e le persone usino, modifichino e
distribuiscano a questo software. Vogliamo lavorare con gli utenti in modo
aperto e trasparente per eliminare ogni incertezza circa le nostre aspettative
sul rispetto o l'ottemperanza alla licenza che possa limitare l'uso del nostro
software. Vediamo l'azione legale come ultima spiaggia, da avviare solo quando
gli altri sforzi della comunità hanno fallito nel risolvere il problema.
Per finire, una volta che un problema di non rispetto della licenza viene
risolto, speriamo che gli utenti si sentano i benvenuti ad aggregarsi a noi
nello sviluppo di questo progetto. Lavorando assieme, saremo più forti.
Ad eccezione deve specificato, parliamo per noi stessi, e non per una qualsiasi
azienda per la quale lavoriamo oggi, o per cui abbiamo lavorato in passato, o
lavoreremo in futuro.
TODO ancora da tradurre
- Laura Abbott
- Bjorn Andersson (Linaro)
- Andrea Arcangeli
- Neil Armstrong
- Jens Axboe
- Pablo Neira Ayuso
- Khalid Aziz
- Ralf Baechle
- Felipe Balbi
- Arnd Bergmann
- Ard Biesheuvel
- Tim Bird
- Paolo Bonzini
- Christian Borntraeger
- Mark Brown (Linaro)
- Paul Burton
- Javier Martinez Canillas
- Rob Clark
- Kees Cook (Google)
- Jonathan Corbet
- Dennis Dalessandro
- Vivien Didelot (Savoir-faire Linux)
- Hans de Goede
- Mel Gorman (SUSE)
- Sven Eckelmann
- Alex Elder (Linaro)
- Fabio Estevam
- Larry Finger
- Bhumika Goyal
- Andy Gross
- Juergen Gross
- Shawn Guo
- Ulf Hansson
- Stephen Hemminger (Microsoft)
- Tejun Heo
- Rob Herring
- Masami Hiramatsu
- Michal Hocko
- Simon Horman
- Johan Hovold (Hovold Consulting AB)
- Christophe JAILLET
- Olof Johansson
- Lee Jones (Linaro)
- Heiner Kallweit
- Srinivas Kandagatla
- Jan Kara
- Shuah Khan (Samsung)
- David Kershner
- Jaegeuk Kim
- Namhyung Kim
- Colin Ian King
- Jeff Kirsher
- Greg Kroah-Hartman (Linux Foundation)
- Christian König
- Vinod Koul
- Krzysztof Kozlowski
- Viresh Kumar
- Aneesh Kumar K.V
- Julia Lawall
- Doug Ledford
- Chuck Lever (Oracle)
- Daniel Lezcano
- Shaohua Li
- Xin Long
- Tony Luck
- Catalin Marinas (Arm Ltd)
- Mike Marshall
- Chris Mason
- Paul E. McKenney
- Arnaldo Carvalho de Melo
- David S. Miller
- Ingo Molnar
- Kuninori Morimoto
- Trond Myklebust
- Martin K. Petersen (Oracle)
- Borislav Petkov
- Jiri Pirko
- Josh Poimboeuf
- Sebastian Reichel (Collabora)
- Guenter Roeck
- Joerg Roedel
- Leon Romanovsky
- Steven Rostedt (VMware)
- Frank Rowand
- Ivan Safonov
- Anna Schumaker
- Jes Sorensen
- K.Y. Srinivasan
- David Sterba (SUSE)
- Heiko Stuebner
- Jiri Kosina (SUSE)
- Willy Tarreau
- Dmitry Torokhov
- Linus Torvalds
- Thierry Reding
- Rik van Riel
- Luis R. Rodriguez
- Geert Uytterhoeven (Glider bvba)
- Eduardo Valentin (Amazon.com)
- Daniel Vetter
- Linus Walleij
- Richard Weinberger
- Dan Williams
- Rafael J. Wysocki
- Arvind Yadav
- Masahiro Yamada
- Wei Yongjun
- Lv Zheng
- Marc Zyngier (Arm Ltd)
This diff is collapsed.
.. include:: ../disclaimer-ita.rst
:Original: :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>
.. _it_stable_kernel_rules:
Tutto quello che volevate sapere sui rilasci -stable di Linux
==============================================================
.. warning::
Regole sul tipo di patch che vengono o non vengono accettate nei sorgenti
"-stable":
TODO ancora da tradurre
- Ovviamente dev'essere corretta e verificata.
- Non dev'essere più grande di 100 righe, incluso il contesto.
- Deve correggere una cosa sola.
- Deve correggere un baco vero che sta disturbando gli utenti (non cose del
tipo "Questo potrebbe essere un problema ...").
- Deve correggere un problema di compilazione (ma non per cose già segnate
con CONFIG_BROKEN), un kernel oops, un blocco, una corruzione di dati,
un vero problema di sicurezza, o problemi del tipo "oh, questo non va bene".
In pratica, qualcosa di critico.
- Problemi importanti riportati dagli utenti di una distribuzione potrebbero
essere considerati se correggono importanti problemi di prestazioni o di
interattività. Dato che questi problemi non sono così ovvi e la loro
correzione ha un'alta probabilità d'introdurre una regressione, dovrebbero
essere sottomessi solo dal manutentore della distribuzione includendo un
link, se esiste, ad un rapporto su bugzilla, e informazioni aggiuntive
sull'impatto che ha sugli utenti.
- Non deve correggere problemi relativi a una "teorica sezione critica",
a meno che non venga fornita anche una spiegazione su come questa si
possa verificare.
- Non deve includere alcuna correzione "banale" (correzioni grammaticali,
pulizia dagli spazi bianchi, eccetera).
- Deve rispettare le regole scritte in
:ref:`Documentation/translation/it_IT/process/submitting-patches.rst <it_submittingpatches>`
- Questa patch o una equivalente deve esistere già nei sorgenti principali di
Linux
Procedura per sottomettere patch per i sorgenti -stable
-------------------------------------------------------
- Se la patch contiene modifiche a dei file nelle cartelle net/ o drivers/net,
allora seguite le linee guida descritte in
:ref:`Documentation/translation/it_IT/networking/netdev-FAQ.rst <it_netdev-FAQ>`;
ma solo dopo aver verificato al seguente indirizzo che la patch non sia
già in coda:
https://patchwork.ozlabs.org/bundle/davem/stable/?series=&submitter=&state=*&q=&archive=
- Una patch di sicurezza non dovrebbero essere gestite (solamente) dal processo
di revisione -stable, ma dovrebbe seguire le procedure descritte in
:ref:`Documentation/translations/it_IT/admin-guide/security-bugs.rst <it_securitybugs>`.
Per tutte le altre sottomissioni, scegliere una delle seguenti procedure
------------------------------------------------------------------------
.. _it_option_1:
Opzione 1
*********
Per far sì che una patch venga automaticamente inclusa nei sorgenti stabili,
aggiungete l'etichetta
.. code-block:: none
Cc: stable@vger.kernel.org
nell'area dedicata alla firme. Una volta che la patch è stata inclusa, verrà
applicata anche sui sorgenti stabili senza che l'autore o il manutentore
del sottosistema debba fare qualcosa.
.. _it_option_2:
Opzione 2
*********
Dopo che la patch è stata inclusa nei sorgenti Linux, inviate una mail a
stable@vger.kernel.org includendo: il titolo della patch, l'identificativo
del commit, il perché pensate che debba essere applicata, e in quale versione
del kernel la vorreste vedere.
.. _it_option_3:
Opzione 3
*********
Inviata la patch, dopo aver verificato che rispetta le regole descritte in
precedenza, a stable@vger.kernel.org. Dovete annotare nel changelog
l'identificativo del commit nei sorgenti principali, così come la versione
del kernel nel quale vorreste vedere la patch.
L':ref:`it_option_1` è fortemente raccomandata; è il modo più facile e usato.
L':ref:`it_option_2` e l':ref:`it_option_3` sono più utili quando, al momento
dell'inclusione dei sorgenti principali, si ritiene che non debbano essere
incluse anche in quelli stabili (per esempio, perché si crede che si dovrebbero
fare più verifiche per eventuali regressioni). L':ref:`it_option_3` è
particolarmente utile se la patch ha bisogno di qualche modifica per essere
applicata ad un kernel più vecchio (per esempio, perché nel frattempo l'API è
cambiata).
Notate che per l':ref:`it_option_3`, se la patch è diversa da quella nei
sorgenti principali (per esempio perché è stato necessario un lavoro di
adattamento) allora dev'essere ben documentata e giustificata nella descrizione
della patch.
L'identificativo del commit nei sorgenti principali dev'essere indicato sopra
al messaggio della patch, così:
.. code-block:: none
commit <sha1> upstream.
In aggiunta, alcune patch inviate attraverso l':ref:`it_option_1` potrebbero
dipendere da altre che devo essere incluse. Questa situazione può essere
indicata nel seguente modo nell'area dedicata alle firme:
.. code-block:: none
Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle
Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle
Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic
Cc: <stable@vger.kernel.org> # 3.3.x
Signed-off-by: Ingo Molnar <mingo@elte.hu>
La sequenza di etichette ha il seguente significato:
.. code-block:: none
git cherry-pick a1f84a3
git cherry-pick 1b9508f
git cherry-pick fd21073
git cherry-pick <this commit>
Inoltre, alcune patch potrebbero avere dei requisiti circa la versione del
kernel. Questo può essere indicato usando il seguente formato nell'area
dedicata alle firme:
.. code-block:: none
Cc: <stable@vger.kernel.org> # 3.3.x
L'etichetta ha il seguente significato:
.. code-block:: none
git cherry-pick <this commit>
per ogni sorgente "-stable" che inizia con la versione indicata.
Dopo la sottomissione:
- Il mittente riceverà un ACK quando la patch è stata accettata e messa in
coda, oppure un NAK se la patch è stata rigettata. A seconda degli impegni
degli sviluppatori, questa risposta potrebbe richiedere alcuni giorni.
- Se accettata, la patch verrà aggiunta alla coda -stable per essere
revisionata dal altri sviluppatori e dal principale manutentore del
sottosistema.
Ciclo di una revisione
----------------------
- Quando i manutentori -stable decidono di fare un ciclo di revisione, le
patch vengono mandate al comitato per la revisione, ai manutentori soggetti
alle modifiche delle patch (a meno che il mittente non sia anche il
manutentore di quell'area del kernel) e in CC: alla lista di discussione
linux-kernel.
- La commissione per la revisione ha 48 ore per dare il proprio ACK o NACK
alle patch.
- Se una patch viene rigettata da un membro della commissione, o un membro
della lista linux-kernel obietta la bontà della patch, sollevando problemi
che i manutentori ed i membri non avevano compreso, allora la patch verrà
rimossa dalla coda.
- Alla fine del ciclo di revisione tutte le patch che hanno ricevuto l'ACK
verranno aggiunte per il prossimo rilascio -stable, e successivamente
questo nuovo rilascio verrà fatto.
- Le patch di sicurezza verranno accettate nei sorgenti -stable direttamente
dalla squadra per la sicurezza del kernel, e non passerà per il normale
ciclo di revisione. Contattate la suddetta squadra per maggiori dettagli
su questa procedura.
Sorgenti
--------
- La coda delle patch, sia quelle già applicate che in fase di revisione,
possono essere trovate al seguente indirizzo:
https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git
- Il rilascio definitivo, e marchiato, di tutti i kernel stabili può essere
trovato in rami distinti per versione al seguente indirizzo:
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git
Comitato per la revisione
-------------------------
- Questo comitato è fatto di sviluppatori del kernel che si sono offerti
volontari per questo lavoro, e pochi altri che non sono proprio volontari.
......@@ -67,8 +67,8 @@ sulla radice dei sorgenti del kernel, e non sulle sue sottocartelle.
Per creare una patch per un singolo file, spesso è sufficiente fare::
SRCTREE= linux
MYFILE= drivers/net/mydriver.c
SRCTREE=linux
MYFILE=drivers/net/mydriver.c
cd $SRCTREE
cp $MYFILE $MYFILE.orig
......@@ -80,7 +80,7 @@ Per creare una patch per molteplici file, dovreste spacchettare i sorgenti
"vergini", o comunque non modificati, e fare un ``diff`` coi vostri.
Per esempio::
MYSRC= /devel/linux
MYSRC=/devel/linux
tar xvfz linux-3.19.tar.gz
mv linux-3.19 linux-3.19-vanilla
......@@ -567,11 +567,42 @@ alcunché - ma dovrebbe indicare che la persona ha ricevuto una copia della
patch. Questa etichetta documenta che terzi potenzialmente interessati sono
stati inclusi nella discussione.
L'etichetta Co-developed-by: indica che la patch è stata scritta dall'autore in
collaborazione con un altro sviluppatore. Qualche volta questo è utile quando
più persone lavorano sulla stessa patch. Notate, questa persona deve avere
nella patch anche una riga Signed-off-by:.
Co-developed-by: indica che la patch è stata cosviluppata da diversi
sviluppatori; viene usato per assegnare più autori (in aggiunta a quello
associato all'etichetta From:) quando più persone lavorano ad una patch. Dato
che Co-developed-by: implica la paternità della patch, ogni Co-developed-by:
dev'essere seguito immediatamente dal Signed-off-by: del corrispondente
coautore. Qui si applica la procedura di base per sign-off, in pratica
l'ordine delle etichette Signed-off-by: dovrebbe riflettere il più possibile
l'ordine cronologico della storia della patch, indipendentemente dal fatto che
la paternità venga assegnata via From: o Co-developed-by:. Da notare che
l'ultimo Signed-off-by: dev'essere quello di colui che ha sottomesso la patch.
Notate anche che l'etichetta From: è opzionale quando l'autore in From: è
anche la persona (e indirizzo email) indicato nel From: dell'intestazione
dell'email.
Esempio di una patch sottomessa dall'autore in From:::
<changelog>
Co-developed-by: First Co-Author <first@coauthor.example.org>
Signed-off-by: First Co-Author <first@coauthor.example.org>
Co-developed-by: Second Co-Author <second@coauthor.example.org>
Signed-off-by: Second Co-Author <second@coauthor.example.org>
Signed-off-by: From Author <from@author.example.org>
Esempio di una patch sottomessa dall'autore Co-developed-by:::
From: From Author <from@author.example.org>
<changelog>
Co-developed-by: Random Co-Author <random@coauthor.example.org>
Signed-off-by: Random Co-Author <random@coauthor.example.org>
Signed-off-by: From Author <from@author.example.org>
Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
13) Utilizzare Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes:
-----------------------------------------------------------------------------
......@@ -719,7 +750,7 @@ Un paio di esempi di oggetti::
La riga ``from`` dev'essere la prima nel corpo del messaggio ed è nel
formato:
From: Original Author <author@example.com>
From: Patch Author <author@example.com>
La riga ``from`` indica chi verrà accreditato nel changelog permanente come
l'autore della patch. Se la riga ``from`` è mancante, allora per determinare
......
......@@ -58,8 +58,8 @@ Linux カーネルに対する全ての変更は diff(1) コマンドによる
1個のファイルについてのパッチを作成するためには、ほとんどの場合、
以下の作業を行えば十分です。
SRCTREE= linux-2.6
MYFILE= drivers/net/mydriver.c
SRCTREE=linux-2.6
MYFILE=drivers/net/mydriver.c
cd $SRCTREE
cp $MYFILE $MYFILE.orig
......@@ -71,7 +71,7 @@ Linux カーネルに対する全ての変更は diff(1) コマンドによる
なわち変更を加えてない Linux カーネルを展開し、自分の Linux カーネル
ソースとの差分を生成しないといけません。例えば、
MYSRC= /devel/linux-2.6
MYSRC=/devel/linux-2.6
tar xvfz linux-2.6.12.tar.gz
mv linux-2.6.12 linux-2.6.12-vanilla
......
This diff is collapsed.
:orphan:
.. warning::
此文件的目的是为让中文读者更容易阅读和理解,而不是作为一个分支。 因此,
如果您对此文件有任何意见或更新,请先尝试更新原始英文文件。
.. note::
如果您发现本文档与原始文件有任何不同或者有翻译问题,请联系该文件的译者,
或者请求时奎亮的帮助:<alex.shi@linux.alibaba.com>。
......@@ -3,10 +3,19 @@
\renewcommand\thesection*
\renewcommand\thesubsection*
Chinese translations
====================
中文翻译
========
这些手册包含有关如何开发内核的整体信息。内核社区非常庞大,一年下来有数千名开发
人员做出贡献。 与任何大型社区一样,知道如何完成任务将使得更改合并的过程变得更
加容易。
.. toctree::
:maxdepth: 1
:maxdepth: 2
process/index
目录和表格
----------
coding-style
* :ref:`genindex`
Chinese translated version of Documentation/process/magic-number.rst
If you have any comment or update to the content, please post to LKML directly.
However, if you have problem communicating in English you can also ask the
Chinese maintainer for help. Contact the Chinese maintainer, if this
translation is outdated or there is problem with translation.
Chinese maintainer: Jia Wei Wei <harryxiyou@gmail.com>
---------------------------------------------------------------------
Documentation/process/magic-number.rst的中文翻译
如果想评论或更新本文的内容,请直接发信到LKML。如果你使用英文交流有困难的话,也可
以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题,请联系中文版维护者。
中文版维护者: 贾威威 Jia Wei Wei <harryxiyou@gmail.com>
中文版翻译者: 贾威威 Jia Wei Wei <harryxiyou@gmail.com>
中文版校译者: 贾威威 Jia Wei Wei <harryxiyou@gmail.com>
以下为正文
---------------------------------------------------------------------
这个文件是有关当前使用的魔术值注册表。当你给一个结构添加了一个魔术值,你也应该把这个魔术值添加到这个文件,因为我们最好把用于各种结构的魔术值统一起来。
使用魔术值来保护内核数据结构是一个非常好的主意。这就允许你在运行期检查(a)一个结构是否已经被攻击,或者(b)你已经给一个例行程序通过了一个错误的结构。后一种情况特别地有用---特别是当你通过一个空指针指向结构体的时候。tty源码,例如,经常通过特定驱动使用这种方法并且反复地排列特定方面的结构。
使用魔术值的方法是在结构的开始处声明的,如下:
struct tty_ldisc {
int magic;
...
};
当你以后给内核添加增强功能的时候,请遵守这条规则!这样就会节省数不清的调试时间,特别是一些古怪的情况,例如,数组超出范围并且重新写了超出部分。遵守这个规则,‪这些情况可以被快速地,安全地避免。
Theodore Ts'o
31 Mar 94
给当前的Linux 2.1.55添加魔术表。
Michael Chastain
<mailto:mec@shout.net>
22 Sep 1997
现在应该最新的Linux 2.1.112.因为在特性冻结期间,不能在2.2.x前改变任何东西。这些条目被数域所排序。
Krzysztof G.Baranowski
<mailto: kgb@knm.org.pl>
29 Jul 1998
更新魔术表到Linux 2.5.45。刚好越过特性冻结,但是有可能还会有一些新的魔术值在2.6.x之前融入到内核中。
Petr Baudis
<pasky@ucw.cz>
03 Nov 2002
更新魔术表到Linux 2.5.74。
Fabian Frederick
<ffrederick@users.sourceforge.net>
09 Jul 2003
魔术名 地址 结构 所在文件
===========================================================================
PG_MAGIC 'P' pg_{read,write}_hdr include/linux/pg.h
CMAGIC 0x0111 user include/linux/a.out.h
MKISS_DRIVER_MAGIC 0x04bf mkiss_channel drivers/net/mkiss.h
HDLC_MAGIC 0x239e n_hdlc drivers/char/n_hdlc.c
APM_BIOS_MAGIC 0x4101 apm_user arch/x86/kernel/apm_32.c
CYCLADES_MAGIC 0x4359 cyclades_port include/linux/cyclades.h
DB_MAGIC 0x4442 fc_info drivers/net/iph5526_novram.c
DL_MAGIC 0x444d fc_info drivers/net/iph5526_novram.c
FASYNC_MAGIC 0x4601 fasync_struct include/linux/fs.h
FF_MAGIC 0x4646 fc_info drivers/net/iph5526_novram.c
ISICOM_MAGIC 0x4d54 isi_port include/linux/isicom.h
PTY_MAGIC 0x5001 drivers/char/pty.c
PPP_MAGIC 0x5002 ppp include/linux/if_pppvar.h
SERIAL_MAGIC 0x5301 async_struct include/linux/serial.h
SSTATE_MAGIC 0x5302 serial_state include/linux/serial.h
SLIP_MAGIC 0x5302 slip drivers/net/slip.h
STRIP_MAGIC 0x5303 strip drivers/net/strip.c
X25_ASY_MAGIC 0x5303 x25_asy drivers/net/x25_asy.h
SIXPACK_MAGIC 0x5304 sixpack drivers/net/hamradio/6pack.h
AX25_MAGIC 0x5316 ax_disp drivers/net/mkiss.h
TTY_MAGIC 0x5401 tty_struct include/linux/tty.h
MGSL_MAGIC 0x5401 mgsl_info drivers/char/synclink.c
TTY_DRIVER_MAGIC 0x5402 tty_driver include/linux/tty_driver.h
MGSLPC_MAGIC 0x5402 mgslpc_info drivers/char/pcmcia/synclink_cs.c
TTY_LDISC_MAGIC 0x5403 tty_ldisc include/linux/tty_ldisc.h
USB_SERIAL_MAGIC 0x6702 usb_serial drivers/usb/serial/usb-serial.h
FULL_DUPLEX_MAGIC 0x6969 drivers/net/ethernet/dec/tulip/de2104x.c
USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth drivers/usb/class/bluetty.c
RFCOMM_TTY_MAGIC 0x6d02 net/bluetooth/rfcomm/tty.c
USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port drivers/usb/serial/usb-serial.h
CG_MAGIC 0x00090255 ufs_cylinder_group include/linux/ufs_fs.h
RPORT_MAGIC 0x00525001 r_port drivers/char/rocket_int.h
LSEMAGIC 0x05091998 lse drivers/fc4/fc.c
GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str drivers/scsi/gdth_ioctl.h
RIEBL_MAGIC 0x09051990 drivers/net/atarilance.c
NBD_REQUEST_MAGIC 0x12560953 nbd_request include/linux/nbd.h
RED_MAGIC2 0x170fc2a5 (any) mm/slab.c
BAYCOM_MAGIC 0x19730510 baycom_state drivers/net/baycom_epp.c
ISDN_X25IFACE_MAGIC 0x1e75a2b9 isdn_x25iface_proto_data
drivers/isdn/isdn_x25iface.h
ECP_MAGIC 0x21504345 cdkecpsig include/linux/cdk.h
LSOMAGIC 0x27091997 lso drivers/fc4/fc.c
LSMAGIC 0x2a3b4d2a ls drivers/fc4/fc.c
WANPIPE_MAGIC 0x414C4453 sdla_{dump,exec} include/linux/wanpipe.h
CS_CARD_MAGIC 0x43525553 cs_card sound/oss/cs46xx.c
LABELCL_MAGIC 0x4857434c labelcl_info_s include/asm/ia64/sn/labelcl.h
ISDN_ASYNC_MAGIC 0x49344C01 modem_info include/linux/isdn.h
CTC_ASYNC_MAGIC 0x49344C01 ctc_tty_info drivers/s390/net/ctctty.c
ISDN_NET_MAGIC 0x49344C02 isdn_net_local_s drivers/isdn/i4l/isdn_net_lib.h
SAVEKMSG_MAGIC2 0x4B4D5347 savekmsg arch/*/amiga/config.c
CS_STATE_MAGIC 0x4c4f4749 cs_state sound/oss/cs46xx.c
SLAB_C_MAGIC 0x4f17a36d kmem_cache mm/slab.c
COW_MAGIC 0x4f4f4f4d cow_header_v1 arch/um/drivers/ubd_user.c
I810_CARD_MAGIC 0x5072696E i810_card sound/oss/i810_audio.c
TRIDENT_CARD_MAGIC 0x5072696E trident_card sound/oss/trident.c
ROUTER_MAGIC 0x524d4157 wan_device [in wanrouter.h pre 3.9]
SAVEKMSG_MAGIC1 0x53415645 savekmsg arch/*/amiga/config.c
GDA_MAGIC 0x58464552 gda arch/mips/include/asm/sn/gda.h
RED_MAGIC1 0x5a2cf071 (any) mm/slab.c
EEPROM_MAGIC_VALUE 0x5ab478d2 lanai_dev drivers/atm/lanai.c
HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state include/linux/hdlcdrv.h
PCXX_MAGIC 0x5c6df104 channel drivers/char/pcxx.h
KV_MAGIC 0x5f4b565f kernel_vars_s arch/mips/include/asm/sn/klkernvars.h
I810_STATE_MAGIC 0x63657373 i810_state sound/oss/i810_audio.c
TRIDENT_STATE_MAGIC 0x63657373 trient_state sound/oss/trident.c
M3_CARD_MAGIC 0x646e6f50 m3_card sound/oss/maestro3.c
FW_HEADER_MAGIC 0x65726F66 fw_header drivers/atm/fore200e.h
SLOT_MAGIC 0x67267321 slot drivers/hotplug/cpqphp.h
SLOT_MAGIC 0x67267322 slot drivers/hotplug/acpiphp.h
LO_MAGIC 0x68797548 nbd_device include/linux/nbd.h
OPROFILE_MAGIC 0x6f70726f super_block drivers/oprofile/oprofilefs.h
M3_STATE_MAGIC 0x734d724d m3_state sound/oss/maestro3.c
VMALLOC_MAGIC 0x87654320 snd_alloc_track sound/core/memory.c
KMALLOC_MAGIC 0x87654321 snd_alloc_track sound/core/memory.c
PWC_MAGIC 0x89DC10AB pwc_device drivers/usb/media/pwc.h
NBD_REPLY_MAGIC 0x96744668 nbd_reply include/linux/nbd.h
ENI155_MAGIC 0xa54b872d midway_eprom drivers/atm/eni.h
CODA_MAGIC 0xC0DAC0DA coda_file_info include/linux/coda_fs_i.h
DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram drivers/scsi/gdth.h
YAM_MAGIC 0xF10A7654 yam_port drivers/net/hamradio/yam.c
CCB_MAGIC 0xf2691ad2 ccb drivers/scsi/ncr53c8xx.c
QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry drivers/scsi/arm/queue.c
QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry drivers/scsi/arm/queue.c
HTB_CMAGIC 0xFEFAFEF1 htb_class net/sched/sch_htb.c
NMI_MAGIC 0x48414d4d455201 nmi_s arch/mips/include/asm/sn/nmi.h
请注意,在声音记忆管理中仍然有一些特殊的为每个驱动定义的魔术值。查看include/sound/sndmagic.h来获取他们完整的列表信息。很多OSS声音驱动拥有自己从声卡PCI ID构建的魔术值-他们也没有被列在这里。
IrDA子系统也使用了大量的自己的魔术值,查看include/net/irda/irda.h来获取他们完整的信息。
HFS是另外一个比较大的使用魔术值的文件系统-你可以在fs/hfs/hfs.h中找到他们。
......@@ -16,7 +16,7 @@ Documentation/admin-guide/bug-hunting.rst 的中文翻译
中文版维护者: 杨瑞 Dave Young <hidave.darkstar@gmail.com>
中文版翻译者: 杨瑞 Dave Young <hidave.darkstar@gmail.com>
中文版校译者: 李阳 Li Yang <leo@zh-kernel.org>
中文版校译者: 李阳 Li Yang <leoyang.li@nxp.com>
王聪 Wang Cong <xiyou.wangcong@gmail.com>
以下为正文
......
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment