Documentation: kernel-hacking: minor edits for style
Rusty's kernel-hacking guides provide important information, however they are written in a narrative style that some readers may interpret as off-putting. Since the goal is to make kernel documentation accessible to as many new developers as possible, it's best to avoid the turns of phrase that require a specific cultural context to properly understand. Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
parent
a32d5c0fc1
commit
f35cf1a59e
|
@ -112,8 +112,7 @@ time, although different tasklets can run simultaneously.
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
The name 'tasklet' is misleading: they have nothing to do with
|
The name 'tasklet' is misleading: they have nothing to do with
|
||||||
'tasks', and probably more to do with some bad vodka Alexey
|
'tasks'.
|
||||||
Kuznetsov had at the time.
|
|
||||||
|
|
||||||
You can tell you are in a softirq (or tasklet) using the
|
You can tell you are in a softirq (or tasklet) using the
|
||||||
:c:func:`in_softirq()` macro (``include/linux/preempt.h``).
|
:c:func:`in_softirq()` macro (``include/linux/preempt.h``).
|
||||||
|
@ -290,8 +289,8 @@ userspace.
|
||||||
Unlike :c:func:`put_user()` and :c:func:`get_user()`, they
|
Unlike :c:func:`put_user()` and :c:func:`get_user()`, they
|
||||||
return the amount of uncopied data (ie. 0 still means success).
|
return the amount of uncopied data (ie. 0 still means success).
|
||||||
|
|
||||||
[Yes, this moronic interface makes me cringe. The flamewar comes up
|
[Yes, this objectionable interface makes me cringe. The flamewar comes
|
||||||
every year or so. --RR.]
|
up every year or so. --RR.]
|
||||||
|
|
||||||
The functions may sleep implicitly. This should never be called outside
|
The functions may sleep implicitly. This should never be called outside
|
||||||
user context (it makes no sense), with interrupts disabled, or a
|
user context (it makes no sense), with interrupts disabled, or a
|
||||||
|
@ -645,8 +644,9 @@ names in development kernels; this is not done just to keep everyone on
|
||||||
their toes: it reflects a fundamental change (eg. can no longer be
|
their toes: it reflects a fundamental change (eg. can no longer be
|
||||||
called with interrupts on, or does extra checks, or doesn't do checks
|
called with interrupts on, or does extra checks, or doesn't do checks
|
||||||
which were caught before). Usually this is accompanied by a fairly
|
which were caught before). Usually this is accompanied by a fairly
|
||||||
complete note to the linux-kernel mailing list; search the archive.
|
complete note to the appropriate kernel development mailing list; search
|
||||||
Simply doing a global replace on the file usually makes things **worse**.
|
the archives. Simply doing a global replace on the file usually makes
|
||||||
|
things **worse**.
|
||||||
|
|
||||||
Initializing structure members
|
Initializing structure members
|
||||||
------------------------------
|
------------------------------
|
||||||
|
@ -723,14 +723,14 @@ Putting Your Stuff in the Kernel
|
||||||
In order to get your stuff into shape for official inclusion, or even to
|
In order to get your stuff into shape for official inclusion, or even to
|
||||||
make a neat patch, there's administrative work to be done:
|
make a neat patch, there's administrative work to be done:
|
||||||
|
|
||||||
- Figure out whose pond you've been pissing in. Look at the top of the
|
- Figure out who are the owners of the code you've been modifying. Look
|
||||||
source files, inside the ``MAINTAINERS`` file, and last of all in the
|
at the top of the source files, inside the ``MAINTAINERS`` file, and
|
||||||
``CREDITS`` file. You should coordinate with this person to make sure
|
last of all in the ``CREDITS`` file. You should coordinate with these
|
||||||
you're not duplicating effort, or trying something that's already
|
people to make sure you're not duplicating effort, or trying something
|
||||||
been rejected.
|
that's already been rejected.
|
||||||
|
|
||||||
Make sure you put your name and EMail address at the top of any files
|
Make sure you put your name and email address at the top of any files
|
||||||
you create or mangle significantly. This is the first place people
|
you create or modify significantly. This is the first place people
|
||||||
will look when they find a bug, or when **they** want to make a change.
|
will look when they find a bug, or when **they** want to make a change.
|
||||||
|
|
||||||
- Usually you want a configuration option for your kernel hack. Edit
|
- Usually you want a configuration option for your kernel hack. Edit
|
||||||
|
@ -748,11 +748,11 @@ make a neat patch, there's administrative work to be done:
|
||||||
can usually just add a "obj-$(CONFIG_xxx) += xxx.o" line. The syntax
|
can usually just add a "obj-$(CONFIG_xxx) += xxx.o" line. The syntax
|
||||||
is documented in ``Documentation/kbuild/makefiles.rst``.
|
is documented in ``Documentation/kbuild/makefiles.rst``.
|
||||||
|
|
||||||
- Put yourself in ``CREDITS`` if you've done something noteworthy,
|
- Put yourself in ``CREDITS`` if you consider what you've done
|
||||||
usually beyond a single file (your name should be at the top of the
|
noteworthy, usually beyond a single file (your name should be at the
|
||||||
source files anyway). ``MAINTAINERS`` means you want to be consulted
|
top of the source files anyway). ``MAINTAINERS`` means you want to be
|
||||||
when changes are made to a subsystem, and hear about bugs; it implies
|
consulted when changes are made to a subsystem, and hear about bugs;
|
||||||
a more-than-passing commitment to some part of the code.
|
it implies a more-than-passing commitment to some part of the code.
|
||||||
|
|
||||||
- Finally, don't forget to read
|
- Finally, don't forget to read
|
||||||
``Documentation/process/submitting-patches.rst`` and possibly
|
``Documentation/process/submitting-patches.rst`` and possibly
|
||||||
|
|
|
@ -941,8 +941,7 @@ lock.
|
||||||
|
|
||||||
A classic problem here is when you provide callbacks or hooks: if you
|
A classic problem here is when you provide callbacks or hooks: if you
|
||||||
call these with the lock held, you risk simple deadlock, or a deadly
|
call these with the lock held, you risk simple deadlock, or a deadly
|
||||||
embrace (who knows what the callback will do?). Remember, the other
|
embrace (who knows what the callback will do?).
|
||||||
programmers are out to get you, so don't do this.
|
|
||||||
|
|
||||||
Overzealous Prevention Of Deadlocks
|
Overzealous Prevention Of Deadlocks
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
@ -952,8 +951,6 @@ grabs a read lock, searches a list, fails to find what it wants, drops
|
||||||
the read lock, grabs a write lock and inserts the object has a race
|
the read lock, grabs a write lock and inserts the object has a race
|
||||||
condition.
|
condition.
|
||||||
|
|
||||||
If you don't see why, please stay away from my code.
|
|
||||||
|
|
||||||
Racing Timers: A Kernel Pastime
|
Racing Timers: A Kernel Pastime
|
||||||
-------------------------------
|
-------------------------------
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue