Skip to content

Commit

Permalink
---
Browse files Browse the repository at this point in the history 
yaml
---
r: 37747
b: refs/heads/master
c: f0b364a
h: refs/heads/master
i:
  37745: dcac5a5
  37743: 294389a
v: v3
  • Loading branch information
Linus Torvalds committed Oct 1, 2006
1 parent 0ec8156 commit 534062e
Show file tree
Hide file tree
Showing 2,902 changed files with 105,619 additions and 60,272 deletions.
2 changes: 1 addition & 1 deletion [refs]
View file
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
---
refs/heads/master: bfeeb0f57940b143a55dcc7ee88e8842108d9145
refs/heads/master: f0b364a13d7fba001c0571d954f165dfaf5f434a
6 changes: 4 additions & 2 deletions trunk/CREDITS
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1620,7 +1620,8 @@ D: fbdev hacking

N: Jesper Juhl
E: jesper.juhl@gmail.com
D: Various fixes, cleanups and minor features.
D: Various fixes, cleanups and minor features all over the tree.
D: Wrote initial version of the hdaps driver (since passed on to others).
S: Lemnosvej 1, 3.tv
S: 2300 Copenhagen S.
S: Denmark
Expand Down Expand Up @@ -2477,7 +2478,8 @@ S: Derbyshire DE4 3RL
S: United Kingdom

N: Ian S. Nelson
E: ian.nelson@echostar.com
E: nelsonis@earthlink.net
P: 1024D/00D3D983 3EFD 7B86 B888 D7E2 29B6 9E97 576F 1B97 00D3 D983
D: Minor mmap and ide hacks
S: 1370 Atlantis Ave.
S: Lafayette CO, 80026
Expand Down
34 changes: 34 additions & 0 deletions trunk/Documentation/CodingStyle
View file
Original file line number Diff line number Diff line change
Expand Up @@ -532,6 +532,40 @@ appears outweighs the potential value of the hint that tells gcc to do
something it would have done anyway.


Chapter 16: Function return values and names

Functions can return values of many different kinds, and one of the
most common is a value indicating whether the function succeeded or
failed. Such a value can be represented as an error-code integer
(-Exxx = failure, 0 = success) or a "succeeded" boolean (0 = failure,
non-zero = success).

Mixing up these two sorts of representations is a fertile source of
difficult-to-find bugs. If the C language included a strong distinction
between integers and booleans then the compiler would find these mistakes
for us... but it doesn't. To help prevent such bugs, always follow this
convention:

If the name of a function is an action or an imperative command,
the function should return an error-code integer. If the name
is a predicate, the function should return a "succeeded" boolean.

For example, "add work" is a command, and the add_work() function returns 0
for success or -EBUSY for failure. In the same way, "PCI device present" is
a predicate, and the pci_dev_present() function returns 1 if it succeeds in
finding a matching device or 0 if it doesn't.

All EXPORTed functions must respect this convention, and so should all
public functions. Private (static) functions need not, but it is
recommended that they do.

Functions whose return value is the actual result of a computation, rather
than an indication of whether the computation succeeded, are not subject to
this rule. Generally they indicate failure by returning some out-of-range
result. Typical examples would be functions that return pointers; they use
NULL or the ERR_PTR mechanism to report failure.



Appendix I: References

Expand Down
78 changes: 50 additions & 28 deletions trunk/Documentation/DocBook/kernel-api.tmpl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -181,27 +181,6 @@ X!Ilib/string.c
</sect1>
</chapter>

<chapter id="proc">
<title>The proc filesystem</title>

<sect1><title>sysctl interface</title>
!Ekernel/sysctl.c
</sect1>

<sect1><title>proc filesystem interface</title>
!Ifs/proc/base.c
</sect1>
</chapter>

<chapter id="debugfs">
<title>The debugfs filesystem</title>

<sect1><title>debugfs interface</title>
!Efs/debugfs/inode.c
!Efs/debugfs/file.c
</sect1>
</chapter>

<chapter id="vfs">
<title>The Linux VFS</title>
<sect1><title>The Filesystem types</title>
Expand Down Expand Up @@ -234,6 +213,50 @@ X!Ilib/string.c
</sect1>
</chapter>

<chapter id="proc">
<title>The proc filesystem</title>

<sect1><title>sysctl interface</title>
!Ekernel/sysctl.c
</sect1>

<sect1><title>proc filesystem interface</title>
!Ifs/proc/base.c
</sect1>
</chapter>

<chapter id="sysfs">
<title>The Filesystem for Exporting Kernel Objects</title>
!Efs/sysfs/file.c
!Efs/sysfs/symlink.c
!Efs/sysfs/bin.c
</chapter>

<chapter id="debugfs">
<title>The debugfs filesystem</title>

<sect1><title>debugfs interface</title>
!Efs/debugfs/inode.c
!Efs/debugfs/file.c
</sect1>
</chapter>

<chapter id="relayfs">
<title>relay interface support</title>

<para>
Relay interface support
is designed to provide an efficient mechanism for tools and
facilities to relay large amounts of data from kernel space to
user space.
</para>

<sect1><title>relay interface</title>
!Ekernel/relay.c
!Ikernel/relay.c
</sect1>
</chapter>

<chapter id="netcore">
<title>Linux Networking</title>
<sect1><title>Networking Base Types</title>
Expand Down Expand Up @@ -349,13 +372,6 @@ X!Earch/i386/kernel/mca.c
</sect1>
</chapter>

<chapter id="sysfs">
<title>The Filesystem for Exporting Kernel Objects</title>
!Efs/sysfs/file.c
!Efs/sysfs/symlink.c
!Efs/sysfs/bin.c
</chapter>

<chapter id="security">
<title>Security Framework</title>
!Esecurity/security.c
Expand Down Expand Up @@ -386,6 +402,7 @@ X!Iinclude/linux/device.h
-->
!Edrivers/base/driver.c
!Edrivers/base/core.c
!Edrivers/base/class.c
!Edrivers/base/firmware_class.c
!Edrivers/base/transport_class.c
!Edrivers/base/dmapool.c
Expand Down Expand Up @@ -437,6 +454,11 @@ X!Edrivers/pnp/system.c
!Eblock/ll_rw_blk.c
</chapter>

<chapter id="chrdev">
<title>Char devices</title>
!Efs/char_dev.c
</chapter>

<chapter id="miscdev">
<title>Miscellaneous Devices</title>
!Edrivers/char/misc.c
Expand Down
123 changes: 62 additions & 61 deletions trunk/Documentation/DocBook/usb.tmpl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,77 +43,67 @@

<para>A Universal Serial Bus (USB) is used to connect a host,
such as a PC or workstation, to a number of peripheral
devices. USB uses a tree structure, with the host at the
devices. USB uses a tree structure, with the host as the
root (the system's master), hubs as interior nodes, and
peripheral devices as leaves (and slaves).
peripherals as leaves (and slaves).
Modern PCs support several such trees of USB devices, usually
one USB 2.0 tree (480 Mbit/sec each) with
a few USB 1.1 trees (12 Mbit/sec each) that are used when you
connect a USB 1.1 device directly to the machine's "root hub".
</para>

<para>That master/slave asymmetry was designed in part for
ease of use. It is not physically possible to assemble
(legal) USB cables incorrectly: all upstream "to-the-host"
connectors are the rectangular type, matching the sockets on
root hubs, and the downstream type are the squarish type
(or they are built in to the peripheral).
Software doesn't need to deal with distributed autoconfiguration
since the pre-designated master node manages all that.
At the electrical level, bus protocol overhead is reduced by
eliminating arbitration and moving scheduling into host software.
<para>That master/slave asymmetry was designed-in for a number of
reasons, one being ease of use. It is not physically possible to
assemble (legal) USB cables incorrectly: all upstream "to the host"
connectors are the rectangular type (matching the sockets on
root hubs), and all downstream connectors are the squarish type
(or they are built into the peripheral).
Also, the host software doesn't need to deal with distributed
auto-configuration since the pre-designated master node manages all that.
And finally, at the electrical level, bus protocol overhead is reduced by
eliminating arbitration and moving scheduling into the host software.
</para>

<para>USB 1.0 was announced in January 1996, and was revised
<para>USB 1.0 was announced in January 1996 and was revised
as USB 1.1 (with improvements in hub specification and
support for interrupt-out transfers) in September 1998.
USB 2.0 was released in April 2000, including high speed
transfers and transaction translating hubs (used for USB 1.1
USB 2.0 was released in April 2000, adding high-speed
transfers and transaction-translating hubs (used for USB 1.1
and 1.0 backward compatibility).
</para>

<para>USB support was added to Linux early in the 2.2 kernel series
shortly before the 2.3 development forked off. Updates
from 2.3 were regularly folded back into 2.2 releases, bringing
new features such as <filename>/sbin/hotplug</filename> support,
more drivers, and more robustness.
The 2.5 kernel series continued such improvements, and also
worked on USB 2.0 support,
higher performance,
better consistency between host controller drivers,
API simplification (to make bugs less likely),
and providing internal "kerneldoc" documentation.
<para>Kernel developers added USB support to Linux early in the 2.2 kernel
series, shortly before 2.3 development forked. Updates from 2.3 were
regularly folded back into 2.2 releases, which improved reliability and
brought <filename>/sbin/hotplug</filename> support as well more drivers.
Such improvements were continued in the 2.5 kernel series, where they added
USB 2.0 support, improved performance, and made the host controller drivers
(HCDs) more consistent. They also simplified the API (to make bugs less
likely) and added internal "kerneldoc" documentation.
</para>

<para>Linux can run inside USB devices as well as on
the hosts that control the devices.
Because the Linux 2.x USB support evolved to support mass market
platforms such as Apple Macintosh or PC-compatible systems,
it didn't address design concerns for those types of USB systems.
So it can't be used inside mass-market PDAs, or other peripherals.
USB device drivers running inside those Linux peripherals
But USB device drivers running inside those peripherals
don't do the same things as the ones running inside hosts,
and so they've been given a different name:
they're called <emphasis>gadget drivers</emphasis>.
This document does not present gadget drivers.
so they've been given a different name:
<emphasis>gadget drivers</emphasis>.
This document does not cover gadget drivers.
</para>

</chapter>

<chapter id="host">
<title>USB Host-Side API Model</title>

<para>Within the kernel,
host-side drivers for USB devices talk to the "usbcore" APIs.
There are two types of public "usbcore" APIs, targetted at two different
layers of USB driver. Those are
<emphasis>general purpose</emphasis> drivers, exposed through
driver frameworks such as block, character, or network devices;
and drivers that are <emphasis>part of the core</emphasis>,
which are involved in managing a USB bus.
Such core drivers include the <emphasis>hub</emphasis> driver,
which manages trees of USB devices, and several different kinds
of <emphasis>host controller driver (HCD)</emphasis>,
<para>Host-side drivers for USB devices talk to the "usbcore" APIs.
There are two. One is intended for
<emphasis>general-purpose</emphasis> drivers (exposed through
driver frameworks), and the other is for drivers that are
<emphasis>part of the core</emphasis>.
Such core drivers include the <emphasis>hub</emphasis> driver
(which manages trees of USB devices) and several different kinds
of <emphasis>host controller drivers</emphasis>,
which control individual busses.
</para>

Expand All @@ -122,21 +112,21 @@

<itemizedlist>

<listitem><para>USB supports four kinds of data transfer
(control, bulk, interrupt, and isochronous). Two transfer
types use bandwidth as it's available (control and bulk),
while the other two types of transfer (interrupt and isochronous)
<listitem><para>USB supports four kinds of data transfers
(control, bulk, interrupt, and isochronous). Two of them (control
and bulk) use bandwidth as it's available,
while the other two (interrupt and isochronous)
are scheduled to provide guaranteed bandwidth.
</para></listitem>

<listitem><para>The device description model includes one or more
"configurations" per device, only one of which is active at a time.
Devices that are capable of high speed operation must also support
full speed configurations, along with a way to ask about the
"other speed" configurations that might be used.
Devices that are capable of high-speed operation must also support
full-speed configurations, along with a way to ask about the
"other speed" configurations which might be used.
</para></listitem>

<listitem><para>Configurations have one or more "interface", each
<listitem><para>Configurations have one or more "interfaces", each
of which may have "alternate settings". Interfaces may be
standardized by USB "Class" specifications, or may be specific to
a vendor or device.</para>
Expand All @@ -162,7 +152,7 @@
</para></listitem>

<listitem><para>The Linux USB API supports synchronous calls for
control and bulk messaging.
control and bulk messages.
It also supports asynchnous calls for all kinds of data transfer,
using request structures called "URBs" (USB Request Blocks).
</para></listitem>
Expand Down Expand Up @@ -463,14 +453,25 @@
file in your Linux kernel sources.
</para>

<para>Otherwise the main use for this file from programs
is to poll() it to get notifications of usb devices
as they're plugged or unplugged.
To see what changed, you'd need to read the file and
compare "before" and "after" contents, scan the filesystem,
or see its hotplug event.
<para>This file, in combination with the poll() system call, can
also be used to detect when devices are added or removed:
<programlisting>int fd;
struct pollfd pfd;

fd = open("/proc/bus/usb/devices", O_RDONLY);
pfd = { fd, POLLIN, 0 };
for (;;) {
/* The first time through, this call will return immediately. */
poll(&amp;pfd, 1, -1);

/* To see what's changed, compare the file's previous and current
contents or scan the filesystem. (Scanning is more precise.) */
}</programlisting>
Note that this behavior is intended to be used for informational
and debug purposes. It would be more appropriate to use programs
such as udev or HAL to initialize a device or start a user-mode
helper program, for instance.
</para>

</sect1>

<sect1>
Expand Down
20 changes: 20 additions & 0 deletions trunk/Documentation/HOWTO
View file
Original file line number Diff line number Diff line change
Expand Up @@ -375,6 +375,26 @@ of information is needed by the kernel developers to help track down the
problem.


Managing bug reports
--------------------

One of the best ways to put into practice your hacking skills is by fixing
bugs reported by other people. Not only you will help to make the kernel
more stable, you'll learn to fix real world problems and you will improve
your skills, and other developers will be aware of your presence. Fixing
bugs is one of the best ways to earn merit amongst the developers, because
not many people like wasting time fixing other people's bugs.

To work in the already reported bug reports, go to http://bugzilla.kernel.org.
If you want to be advised of the future bug reports, you can subscribe to the
bugme-new mailing list (only new bug reports are mailed here) or to the
bugme-janitor mailing list (every change in the bugzilla is mailed here)

http://lists.osdl.org/mailman/listinfo/bugme-new
http://lists.osdl.org/mailman/listinfo/bugme-janitors



Mailing lists
-------------

Expand Down
Loading

0 comments on commit 534062e

Please sign in to comment.