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:
Konstantin Ryabitsev 2022-03-29 15:51:17 -04:00 committed by Jonathan Corbet
parent a32d5c0fc1
commit f35cf1a59e
2 changed files with 19 additions and 22 deletions

View File

@ -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

View File

@ -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
------------------------------- -------------------------------