shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2025-03-24 14:50:17 +03:00
Code

docs: update some docs and delete outdated stuff

Browse Source
This commit is contained in:
Kay Sievers 2008-06-26 18:12:50 +02:00
parent ec9611ddb5
commit 8bf875ff28
3 changed files with 6 additions and 322 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
docs/README-gcov_for_udev
View File

@ -14,37 +14,19 @@ With that said, here is how to get code coverage analysis for udev files.
Note that this was developed with udev version 024.
- Make sure you've installed udev and that it is working properly.
If you are having problems, refer to the README and HOWTO-udev_for_dev
documents in udev tarball.
- execute make_gcov.sh from udev top level directory
- Build udev with:
make gcov-all
This will compile udev with gcov support. Basically make_gcov.sh will
run make but override the CFLAGS. It strips any optimization from
CFLAGS in order for gcov to get correct code coverage analysis. It will
also add the -fprofile-arcs and -ftest-coverage options which are the
necessary flags needed to use gcov.
If you look into your udev directory and see that it has been polluted with
a bunch of *.gcno, *.gcda and *.gcov files. gcov creates and uses these files
to extract the code coverage info.
- After running make_gcov.sh you need to install udev again. So basically,
su to root
make install
This will compile udev with gcov support. If you look into your udev directory
and see that it has been polluted with a bunch of *.gcno, *.gcda and *.gcov files.
gcov creates and uses these files to extract the code coverage info.
- Then execute some udev tasks. You can run some udev tests, reboot, or
do anything your little udev heart desires. Once you are satisfied, you
can now see how much udev code was covered. I personally recommend just
running test/udev-test.pl for starters.
- To get the udev code coverage analysis, execute run_gcov.sh from udev top
level directory. You need to be root to do this.
su to root
- To get the udev code coverage analysis:
make udev_gcov.txt
- This creates udev_gcov.txt in the udev top level directory which holds all
@ -83,8 +65,4 @@ Note that this was developed with udev version 024.
- Once you are done with using gcov for udev and want to return to your
normal use of udev, run a regular 'make clean' on your udev directory.
Then just run a regular make and make install and you are back to normal:
make clean all
su to root
make install
Then just run a regular make and make install and you are back to normal.

102
docs/overview
View File

@ -1,102 +0,0 @@
-------------------------------------------------------------------------
This is a proposal from the early days of udev. A lot of the things
mentioned here are implemented differently and most of the features
implemented in udev are not part of that document.
This document is only kept in the tree for sentimental reasons.
-------------------------------------------------------------------------
We've got a couple of goals for udev:
1) dynamic replacement for /dev
2) device naming
3) API to access info about current system devices
Splitting these goals into separate subsystems:
1) udev - dynamic replacement for /dev
2) namedev - device naming
3) libsysfs - a standard library for accessing device information on the
system.
Udev
------
Udev will be responsible for responding to /sbin/hotplug on device
events. It will receive the device class information along with
device's sysfs directory. Udev will call the name_device function from
the naming device subsystem with that information and receive a unique
device name in return. Udev will then query sysfs through the libsysfs
for specific device information required for creating the /dev node like
major and minor number. Once it has the important information, udev
will create a /dev entry for the device, add the device to the in memory
table of current devices, and send notification of the successful event
through a D-BUS message. On a remove call, udev will remove the /dev
entry, remove the device from the in memory table, and send
notification.
Udev will consist of a command udev - to be called from /sbin/hotplug.
It will require the in memory dynamic database/table for keeping track
of current system devices, and a library of routines for accessing that
database/table. Udev will not care about "how" devices are named, that
will be separated into the device naming subsystem. It's presented a
common device naming API by the device naming subsystem to use for
naming devices.
namedev
----------
From comments people have made, the device naming part of udev has been
pushed into its own "subsystem". The reason is to make this as flexible
and pluggable as possible. The device naming subsystem, or namedev, will
present a standard interface for udev to call for naming a particular
device. Under that interface, system administrators can plug in their
own methods for device naming.
We would provide a default naming scheme. The first prototype
implementation could simply take the sysfs directory passed in with the
device name function, query sysfs for the major and minor numbers, and
then look up in a static device name mapping file the name of the
device. The static device naming file could look just like devices.txt
in the Linux kernel's Documentation directory. Obviously, this isn't a
great implementation because eventually we'd like major an minor numbers
to be dynamic.
The default naming scheme in the future would have a set of policies to
go through in order to determine the name of the device. The device
naming subsystem would get the sysfs directory of the to be named device
and would use the following information in order to map the device's
name:
1) Label info - like SCSI's UUID
2) Bus Device Number
3) Topology on Bus
4) Kernel Name - DEFAULT
System administrators could use the default naming system or enterprise
computing environments could plug in their Universal Unique Identifier
(UUID) policies. The idea is to make the device naming as flexible and
pluggable as possible.
The device naming subsystem would require accessing sysfs for device
information. It will receive the device's sysfs directory in the call
from udev and use it to get more information to determine naming. The
namedev subsystem will include a standard naming API for udev to use.
The default naming scheme will include a set of functions and a static
device naming file, which will reside in /etc or /var.
libsysfs
--------
There is a need for a common API to access device information in sysfs.
The device naming subsystem and the udev subsystem need to take the
sysfs directory path and query device information. Instead of copying
code so each one will have to readdir, etc., splitting this logic of
sysfs calls into a separate library that will sit atop sysfs makes more
sense. Sysfs callbacks aren't standard across devices, so this is
another reason for creating a common and standard library interface for
querying device information.

192
docs/udev_vs_devfs
View File

@ -1,192 +0,0 @@
udev and devfs - The final word
December 30, 2003
Greg Kroah-Hartman
<greg@kroah.com>
Executive summary for those too lazy to read this whole thing:
I don't care about devfs, and I don't want to talk about it at
all anymore. If you love devfs, fine, I'm not trying to tell
anyone what to do. But you really should be looking into using
udev instead. All further email messages sent to me about devfs
will be gladly ignored.
First off, some background. For a description of udev, and what its
original design goals were, please see the OLS 2003 paper on udev,
available at:
<http://www.kroah.com/linux/talks/ols_2003_udev_paper/Reprint-Kroah-Hartman-OLS2003.pdf>
and the slides for the talk, available at:
<http://www.kroah.com/linux/talks/ols_2003_udev_talk/>
The OLS paper can also be found in the docs/ directory of the udev
tarball, available on kernel.org in the /pub/linux/utils/kernel/hotplug/
directory.
In that OLS paper, I described the current situation of a static /dev
and the current problems that a number of people have with it. I also
detailed how devfs tries to solve a number of these problems. In
hindsight, I should have never mentioned the word "devfs" when talking
about udev. I did so only because it seemed like a good place to start
with. Most people understood what devfs is, and what it does. To
compare udev against it, showing how udev was more powerful, and a more
complete solution to the problems people were having, seemed like a
natural comparison to me.
But no more. I hereby never want to compare devfs and udev again. With
the exception of this message...
The Problems:
1) A static /dev is unwieldy and big. It would be nice to only show
the /dev entries for the devices we actually have running in the
system.
2) We are (well, were) running out of major and minor numbers for
devices.
3) Users want a way to name devices in a persistent fashion (i.e. "This
disk here, must _always_ be called "boot_disk" no matter where in
the scsi tree I put it", or "This USB camera must always be called
"camera" no matter if I have other USB scsi devices plugged in or
not.")
4) Userspace programs want to know when devices are created or removed,
and what /dev entry is associated with them.
The constraints:
1) No policy in the kernel!
2) Follow standards (like the LSB)
3) must be small so embedded devices will use it.
So, how does devfs stack up to the above problems and constraints:
Problems:
1) devfs only shows the dev entries for the devices in the system.
2) devfs does not handle the need for dynamic major/minor numbers
3) devfs does not provide a way to name devices in a persistent
fashion.
4) devfs does provide a deamon that userspace programs can hook into
to listen to see what devices are being created or removed.
Constraints:
1) devfs forces the devfs naming policy into the kernel. If you
don't like this naming scheme, tough.
2) devfs does not follow the LSB device naming standard.
3) devfs is small, and embedded devices use it. However it is
implemented in non-pagable memory.
Oh yeah, and there are the insolvable race conditions with the devfs
implementation in the kernel, but I'm not going to talk about them right
now, sorry. See the linux-kernel archives if you care about them (and
if you use devfs, you should care...)
So devfs is 2 for 7, ignoring the kernel races.
And now for udev:
Problems:
1) using udev, the /dev tree only is populated for the devices that
are currently present in the system.
2) udev does not care about the major/minor number schemes. If the
kernel tomorrow switches to randomly assign major and minor numbers
to different devices, it would work just fine (this is exactly
what I am proposing to do in 2.7...)
3) This is the main reason udev is around. It provides the ability
to name devices in a persistent manner. More on that below.
4) udev emits D-BUS messages so that any other userspace program
(like HAL) can listen to see what devices are created or removed.
It also allows userspace programs to query its database to see
what devices are present and what they are currently named as
(providing a pointer into the sysfs tree for that specific device
node.)
Constraints:
1) udev moves _all_ naming policies out of the kernel and into
userspace.
2) udev defaults to using the LSB device naming standard. If users
want to deviate away from this standard (for example when naming
some devices in a persistent manner), it is easily possible to do
so.
3) udev is small and is entirely in userspace, which
is swapable, and doesn't have to be running at all times.
Nice, 7 out of 7 for udev. Makes you think the problems and constraints
were picked by a udev developer, right? No, the problems and
constraints are ones I've seen over the years and so udev, along with
the kernel driver model and sysfs, were created to solve these real
problems. I also have had the luxury to see the problems that the
current devfs implementation has, and have taken the time to work out
something that does not have those same problems.
So by just looking at the above descriptions, everyone should instantly
realize that udev is far better than devfs and start helping out udev
development, right? Oh, you want more info, ok...
Back in May 2003 I released a very tiny version of udev that implemented
everything that devfs currently does, in about 6Kb of userspace code:
http://marc.theaimsgroup.com/?l=linux-kernel&m=105003185331553
Yes, that's right, 6Kb. So, you are asking, why are you still working
on udev if it did everything devfs did back in May 2003? That's because
just managing static device nodes based on what the kernel calls the
devices is _not_ the primary goal of udev. It's just a tiny side effect
of its primary goal, the ability to never worry about major/minor
number assignments and provide the ability to achieve persistent device
names if wanted.
All the people wanting to bring up the udev vs. devfs argument go back
and read the previous paragraph. Yes, all Gentoo users who keep filling
up my inbox with smoking emails, I mean you.
So, how well does udev solve its goals:
Prevent users from ever worrying about major/minor numbers
And here you were, not knowing you ever needed to worry about
major/minor numbers in the first place, right? Ah, I see you
haven't plugged in 2 USB printers and tried to figure out which
printer was which /dev entry? Or plugged in 4000 SCSI disks and
tried to figure out how to access that 3642nd disk and what it was
called in /dev. Or plugged in a USB camera and a USB flash drive
and then tried to download the pictures off of the flash drive by
accident?
As the above scenarios show, both desktop users and big iron users
both need to not worry about which device is assigned to what
major/minor device.
udev doesn't care what major/minor number is assigned to a device.
It merely takes the numbers that the kernel says it assigned to the
device and creates a device node based on it, which the user can
then use (if you don't understand the whole major/minor to device
node issue, or even what a device node is, trust me, you don't
really want to, go install udev and don't worry about it...) As
stated above, if the kernel decides to start randomly assigning
major numbers to all devices, then udev will still work just fine.
Provide a persistent device naming solution:
Lots of people want to assign a specific name that they can talk to
a device to, no matter where it is in the system, or what order they
plugged the device in. USB printers, SCSI disks, PCI sound cards,
Firewire disks, USB mice, and lots of other devices all need to be
assigned a name in a consistent manner (udev doesn't handle network
devices, naming them is already a solved solution, using nameif).
udev allows users to create simple rules to describe what device to
name. If users want to call a program running a large database
half-way around the world, asking it what to name this device, it
can. We don't put the naming database into the kernel (like other
Unix variants have), everything is in userspace, and easily
accessible. You can even run a perl script to name your device if
you are that crazy...
For more information on how to create udev rules to name devices,
please see the udev man page, and look at the example udev rules
that ship with the tarball.
So, convinced already why you should use udev instead of devfs? No.
Ok, fine, I'm not forcing you to abandon your bloated, stifling policy,
nonextensible, end of life feature if you don't want to. But please
don't bother me about it either, I don't care about devfs, only about
udev.
This is my last posting about this topic, all further emails sent to me
about why devfs is wonderful, and why are you making fun of this
wonderful, stable gift from the gods, will be gleefully ignored and
possibly posted in a public place where others can see.
thanks,
greg k-h