d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Mdoc Janitor:

Browse Source 
* Fix hard sentence breaks.

  * NOTE: devstat(9) requires more mdoc(7) work.
This commit is contained in:
hmp 2003-10-23 01:54:06 +00:00
parent 4e58cc8b1a
commit 85ba5ab8f0
18 changed files with 130 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
share/man/man9/bus_generic_attach.9
View File

@ -44,7 +44,8 @@ for busses
.Sh DESCRIPTION
This function provides an implementation of the
.Xr DEVICE_ATTACH 9
method which can be used by most bus code. It simply calls
method which can be used by most bus code.
It simply calls
.Xr device_probe_and_attach 9
for each child device attached to the bus.
.Sh RETURN VALUES

3
share/man/man9/bus_generic_detach.9
View File

@ -45,7 +45,8 @@ for busses
This function provides an implementation of the
.Xr DEVICE_DETACH 9
method
which can be used by most bus code. It simply calls the
which can be used by most bus code.
It simply calls the
.Xr DEVICE_DETACH 9
method of each child device attached to the bus.
.Sh RETURN VALUES

3
share/man/man9/bus_generic_shutdown.9
View File

@ -45,7 +45,8 @@ for busses
This function provides an implementation of the
.Xr DEVICE_SHUTDOWN 9
method
which can be used by most bus code. It simply calls the
which can be used by most bus code.
It simply calls the
.Xr DEVICE_SHUTDOWN 9
method of each child device attached to the bus.
.Sh RETURN VALUES

3
share/man/man9/devclass.9
View File

@ -39,7 +39,8 @@
.Sh DESCRIPTION
The
.Vt devclass
object has two main functions in the system. The first is to manage
object has two main functions in the system.
The first is to manage
the allocation of unit numbers for device instances and the second is
to hold the list of device drivers for a particular bus type.
Each

3
share/man/man9/devclass_add_driver.9
View File

@ -47,7 +47,8 @@
.Fn devclass_find_driver "devclass_t dc" "const char *name"
.Sh DESCRIPTION
These functions can be used to add new drivers into the system, remove
old ones and search for existing ones. Normally drivers are added
old ones and search for existing ones.
Normally drivers are added
automatically during system initialisation.
.Sh SEE ALSO
.Xr devclass 9 ,

3
share/man/man9/device.9
View File

@ -43,7 +43,8 @@ into, disk drives attached to the expansion card etc.
The system defines one device,
.Va root_bus
and all other devices are created dynamically during
autoconfiguration. Normally devices representing top-level busses in
autoconfiguration.
Normally devices representing top-level busses in
the system (ISA, PCI etc.) will be attached directly to
.Va root_bus
and other devices will be added as children of their relevant bus.

11
share/man/man9/device_add_child.9
View File

@ -57,13 +57,15 @@ If the unit is unknown then the caller should pass
and the system will choose the next available unit number.
.Pp
The name of the device is used to determine which drivers might be
appropriate for the device. If a name is specified then only drivers
of that name are probed. If no name is given then all drivers for the
appropriate for the device.
If a name is specified then only drivers of that name are probed.
If no name is given then all drivers for the
owning bus are probed.
.Pp
This allows busses which can uniquely identify device instances (such
as PCI) to allow each driver to check each device instance for a
match. For busses which rely on supplied probe hints where only one
match.
For busses which rely on supplied probe hints where only one
driver can have a change of probing the device, the driver name should
specified as the device name.
.Pp
@ -73,7 +75,8 @@ unit number of
should be given.
When a specific unit number is desired (e.g. for wiring a particular
piece of hardware to a pre-configured unit number), that unit should
be passed. If the specified unit number is already allocated, a new
be passed.
If the specified unit number is already allocated, a new
unit will be allocated and a diagnostic message printed.
.Pp
If the devices attached to a bus must be probed in a specific order

3
share/man/man9/device_enable.9
View File

@ -46,7 +46,8 @@
.Ft int
.Fn device_is_enabled "device_t dev"
.Sh DESCRIPTION
Each device has an enabled flag associated with it. A device is
Each device has an enabled flag associated with it.
A device is
enabled by default when it is created but may be disabled (for
instance to prevent a destructive or time consuming probe attempt).
To disable a device, call

4
share/man/man9/device_get_devclass.9
View File

@ -40,8 +40,8 @@
.Ft devclass_t
.Fn device_get_devclass "device_t dev"
.Sh DESCRIPTION
The current devclass associated with the device is returned. If the
device has no devclass,
The current devclass associated with the device is returned.
If the device has no devclass,
.Dv NULL
is returned.
.Sh SEE ALSO

4
share/man/man9/device_get_driver.9
View File

@ -40,8 +40,8 @@
.Ft driver_t *
.Fn device_get_driver "device_t dev"
.Sh DESCRIPTION
The current driver associated with the device is returned. If the
device has no driver,
The current driver associated with the device is returned.
If the device has no driver,
.Dv NULL
is returned.
.Sh SEE ALSO

4
share/man/man9/device_get_state.9
View File

@ -75,8 +75,8 @@ Each device has a busy count which is incremented when
.Fn device_busy
is called and decremented when
.Fn device_unbusy
is called. Both routines return an error if the device state is less
than
is called.
Both routines return an error if the device state is less than
.Dv DS_ATTACHED .
.Pp
When

3
share/man/man9/device_probe_and_attach.9
View File

@ -41,7 +41,8 @@
.Fn device_probe_and_attach "device_t dev"
.Sh DESCRIPTION
This function is called during autoconfiguration to initialise the
devices in the system. For each device, the
devices in the system.
For each device, the
.Xr DEVICE_PROBE 9
method of each suitable driver is called and if a probe succeeds, a
description of the device is printed and the

3
share/man/man9/device_quiet.9
View File

@ -46,7 +46,8 @@
.Ft int
.Fn device_is_quiet "device_t dev"
.Sh DESCRIPTION
Each device has a quiet flag associated with it. A device is
Each device has a quiet flag associated with it.
A device is
verbose by default when it is created but may be quieted to prevent
the device identification string to be printed during probe.
To quiet a device, call

3
share/man/man9/device_set_desc.9
View File

@ -46,7 +46,8 @@
.Ft const char *
.Fn device_get_desc "device_t dev"
.Sh DESCRIPTION
Manipulate the verbose description of a device. This description (if
Manipulate the verbose description of a device.
This description (if
present) is printed as part of the message when it is attached during
autoconfiguration.
The variation

127
share/man/man9/devstat.9
View File

@ -68,7 +68,8 @@
.Fc
.Sh DESCRIPTION
The devstat subsystem is an interface for recording device
statistics, as its name implies. The idea is to keep reasonably detailed
statistics, as its name implies.
The idea is to keep reasonably detailed
statistics while utilizing a minimum amount of CPU time to record them.
Thus, no statistical calculations are actually performed in the kernel
portion of the
@ -78,7 +79,8 @@ code. Instead, that is left for user programs to handle.
.Fn devstat_add_entry
registers a device with the
.Nm
subsystem. The caller is expected to have already allocated \fBand zeroed\fR
subsystem.
The caller is expected to have already allocated \fBand zeroed\fR
the devstat structure before calling this function.
.Fn devstat_add_entry
takes several arguments:
@ -92,40 +94,48 @@ The device name. e.g. da, cd, sa.
.It unit_number
Device unit number.
.It block_size
Block size of the device, if supported. If the device does not support a
Block size of the device, if supported.
If the device does not support a
block size, or if the blocksize is unknown at the time the device is added
to the
.Nm
list, it should be set to 0.
.It flags
Flags indicating operations supported or not supported by the device. See
below for details.
Flags indicating operations supported or not supported by the device.
See below for details.
.It device_type
The device type. This is broken into three sections: base device type
The device type.
This is broken into three sections: base device type
(e.g. direct access, CDROM, sequential access), interface type (IDE, SCSI
or other) and a pass-through flag to indicate pas-through devices. See below
for a complete list of types.
or other) and a pass-through flag to indicate pas-through devices.
See below for a complete list of types.
.It priority
The device priority. The priority is used to determine how devices are
The device priority.
The priority is used to determine how devices are
sorted within
.Nm devstat Ns 's
list of devices. Devices are sorted first by priority (highest to lowest),
and then by attach order. See below for a complete list of available
list of devices.
Devices are sorted first by priority (highest to lowest),
and then by attach order.
See below for a complete list of available
priorities.
.El
.Pp
.Fn devstat_remove_entry
removes a device from the
.Nm
subsystem. It takes the devstat structure for the device in question as
an argument. The
subsystem.
It takes the devstat structure for the device in question as
an argument.
The
.Nm
generation number is incremented and the number of devices is decremented.
.Pp
.Fn devstat_start_transaction
registers the start of a transaction with the
.Nm
subsystem. The busy count is incremented with each transaction start.
subsystem.
The busy count is incremented with each transaction start.
When a device goes from idle to busy, the system uptime is recorded in the
.Va start_time
field of the
@ -135,7 +145,8 @@ structure.
.Fn devstat_end_transaction
registers the end of a transaction with the
.Nm
subsystem. It takes four arguments:
subsystem.
It takes four arguments:
.Bl -tag -width tag_type
.It ds
The
@ -144,7 +155,8 @@ structure for the device in question.
.It bytes
The number of bytes transferred in this transaction.
.It tag_type
Transaction tag type. See below for tag types.
Transaction tag type.
See below for tag types.
.It flags
Transaction flags indicating whether the transaction was a read, write, or
whether no data was transferred.
@ -164,19 +176,23 @@ structure is composed of the following fields:
.It dev_links
Each
.Va devstat
structure is placed in a linked list when it is registered. The
structure is placed in a linked list when it is registered.
The
.Va dev_links
field contains a pointer to the next entry in the list of
.Va devstat
structures.
.It device_number
The device number is a unique identifier for each device. The device
number is incremented for each new device that is registered. The device
The device number is a unique identifier for each device.
The device
number is incremented for each new device that is registered.
The device
number is currently only a 32-bit integer, but it could be enlarged if
someone has a system with more than four billion device arrival events.
.It device_name
The device name is a text string given by the registering driver to
identify itself. (e.g.\&
identify itself.
(e.g.\&
.Dq da ,
.Dq cd ,
.Dq sa ,
@ -185,8 +201,9 @@ etc.)
The unit number identifies the particular instance of the peripheral driver
in question.
.It bytes_written
This is the number of bytes that have been written to the device. This
number is currently an unsigned 64 bit integer. This will hopefully
This is the number of bytes that have been written to the device.
This number is currently an unsigned 64 bit integer.
This will hopefully
eliminate the counter wrap that would come very quickly on some systems if
32 bit integers were used.
.It bytes_read
@ -201,12 +218,14 @@ This is the number of writes to the device.
This is the number of free/erase operations on the device.
.It num_other
This is the number of transactions to the device which are neither reads or
writes. For instance,
writes.
For instance,
.Tn SCSI
drivers often send a test unit ready command to
.Tn SCSI
devices. The test unit ready command does not read or write any data. It
merely causes the device to return its status.
devices.
The test unit ready command does not read or write any data.
It merely causes the device to return its status.
.It busy_count
This is the current number of outstanding transactions for the device.
This should never go below zero, and on an idle device it should be zero.
@ -215,20 +234,23 @@ the way
.Fn devstat_start_transaction
and
.Fn devstat_end_transaction
are being called in client code. There should be one and only one
are being called in client code.
There should be one and only one
transaction start event and one transaction end event for each transaction.
.It block_size
This is the block size of the device, if the device has a block size.
.It tag_types
This is an array of counters to record the number of various tag types that
are sent to a device. See below for a list of tag types.
are sent to a device.
See below for a list of tag types.
.It dev_creation_time
This is the time, as reported by
.Fn getmicrotime
that the device was registered.
.It busy_time
This is the amount of time that the device busy count has been greater than
zero. This is only updated when the busy count returns to zero.
zero.
This is only updated when the busy count returns to zero.
.It start_time
This is the time, as reported by
.Fn getmicrouptime
@ -236,29 +258,38 @@ that the device busy count went from zero to one.
.It last_comp_time
This is the time as reported by
.Fn getmicrouptime
that a transaction last completed. It is used along with
that a transaction last completed.
It is used along with
.Va start_time
to calculate the device busy time.
.It flags
These flags indicate which statistics measurements are supported by a
particular device. These flags are primarily intended to serve as an aid
particular device.
These flags are primarily intended to serve as an aid
to userland programs that decipher the statistics.
.It device_type
This is the device type. It consists of three parts: the device type
This is the device type.
It consists of three parts: the device type
(e.g. direct access, CDROM, sequential access, etc.), the interface (IDE,
SCSI or other) and whether or not the device in question is a pass-through
driver. See below for a complete list of device types.
driver.
See below for a complete list of device types.
.It priority
This is the priority. This is the first parameter used to determine where
This is the priority.
This is the first parameter used to determine where
to insert a device in the
.Nm
list. The second parameter is attach order. See below for a list of
list.
The second parameter is attach order.
See below for a list of
available priorities.
.El
.Pp
Each device is given a device type. Pass-through devices have the same
Each device is given a device type.
Pass-through devices have the same
underlying device type and interface as the device they provide an
interface for, but they also have the pass-through flag set. The base
interface for, but they also have the pass-through flag set.
The base
device types are identical to the
.Tn SCSI
device type numbers, so with
@ -266,7 +297,8 @@ device type numbers, so with
peripherals, the device type returned from an inquiry is usually ORed with
the
.Tn SCSI
interface type and the pass-through flag if appropriate. The device type
interface type and the pass-through flag if appropriate.
The device type
flags are as follows:
.Bd -literal -offset indent
typedef enum {
@ -297,7 +329,8 @@ typedef enum {
Devices have a priority associated with them, which controls roughly where
they are placed in the
.Nm
list. The priorities are as follows:
list.
The priorities are as follows:
.Bd -literal -offset indent
typedef enum {
DEVSTAT_PRIORITY_MIN = 0x000,
@ -314,7 +347,8 @@ typedef enum {
.Ed
.Pp
Each device has associated with it flags to indicate what operations are
supported or not supported. The
supported or not supported.
The
.Va devstat_support_flags
values are as follows:
.Bl -tag -width DEVSTAT_NO_ORDERED_TAGS
@ -325,7 +359,8 @@ This device does not have a blocksize.
.It DEVSTAT_NO_ORDERED_TAGS
This device does not support ordered tags.
.It DEVSTAT_BS_UNAVAILABLE
This device supports a blocksize, but it is currently unavailable. This
This device supports a blocksize, but it is currently unavailable.
This
flag is most often used with removable media drives.
.El
.Pp
@ -361,7 +396,8 @@ The device doesn't support tags.
.Pp
The tag type values correspond to the lower four bits of the
.Tn SCSI
tag definitions. In CAM, for instance, the
tag definitions.
In CAM, for instance, the
.Va tag_action
from the CCB is ORed with 0xf to determine the tag type to pass in to
.Fn devstat_end_transaction .
@ -375,7 +411,8 @@ This is the current version of the
subsystem, and it should be incremented each time a change is made that
would require recompilation of userland programs that access
.Nm
statistics. Userland programs use this version, via the
statistics.
Userland programs use this version, via the
.Va kern.devstat.version
.Nm sysctl
variable to determine whether they are in sync with the kernel
@ -407,9 +444,11 @@ variable.
.Pp
It is impossible with the current
.Nm
architecture to accurately measure time per transaction. The only feasible
architecture to accurately measure time per transaction.
The only feasible
way to accurately measure time per transaction would be to record a
timestamp for every transaction. This measurement is probably not
timestamp for every transaction.
This measurement is probably not
worthwhile for most people as it would adversely affect the performance of
the system and cost space to store the timestamps for individual
transactions.

4
share/man/man9/devtoname.9
View File

@ -38,8 +38,8 @@
.Sh DESCRIPTION
The
.Fn devtoname
function returns a pointer to the name of the device passed to it. The name
is whatever was set to it in
function returns a pointer to the name of the device passed to it.
The name is whatever was set to it in
.Fn make_dev .
If no name is associated with
.Va dev ,

12
share/man/man9/driver.9
View File

@ -72,11 +72,14 @@ DRIVER_MODULE(foo, bogo, foo_driver, foo_devclass, 0, 0);
.Sh DESCRIPTION
Each driver in the kernel is described by a
.Dv driver_t
structure. The structure contains the name of the device, a pointer
structure.
The structure contains the name of the device, a pointer
to a list of methods, an indication of the kind of device which the
driver implements and the size of the private data which the driver
needs to associate with a device instance. Each driver will implement
one or more sets of methods (called interfaces). The example driver
needs to associate with a device instance.
Each driver will implement
one or more sets of methods (called interfaces).
The example driver
implements the standard "driver" interface and the fictitious "bogo"
interface.
.Pp
@ -85,7 +88,8 @@ When a driver is registered with the system (by the
macro, see
.Xr DRIVER_MODULE 9 ) ,
it is added to the list of drivers contained in the devclass
of its parent bus type. For instance all PCI drivers would be
of its parent bus type.
For instance all PCI drivers would be
contained in the devclass named "pci" and all ISA drivers would be
in the devclass named "isa".
The reason the drivers are not held in the device object of the parent

6
share/man/man9/make_dev.9
View File

@ -51,8 +51,10 @@ The
.Fn make_dev
function creates a
.Fa dev_t
structure for a new device. If DEVFS is available, it is also notified of
the presence of the new device. The device will be owned by
structure for a new device.
If DEVFS is available, it is also notified of
the presence of the new device.
The device will be owned by
.Va uid ,
with the group ownership as
.Va gid ,