Commit 5464e9c72194d4db9665346b3973c1fb27ba87be
Committed by
Greg Kroah-Hartman
1 parent
e556b8131a
Exists in
master
and in
4 other branches
DOCUMENTATION: Update overview.txt in Doc/driver-model.
A few grammatical fixes, clarifications and corrections in just the overview file for the driver model documentation. Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
Showing 1 changed file with 34 additions and 18 deletions Side-by-side Diff
Documentation/driver-model/overview.txt
... | ... | @@ -30,7 +30,7 @@ |
30 | 30 | Microsoft (namely ACPI) ensures that almost every device on almost any bus |
31 | 31 | on an x86-compatible system can work within this paradigm. Of course, |
32 | 32 | not every bus is able to support all such operations, although most |
33 | -buses support a most of those operations. | |
33 | +buses support most of those operations. | |
34 | 34 | |
35 | 35 | |
36 | 36 | Downstream Access |
37 | 37 | |
38 | 38 | |
39 | 39 | |
40 | 40 | |
... | ... | @@ -46,25 +46,29 @@ |
46 | 46 | struct pci_dev { |
47 | 47 | ... |
48 | 48 | |
49 | - struct device dev; | |
49 | + struct device dev; /* Generic device interface */ | |
50 | + ... | |
50 | 51 | }; |
51 | 52 | |
52 | -Note first that it is statically allocated. This means only one allocation on | |
53 | -device discovery. Note also that it is at the _end_ of struct pci_dev. This is | |
54 | -to make people think about what they're doing when switching between the bus | |
55 | -driver and the global driver; and to prevent against mindless casts between | |
56 | -the two. | |
53 | +Note first that the struct device dev within the struct pci_dev is | |
54 | +statically allocated. This means only one allocation on device discovery. | |
57 | 55 | |
56 | +Note also that that struct device dev is not necessarily defined at the | |
57 | +front of the pci_dev structure. This is to make people think about what | |
58 | +they're doing when switching between the bus driver and the global driver, | |
59 | +and to discourage meaningless and incorrect casts between the two. | |
60 | + | |
58 | 61 | The PCI bus layer freely accesses the fields of struct device. It knows about |
59 | 62 | the structure of struct pci_dev, and it should know the structure of struct |
60 | 63 | device. Individual PCI device drivers that have been converted to the current |
61 | 64 | driver model generally do not and should not touch the fields of struct device, |
62 | -unless there is a strong compelling reason to do so. | |
65 | +unless there is a compelling reason to do so. | |
63 | 66 | |
64 | -This abstraction is prevention of unnecessary pain during transitional phases. | |
65 | -If the name of the field changes or is removed, then every downstream driver | |
66 | -will break. On the other hand, if only the bus layer (and not the device | |
67 | -layer) accesses struct device, it is only that layer that needs to change. | |
67 | +The above abstraction prevents unnecessary pain during transitional phases. | |
68 | +If it were not done this way, then when a field was renamed or removed, every | |
69 | +downstream driver would break. On the other hand, if only the bus layer | |
70 | +(and not the device layer) accesses the struct device, it is only the bus | |
71 | +layer that needs to change. | |
68 | 72 | |
69 | 73 | |
70 | 74 | User Interface |
71 | 75 | |
72 | 76 | |
73 | 77 | |
... | ... | @@ -73,15 +77,27 @@ |
73 | 77 | By virtue of having a complete hierarchical view of all the devices in the |
74 | 78 | system, exporting a complete hierarchical view to userspace becomes relatively |
75 | 79 | easy. This has been accomplished by implementing a special purpose virtual |
76 | -file system named sysfs. It is hence possible for the user to mount the | |
77 | -whole sysfs filesystem anywhere in userspace. | |
80 | +file system named sysfs. | |
78 | 81 | |
79 | -This can be done permanently by providing the following entry into the | |
80 | -/etc/fstab (under the provision that the mount point does exist, of course): | |
82 | +Almost all mainstream Linux distros mount this filesystem automatically; you | |
83 | +can see some variation of the following in the output of the "mount" command: | |
81 | 84 | |
82 | -none /sys sysfs defaults 0 0 | |
85 | +$ mount | |
86 | +... | |
87 | +none on /sys type sysfs (rw,noexec,nosuid,nodev) | |
88 | +... | |
89 | +$ | |
83 | 90 | |
84 | -Or by hand on the command line: | |
91 | +The auto-mounting of sysfs is typically accomplished by an entry similar to | |
92 | +the following in the /etc/fstab file: | |
93 | + | |
94 | +none /sys sysfs defaults 0 0 | |
95 | + | |
96 | +or something similar in the /lib/init/fstab file on Debian-based systems: | |
97 | + | |
98 | +none /sys sysfs nodev,noexec,nosuid 0 0 | |
99 | + | |
100 | +If sysfs is not automatically mounted, you can always do it manually with: | |
85 | 101 | |
86 | 102 | # mount -t sysfs sysfs /sys |
87 | 103 |