diff --git a/share/man/man9/bus_generic_attach.9 b/share/man/man9/bus_generic_attach.9 index 5b2b205f78bb..1bae1e68cb60 100644 --- a/share/man/man9/bus_generic_attach.9 +++ b/share/man/man9/bus_generic_attach.9 @@ -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 diff --git a/share/man/man9/bus_generic_detach.9 b/share/man/man9/bus_generic_detach.9 index 76ce99d16320..0151d49a5251 100644 --- a/share/man/man9/bus_generic_detach.9 +++ b/share/man/man9/bus_generic_detach.9 @@ -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 diff --git a/share/man/man9/bus_generic_shutdown.9 b/share/man/man9/bus_generic_shutdown.9 index d439ce5b5ac1..5cb7738a270a 100644 --- a/share/man/man9/bus_generic_shutdown.9 +++ b/share/man/man9/bus_generic_shutdown.9 @@ -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 diff --git a/share/man/man9/devclass.9 b/share/man/man9/devclass.9 index 73e4f1a5f5ec..af169155df8f 100644 --- a/share/man/man9/devclass.9 +++ b/share/man/man9/devclass.9 @@ -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 diff --git a/share/man/man9/devclass_add_driver.9 b/share/man/man9/devclass_add_driver.9 index 83b7cc2f0476..0b7b827165c5 100644 --- a/share/man/man9/devclass_add_driver.9 +++ b/share/man/man9/devclass_add_driver.9 @@ -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 , diff --git a/share/man/man9/device.9 b/share/man/man9/device.9 index 8419197bd5f4..246aac07efec 100644 --- a/share/man/man9/device.9 +++ b/share/man/man9/device.9 @@ -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. diff --git a/share/man/man9/device_add_child.9 b/share/man/man9/device_add_child.9 index 8d0863915121..2314ca79a4b5 100644 --- a/share/man/man9/device_add_child.9 +++ b/share/man/man9/device_add_child.9 @@ -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 diff --git a/share/man/man9/device_enable.9 b/share/man/man9/device_enable.9 index 7e7fdc91be05..c4daf81db801 100644 --- a/share/man/man9/device_enable.9 +++ b/share/man/man9/device_enable.9 @@ -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 diff --git a/share/man/man9/device_get_devclass.9 b/share/man/man9/device_get_devclass.9 index 60ad911908b8..01d7bdf439cd 100644 --- a/share/man/man9/device_get_devclass.9 +++ b/share/man/man9/device_get_devclass.9 @@ -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 diff --git a/share/man/man9/device_get_driver.9 b/share/man/man9/device_get_driver.9 index 38a54807e57e..904b1e5881a1 100644 --- a/share/man/man9/device_get_driver.9 +++ b/share/man/man9/device_get_driver.9 @@ -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 diff --git a/share/man/man9/device_get_state.9 b/share/man/man9/device_get_state.9 index d5800c9ef6d5..27cb25df8a54 100644 --- a/share/man/man9/device_get_state.9 +++ b/share/man/man9/device_get_state.9 @@ -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 diff --git a/share/man/man9/device_probe_and_attach.9 b/share/man/man9/device_probe_and_attach.9 index 44ccd4eec7be..bcf5ef65a617 100644 --- a/share/man/man9/device_probe_and_attach.9 +++ b/share/man/man9/device_probe_and_attach.9 @@ -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 diff --git a/share/man/man9/device_quiet.9 b/share/man/man9/device_quiet.9 index 502e1a927dca..5c0f8ce19a37 100644 --- a/share/man/man9/device_quiet.9 +++ b/share/man/man9/device_quiet.9 @@ -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 diff --git a/share/man/man9/device_set_desc.9 b/share/man/man9/device_set_desc.9 index 05478059105d..96085b8435f9 100644 --- a/share/man/man9/device_set_desc.9 +++ b/share/man/man9/device_set_desc.9 @@ -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 diff --git a/share/man/man9/devstat.9 b/share/man/man9/devstat.9 index af9164c3842e..adf6c7100964 100644 --- a/share/man/man9/devstat.9 +++ b/share/man/man9/devstat.9 @@ -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. diff --git a/share/man/man9/devtoname.9 b/share/man/man9/devtoname.9 index 3b9ad94ebb94..9a62a5ededb6 100644 --- a/share/man/man9/devtoname.9 +++ b/share/man/man9/devtoname.9 @@ -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 , diff --git a/share/man/man9/driver.9 b/share/man/man9/driver.9 index fa64a1a2fddf..88fdb9eea584 100644 --- a/share/man/man9/driver.9 +++ b/share/man/man9/driver.9 @@ -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 diff --git a/share/man/man9/make_dev.9 b/share/man/man9/make_dev.9 index 94edfdf12134..629984370fff 100644 --- a/share/man/man9/make_dev.9 +++ b/share/man/man9/make_dev.9 @@ -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 ,