From fe5f4f64ebf0577c0e59a1e740a7a01831b7b408 Mon Sep 17 00:00:00 2001
From: njl <njl@FreeBSD.org>
Date: Tue, 27 Jan 2004 06:04:15 +0000
Subject: [PATCH] Document my adventures in newbus land.  Clarify some
 examples, especially that count is in bytes, not bits.  There are some
 drivers that I think make this mistake.  (I've seen counts of 16 in the
 tree).

---
 share/man/man9/bus_alloc_resource.9 | 27 ++++++++++++++++-----------
 share/man/man9/bus_set_resource.9   |  1 +
 2 files changed, 17 insertions(+), 11 deletions(-)

diff --git a/share/man/man9/bus_alloc_resource.9 b/share/man/man9/bus_alloc_resource.9
index b387d729eb46..b086caf3762a 100644
--- a/share/man/man9/bus_alloc_resource.9
+++ b/share/man/man9/bus_alloc_resource.9
@@ -85,17 +85,18 @@ You must not depend on the value you gave it earlier.
 and
 .Fa end
 are the start/end addresses of the resource.
-If you specify values of 0 for
+If you specify values of 0ul for
 .Fa start
-and ~0 for
+and ~0ul for
 .Fa end
 and 1 for
 .Fa count ,
 the default values for the bus are calculated.
 .It
 .Fa count
-is the size of the resource, e.g. the size of an I/O port (often
-1, but some devices override this).
+is the size of the resource.
+For example, the size of an I/O port is usually 1 byte (but some devices
+override this).
 If you specified the default values for
 .Fa start
 and
@@ -104,7 +105,7 @@ then the default value of the bus is used if
 .Fa count
 is smaller than the default value and
 .Fa count
-is used, if it is bigger as the default value.
+is used, if it is bigger than the default value.
 .It
 .Fa flags
 sets the flags for the resource.
@@ -118,10 +119,14 @@ The resource still needs to be activated with
 activate resource atomically.
 .It Dv RF_SHAREABLE
 resource permits contemporaneous sharing.
-Should always be set unless you know, that the resource cannot be shared.
-It is the bus-code's task to filter out the flag if the bus doesn't
-support sharing, which is, for example, the case for pccard/cardbus,
-which can or cannot share devices, depending on the bus.
+It should always be set unless you know that the resource cannot be shared.
+It is the bus driver's task to filter out the flag if the bus doesn't
+support sharing.
+For example,
+.Xr pccard 4
+cannot share IRQs while
+.Xr cardbus 4
+can.
 .It Dv RF_TIMESHARE
 resource permits time-division sharing.
 .El
@@ -131,7 +136,7 @@ A pointer to
 .Va struct res
 is returned on success, a null pointer otherwise.
 .Sh EXAMPLES
-This is some example code.
+This is some example code that allocates a 32-bit I/O port and an IRQ.
 The values of
 .Va portid
 and
@@ -144,7 +149,7 @@ should be saved in the softc of the device after these calls.
 	portid = 0;
 	irqid = 0;
 	portres = bus_alloc_resource(dev, SYS_RES_IOPORT, &portid,
-			0ul, ~0ul, 32, RF_ACTIVE);
+			0ul, ~0ul, 4, RF_ACTIVE);
 	irqres = bus_alloc_resource(dev, SYS_RES_IRQ, &irqid,
 			0ul, ~0ul, 1, RF_ACTIVE | RF_SHAREABLE);
 .Ed
diff --git a/share/man/man9/bus_set_resource.9 b/share/man/man9/bus_set_resource.9
index 27448b470f37..59e1a45c9724 100644
--- a/share/man/man9/bus_set_resource.9
+++ b/share/man/man9/bus_set_resource.9
@@ -82,6 +82,7 @@ A pointer to a bus specific handle that identifies the resource being allocated.
 The start address of this resource.
 .It Fa count
 The length of the resource.
+For example, the size of the memory in bytes.
 .El
 .Sh RETURN VALUES
 Zero is returned on success, otherwise an error is returned.