From 3e1cee04f8b33031d7d2640344d5b93d45e21b8f Mon Sep 17 00:00:00 2001 From: Ruslan Ermilov Date: Fri, 30 May 2003 21:13:32 +0000 Subject: [PATCH] Assorted mdoc(7) fixes. --- share/man/man9/CTASSERT.9 | 12 +-- share/man/man9/bus_activate_resource.9 | 52 +++++------ share/man/man9/bus_child_present.9 | 35 ++++--- share/man/man9/bus_set_resource.9 | 60 ++++++------ share/man/man9/device_get_name.9 | 11 ++- share/man/man9/device_get_parent.9 | 5 +- share/man/man9/device_printf.9 | 10 +- share/man/man9/device_set_driver.9 | 2 +- share/man/man9/rman.9 | 122 ++++++++++++++----------- 9 files changed, 165 insertions(+), 144 deletions(-) diff --git a/share/man/man9/CTASSERT.9 b/share/man/man9/CTASSERT.9 index c3e29a2a8d80..5c9d30eb2361 100644 --- a/share/man/man9/CTASSERT.9 +++ b/share/man/man9/CTASSERT.9 @@ -33,19 +33,18 @@ .Nm CTASSERT .Nd compile time assertion macro .Sh SYNOPSIS -.Pp .In sys/param.h .In sys/systm.h .Fn CTASSERT expression .Sh DESCRIPTION The -.Nm +.Fn CTASSERT macro evaluates .Fa expression at compile time and causes a compiler error if it is false. .Pp The -.Nm +.Fn CTASSERT macro is useful for asserting the size or alignment of important data structures and variables during compilation, which would otherwise cause the code to fail at run time. @@ -53,12 +52,11 @@ otherwise cause the code to fail at run time. Assert that the size of the .Vt uuid structure is 16 bytes. -.Bd -literal -offset indent -CTASSERT(sizeof(struct uuid) == 16); -.Ed +.Pp +.Dl "CTASSERT(sizeof(struct uuid) == 16);" .Sh SEE ALSO .Xr KASSERT 9 .Sh AUTHORS This manual page was written by .An Hiten M. Pandya -.Aq hmp@FreeBSD.ORG . +.Aq hmp@FreeBSD.org . diff --git a/share/man/man9/bus_activate_resource.9 b/share/man/man9/bus_activate_resource.9 index ce5f14317d12..eb5b3e824e79 100644 --- a/share/man/man9/bus_activate_resource.9 +++ b/share/man/man9/bus_activate_resource.9 @@ -32,8 +32,8 @@ .Dt BUS_ACTIVATE_RESOURCE 9 .Os .Sh NAME -.Nm bus_activate_resource, bus_deactivate_resources -.Nd activates or deactivates a resources +.Nm bus_activate_resource , bus_deactivate_resource +.Nd activate or deactivate a resource .Sh SYNOPSIS .In sys/param.h .In sys/bus.h @@ -42,26 +42,29 @@ .In sys/rman.h .In machine/resource.h .Ft int -.Fn bus_activate_resource "device_t dev" "int type" "int rid" "struct resource *r" +.Fo bus_activate_resource +.Fa "device_t dev" "int type" "int rid" "struct resource *r" +.Fc .Ft int -.Fn bus_deactivate_resource "device_t dev" "int type" "int rid" "struct resource *r" +.Fo bus_deactivate_resource +.Fa "device_t dev" "int type" "int rid" "struct resource *r" +.Fc .Sh DESCRIPTION -Activates or deactivates a previously allocated resource. +These functions activate or deactivate a previously allocated resource. In general, resources must be activated before they can be accessed by the driver so that the bus driver can map the resource into the devices space. .Pp -Its arguments are as follows: -.Bl -item -.It -.Fa dev -is the device that requests ownership of the resource. +The arguments are as follows: +.Bl -tag -width indent +.It Fa dev +The device that requests ownership of the resource. Before allocation, the resource is owned by the parent bus. -.It -.Fa type -is the type of resource you want to allocate. +.It Fa type +The type of resource you want to allocate. It is one of: -.Bl -tag -width SYS_RES_MEMORY +.Pp +.Bl -tag -width ".Dv SYS_RES_MEMORY" -compact .It Dv SYS_RES_IRQ for IRQs .It Dv SYS_RES_DRQ @@ -71,27 +74,20 @@ for I/O ports .It Dv SYS_RES_MEMORY for I/O memory .El -.It -.Fa rid -points to a bus specific handle that identifies the resource being allocated. -.It -.Fa r -points to the -.Ft struct resource +.It Fa rid +A pointer to a bus specific handle that identifies the resource being allocated. +.It Fa r +A pointer to the +.Vt "struct resource" returned by .Xr bus_alloc_resource 9 . .El .Sh RETURN VALUES -Zero indicates success. -Non-zero is an error from errno.h. -.\".Sh EXAMPLES -.\".Bd -literal -.\".Ed +Zero is returned on success, otherwise an error is returned. .Sh SEE ALSO .Xr bus_alloc_resource 9 , .Xr device 9 , .Xr driver 9 .Sh AUTHORS -.An -nosplit -This man page was written by +This manual page was written by .An Warner Losh Aq imp@FreeBSD.org . diff --git a/share/man/man9/bus_child_present.9 b/share/man/man9/bus_child_present.9 index 995a48208016..1b7ff4dbb3d4 100644 --- a/share/man/man9/bus_child_present.9 +++ b/share/man/man9/bus_child_present.9 @@ -33,7 +33,7 @@ .Os .Sh NAME .Nm bus_child_present -.Nd Ask the bus driver to see if this device is still really present. +.Nd "ask the bus driver to see if this device is still really present" .Sh SYNOPSIS .In sys/param.h .In sys/bus.h @@ -44,18 +44,22 @@ .Ft int .Fn bus_child_present "device_t dev" .Sh DESCRIPTION -Requests that the parent device driver of +The +.Fn bus_child_present +function requests that the parent device driver of .Fa dev check to see if the hardware represented by -.Fa dev +.Fa dev is still physically accessible at this time. While the notion of accessible varies from bus to bus, generally -hardware that is not acceessible cannot be accessed via the bus_space -methods that would otherwise be used to acceess the device. +hardware that is not acceessible cannot be accessed via the +.Fn bus_space* +methods that would otherwise be used to access the device. .Pp -This does not ask the question 'does this device have children?' which -can better be answered by +This does not ask the question +.Dq does this device have children? +which can better be answered by .Xr device_get_children 9 . .Sh RETURN VALUES A zero return value indicates that the device is not present in the @@ -64,19 +68,20 @@ A non-zero return value indicates that the device is present in the system, or that the state of the device cannot be determined. .Sh EXAMPLES This is some example code. -It only calls stop when the dc device is actually present. -.Bd -literal - device_t dev; - dc_softc *sc; +It only calls stop when the +.Xr dc 4 +device is actually present. +.Bd -literal -offset indent +device_t dev; +dc_softc *sc; - sc = device_get_softc(dev); - if (bus_child_present(dev)) - dc_stop(sc); +sc = device_get_softc(dev); +if (bus_child_present(dev)) + dc_stop(sc); .Ed .Sh SEE ALSO .Xr device 9 , .Xr driver 9 .Sh AUTHORS -.An -nosplit This man page was written by .An Warner Losh Aq imp@FreeBSD.org . diff --git a/share/man/man9/bus_set_resource.9 b/share/man/man9/bus_set_resource.9 index 9b1fe1fdf4b0..27448b470f37 100644 --- a/share/man/man9/bus_set_resource.9 +++ b/share/man/man9/bus_set_resource.9 @@ -33,7 +33,7 @@ .Os .Sh NAME .Nm bus_set_resource -.Nd Associates a definite resource with a given rid. +.Nd "associate a definite resource with a given resource ID" .Sh SYNOPSIS .In sys/param.h .In sys/bus.h @@ -42,23 +42,31 @@ .In sys/rman.h .In machine/resource.h .Ft int -.Fn bus_set_resource "device_t dev" "int type" "int rid" "u_long start" "u_long count" +.Fo bus_set_resource +.Fa "device_t dev" "int type" "int rid" "u_long start" "u_long count" +.Fc .Sh DESCRIPTION -Set the start address of the resource type, rid pair to be count long. -Typically client drivers do not use this interface. -Bus drivers, however, often use it to setup the resources a client -driver users. +The +.Fn bus_set_resource +function +sets the start address of the resource +.Fa type , rid +pair to be +.Fa count +long. +Typically, client drivers do not use this interface. +Bus drivers, however, often use it to set up the resources a client +driver uses. .Pp -Its arguments are as follows: -.Bl -item -.It -.Fa dev -is the device to set the resource on. -.It -.Fa type -is the type of resource you want to allocate. +The arguments are as follows: +.Bl -tag -width indent +.It Fa dev +The device to set the resource on. +.It Fa type +The type of resource you want to allocate. It is one of: -.Bl -tag -width SYS_RES_MEMORY +.Pp +.Bl -tag -width ".Dv SYS_RES_MEMORY" -compact .It Dv SYS_RES_IRQ for IRQs .It Dv SYS_RES_DRQ @@ -68,28 +76,20 @@ for I/O ports .It Dv SYS_RES_MEMORY for I/O memory .El -.It -.Fa rid -points to a bus specific handle that identifies the resource being allocated. -.It -.Fa start -is the beginning address of this resource. -.It -.Fa count -is the length of the resource. +.It Fa rid +A pointer to a bus specific handle that identifies the resource being allocated. +.It Fa start +The start address of this resource. +.It Fa count +The length of the resource. .El .Sh RETURN VALUES -Zero indicates success. -Non-zero is an error from errno.h. -.\".Sh EXAMPLES -.\".Bd -literal -.\".Ed +Zero is returned on success, otherwise an error is returned. .Sh SEE ALSO .Xr bus_alloc_resource 9 , .Xr bus_get_resource 9 , .Xr device 9 , .Xr driver 9 .Sh AUTHORS -.An -nosplit This man page was written by .An Warner Losh Aq imp@FreeBSD.org . diff --git a/share/man/man9/device_get_name.9 b/share/man/man9/device_get_name.9 index 6c64ecb2a2c9..811263589159 100644 --- a/share/man/man9/device_get_name.9 +++ b/share/man/man9/device_get_name.9 @@ -32,9 +32,8 @@ .Dt DEVICE_GET_NAME 9 .Os .Sh NAME -.Nm device_get_name -.Nm device_get_nameunit -.Nd access the name of a device's device class or instance. +.Nm device_get_name , device_get_nameunit +.Nd access the name of a device's device class or instance .Sh SYNOPSIS .In sys/param.h .In sys/bus.h @@ -43,11 +42,13 @@ .Ft int .Fn device_get_nameunit "device_t dev" .Sh DESCRIPTION +The .Fn device_get_name -Returns the name of the device's device class. +function returns the name of the device's device class. .Pp +The .Fn device_get_nameunit -Returns the name of the device's instance. +function returns the name of the device's instance. .Sh SEE ALSO .Xr device 9 .Sh AUTHORS diff --git a/share/man/man9/device_get_parent.9 b/share/man/man9/device_get_parent.9 index 10c93ced47cf..1c58a6c4bb14 100644 --- a/share/man/man9/device_get_parent.9 +++ b/share/man/man9/device_get_parent.9 @@ -33,15 +33,16 @@ .Os .Sh NAME .Nm device_get_parent -.Nd returns the device's parent. +.Nd return the device's parent .Sh SYNOPSIS .In sys/param.h .In sys/bus.h .Ft device_t .Fn device_get_parent "device_t dev" .Sh DESCRIPTION +The .Fn device_get_parent -Returns the name of the device's parent device. +function returns the name of the device's parent device. .Sh SEE ALSO .Xr device 9 .Sh AUTHORS diff --git a/share/man/man9/device_printf.9 b/share/man/man9/device_printf.9 index d8449fa97582..297cce731a15 100644 --- a/share/man/man9/device_printf.9 +++ b/share/man/man9/device_printf.9 @@ -35,19 +35,19 @@ .In sys/param.h .In sys/bus.h .Ft int -.Fn device_printf "device_t dev" "const char *fmt" "..." +.Fn device_printf "device_t dev" "const char *fmt" ... .Sh DESCRIPTION The -.Xr device_printf 9 +.Fn device_printf function is a convenience interface to the .Xr printf 9 function. It outputs the name of the -.Ar dev +.Fa dev device, followed by a colon and a space, and then what .Xr printf 9 -woult print if you passed -.Ar fmt +would print if you passed +.Fa fmt and the remaining arguments to it. .Sh RETURN VALUES The diff --git a/share/man/man9/device_set_driver.9 b/share/man/man9/device_set_driver.9 index f1b124927031..385e8be27f48 100644 --- a/share/man/man9/device_set_driver.9 +++ b/share/man/man9/device_set_driver.9 @@ -33,7 +33,7 @@ .Os .Sh NAME .Nm device_set_driver -.Nd associate a specific driver with a device node in the tree. +.Nd "associate a specific driver with a device node in the tree" .Sh SYNOPSIS .In sys/param.h .In sys/bus.h diff --git a/share/man/man9/rman.9 b/share/man/man9/rman.9 index 31c9bcf6dba0..5694ed5904b3 100644 --- a/share/man/man9/rman.9 +++ b/share/man/man9/rman.9 @@ -30,28 +30,28 @@ .Os .Sh NAME .Nm rman , -.Nm rman_activate_resource , -.Nm rman_await_resource , -.Nm rman_deactivate_resource , -.Nm rman_fini , -.Nm rman_init , -.Nm rman_manage_region , -.Nm rman_release_resource , -.Nm rman_reserve_resource , -.Nm rman_reserve_resource_bound , -.Nm rman_make_alignment_flags , -.Nm rman_get_start , -.Nm rman_get_end , -.Nm rman_get_size , -.Nm rman_get_flags , -.Nm rman_set_virtual , -.Nm rman_get_virtual , -.Nm rman_set_bustag , -.Nm rman_get_bustag , -.Nm rman_set_bushandle , -.Nm rman_get_bushandle , -.Nm rman_set_rid , -.Nm rman_get_rid +.Nm rman_activate_resource , +.Nm rman_await_resource , +.Nm rman_deactivate_resource , +.Nm rman_fini , +.Nm rman_init , +.Nm rman_manage_region , +.Nm rman_release_resource , +.Nm rman_reserve_resource , +.Nm rman_reserve_resource_bound , +.Nm rman_make_alignment_flags , +.Nm rman_get_start , +.Nm rman_get_end , +.Nm rman_get_size , +.Nm rman_get_flags , +.Nm rman_set_virtual , +.Nm rman_get_virtual , +.Nm rman_set_bustag , +.Nm rman_get_bustag , +.Nm rman_set_bushandle , +.Nm rman_get_bushandle , +.Nm rman_set_rid , +.Nm rman_get_rid .Nd resource management functions .Sh SYNOPSIS .In sys/rman.h @@ -69,36 +69,42 @@ .Fn rman_manage_region "struct rman *rm" "u_long start" "u_long end" .Ft int .Fn rman_release_resource "struct resource *r" -.Ft struct resource * -.Fn rman_reserve_resource "struct rman *rm" "u_long start" "u_long end" "u_long count" "u_int flags" "struct device *dev" -.Ft struct resource * -.Fn rman_reserve_resource_bound "struct rman *rm" "u_long start" "u_long end" "u_long count" "u_long bound" "u_int flags" "struct device *dev" +.Ft "struct resource *" +.Fo rman_reserve_resource +.Fa "struct rman *rm" "u_long start" "u_long end" "u_long count" +.Fa "u_int flags" "struct device *dev" +.Fc +.Ft "struct resource *" +.Fo rman_reserve_resource_bound +.Fa "struct rman *rm" "u_long start" "u_long end" "u_long count" +.Fa "u_long bound" "u_int flags" "struct device *dev" +.Fc .Ft uint32_t .Fn rman_make_alignment_flags "uint32_t size" -.Ft u_long -.Fn rman_get_start "struct resource *_r" .Ft u_long -.Fn rman_get_end "struct resource *_r" +.Fn rman_get_start "struct resource *r" .Ft u_long -.Fn rman_get_size "struct resource *_r" +.Fn rman_get_end "struct resource *r" +.Ft u_long +.Fn rman_get_size "struct resource *r" .Ft u_int -.Fn rman_get_flags "struct resource *_r" +.Fn rman_get_flags "struct resource *r" .Ft void -.Fn rman_set_virtual "struct resource *_r" "void *_v" -.Ft void * -.Fn rman_get_virtual "struct resource *_r" +.Fn rman_set_virtual "struct resource *r" "void *v" +.Ft "void *" +.Fn rman_get_virtual "struct resource *r" .Ft void -.Fn rman_set_bustag "struct resource *_r" "bus_space_tag_t _t" +.Fn rman_set_bustag "struct resource *r" "bus_space_tag_t t" .Ft bus_space_tag_t -.Fn rman_get_bustag "struct resource *_r" +.Fn rman_get_bustag "struct resource *r" .Ft void -.Fn rman_set_bushandle "struct resource *_r" "bus_space_handle_t _h" +.Fn rman_set_bushandle "struct resource *r" "bus_space_handle_t h" .Ft bus_space_handle_t -.Fn rman_get_bushandle "struct resource *_r" +.Fn rman_get_bushandle "struct resource *r" .Ft void -.Fn rman_set_rid "struct resource *_r" "int _rid" -.Ft int -.Fn rman_get_rid "struct resource *_r" +.Fn rman_set_rid "struct resource *r" "int rid" +.Ft int +.Fn rman_get_rid "struct resource *r" .Sh DESCRIPTION The .Nm @@ -137,8 +143,8 @@ The function frees any structures associated with the structure pointed to by the .Fa rm -argument. If any of the resources within the managed -region have the +argument. +If any of the resources within the managed region have the .Dv RF_ALLOCATED flag set, it will return .Er EBUSY ; @@ -153,7 +159,11 @@ control. The .Fa rman argument points to the region descriptor. -The start and end arguments specify the bounds of the region. +The +.Fa start +and +.Fa end +arguments specify the bounds of the region. .Pp .Em NOTE : This interface is not robust against programming errors which @@ -162,12 +172,17 @@ add multiple copies of the same region. The .Fn rman_reserve_resource_bound function is where the bulk of the -.Nm logic is located. +.Nm +logic is located. It attempts to reserve a contiguous range in the specified region .Fa rm for the use of the device .Fa dev . -The caller can specify the start and end of an acceptable range, as well as +The caller can specify the +.Fa start +and +.Fa end +of an acceptable range, as well as alignment, and the code will attempt to find a free segment which fits. The default behavior is to allocate an exclusive segment, unless the .Dv RF_SHAREABLE @@ -207,7 +222,7 @@ function marks a resource as active, by setting the flag. If this is a time shared resource, and the caller has not yet acquired the resource, the function returns -.Er EBUSY. +.Er EBUSY . .Pp The .Fn rman_deactivate_resource @@ -238,7 +253,8 @@ function. The .Fn rman_get_start , .Fn rman_get_end , -.Fn rman_get_size , and +.Fn rman_get_size , +and .Fn rman_get_flags functions return the bounds, size and flags of the previously reserved resource @@ -246,7 +262,8 @@ resource .Pp The .Fn rman_set_bustag -function associates a bus_space_tag_t +function associates a +.Vt bus_space_tag_t .Fa t with the resource .Fa r . @@ -256,7 +273,8 @@ function is used to retrieve this tag once set. .Pp The .Fn rman_set_bushandle -function associates a bus_space_handle_t +function associates a +.Vt bus_space_handle_t .Fa h with the resource .Fa r . @@ -276,7 +294,9 @@ The .Fn rman_set_rid function associates a resource identifier with a resource .Fa r . -The rman_get_rid function retrieves this RID. +The +.Fn rman_get_rid +function retrieves this RID. .Pp The .Fn rman_get_device