Expand all contractions in the developer's handbook.
This commit is contained in:
parent
55f6bdd638
commit
b1def32fd6
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=11371
16 changed files with 245 additions and 245 deletions
en_US.ISO8859-1/books
arch-handbook
developers-handbook
dma
ipv6
isa
kerneldebug
kobj
pci
policies
scsi
tools
vm
x86
|
@ -259,7 +259,7 @@
|
|||
<para>The values of port, IRQ and so on are converted to the
|
||||
resource values associated with the device. They are optional,
|
||||
depending on the device needs and abilities for
|
||||
auto-configuration. For example, some devices don't need DRQ
|
||||
auto-configuration. For example, some devices do not need DRQ
|
||||
at all and some allow the driver to read the IRQ setting from
|
||||
the device configuration ports. If a machine has multiple ISA
|
||||
buses the exact bus may be specified in the configuration
|
||||
|
@ -287,7 +287,7 @@
|
|||
|
||||
<para>If a driver supports both auto-identified and legacy
|
||||
devices and both kinds are installed at once in one machine
|
||||
then it's enough to describe in the config file the legacy
|
||||
then it is enough to describe in the config file the legacy
|
||||
devices only. The auto-identified devices will be added
|
||||
automatically.</para>
|
||||
|
||||
|
@ -359,8 +359,8 @@
|
|||
<para>Because the PnP devices are disabled when probing the
|
||||
legacy devices they will not be attached twice (once as legacy
|
||||
and once as PnP). But in case of device-dependent identify
|
||||
routines it's the responsibility of the driver to make sure
|
||||
that the same device won't be attached by the driver twice:
|
||||
routines it is the responsibility of the driver to make sure
|
||||
that the same device will not be attached by the driver twice:
|
||||
once as legacy user-configured and once as
|
||||
auto-identified.</para>
|
||||
|
||||
|
@ -393,7 +393,7 @@
|
|||
device_t and the bus resources associated with it. The drivers
|
||||
may access the configuration resources directly using
|
||||
functions resource_* for more complex cases of
|
||||
configuration. But generally it's not needed nor recommended,
|
||||
configuration. But generally it is not needed nor recommended,
|
||||
so this issue is not discussed further.</para>
|
||||
|
||||
<para>The bus resources are associated with each device. They
|
||||
|
@ -428,7 +428,7 @@
|
|||
SYS_RES_MEMORY numbered 0 and 1. The resource type has
|
||||
nothing to do with the C language type, all the resource
|
||||
values have the C language type "unsigned long" and must be
|
||||
cast as necessary. The resource numbers don't have to be
|
||||
cast as necessary. The resource numbers do not have to be
|
||||
contiguous although for ISA they normally would be. The
|
||||
permitted resource numbers for ISA devices are:</para>
|
||||
|
||||
|
@ -523,14 +523,14 @@
|
|||
<para>Allocate a resource as a range of count values not
|
||||
allocated by anyone else, somewhere between start and
|
||||
end. Alas, alignment is not supported. If the resource
|
||||
was not set yet it's automatically created. The special
|
||||
was not set yet it is automatically created. The special
|
||||
values of start 0 and end ~0 (all ones) means that the
|
||||
fixed values previously set by
|
||||
<function>bus_set_resource()</function> must be used
|
||||
instead: start and count as themselves and
|
||||
end=(start+count), in this case if the resource was not
|
||||
defined before then an error is returned. Although rid is
|
||||
passed by reference it's not set anywhere by the resource
|
||||
passed by reference it is not set anywhere by the resource
|
||||
allocation code of the ISA bus. (The other buses may use a
|
||||
different approach and modify it).</para>
|
||||
</listitem>
|
||||
|
@ -707,7 +707,7 @@
|
|||
address obtained using
|
||||
<function>rman_get_virtual()</function>. The older drivers
|
||||
used the function <function>pmap_mapdev()</function> for this
|
||||
purpose, which should not be used directly any more. Now it's
|
||||
purpose, which should not be used directly any more. Now it is
|
||||
one of the internal steps of resource activation.</para>
|
||||
|
||||
<para>Most of the ISA cards will have their memory configured
|
||||
|
@ -755,14 +755,14 @@
|
|||
tag requirements may be allocated (and later may be
|
||||
freed). This is normally used to allocate relatively
|
||||
long-living areas of memory for communication with the
|
||||
device. Loading of such memory into a map is trivial: it's
|
||||
device. Loading of such memory into a map is trivial: it is
|
||||
always considered as one chunk in the appropriate physical
|
||||
memory range.</para>
|
||||
|
||||
<para>Second, an arbitrary area of virtual memory may be loaded
|
||||
into a map. Each page of this memory will be checked for
|
||||
conformance to the map requirement. If it conforms then it's
|
||||
left at it's original location. If it is not then a fresh
|
||||
conformance to the map requirement. If it conforms then it is
|
||||
left at its original location. If it is not then a fresh
|
||||
conformant "bounce page" is allocated and used as intermediate
|
||||
storage. When writing the data from the non-conformant
|
||||
original pages they will be copied to their bounce pages first
|
||||
|
@ -860,7 +860,7 @@
|
|||
<listitem>
|
||||
<para><emphasis>maxsize</emphasis> - the maximal size of
|
||||
memory (in bytes) that may be allocated through this
|
||||
tag. In case it's difficult to estimate or could be
|
||||
tag. In case it is difficult to estimate or could be
|
||||
arbitrarily big, the value for ISA devices would be
|
||||
BUS_SPACE_MAXSIZE_24BIT.</para>
|
||||
</listitem>
|
||||
|
@ -876,7 +876,7 @@
|
|||
maps, they may be used only as parent tags. The
|
||||
practical limit for nsegments seems to be about 250-300,
|
||||
higher values will cause kernel stack overflow. But
|
||||
anyway the hardware normally can't support that many
|
||||
anyway the hardware normally can not support that many
|
||||
scatter-gather buffers.</para>
|
||||
</listitem>
|
||||
|
||||
|
@ -1162,7 +1162,7 @@
|
|||
<listitem>
|
||||
<para>
|
||||
<emphasis>error</emphasis> - indication of the
|
||||
segment number overflow: if it's set to EFBIG then
|
||||
segment number overflow: if it is set to EFBIG then
|
||||
the buffer did not fit into the maximal number of
|
||||
segments permitted by the tag. In this case only the
|
||||
permitted number of descriptors will be in the
|
||||
|
@ -1317,7 +1317,7 @@
|
|||
</para>
|
||||
<para>
|
||||
If the hardware does not support scatter-gather at all or
|
||||
the driver wants to support some buffer size even if it's
|
||||
the driver wants to support some buffer size even if it is
|
||||
heavily fragmented then the solution is to allocate a
|
||||
contiguous buffer in the driver and use it as intermediate
|
||||
storage if the original buffer does not fit.
|
||||
|
@ -1398,7 +1398,7 @@
|
|||
(void *) &psomedata, /*flags*/0); </programlisting>
|
||||
|
||||
<para>
|
||||
Looks a bit long and complicated but that's the way to do
|
||||
Looks a bit long and complicated but that is the way to do
|
||||
it. The practical consequence is: if multiple memory areas
|
||||
are allocated always together it would be a really good idea
|
||||
to combine them all into one structure and allocate as one
|
||||
|
@ -1441,7 +1441,7 @@
|
|||
1. If requests are completed by marking them explicitly as
|
||||
done (such as the CAM requests) then it would be simpler to
|
||||
put all the further processing into the callback driver
|
||||
which would mark the request when it's done. Then not much
|
||||
which would mark the request when it is done. Then not much
|
||||
extra synchronization is needed. For the flow control
|
||||
reasons it may be a good idea to freeze the request queue
|
||||
until this request gets completed.
|
||||
|
@ -1451,8 +1451,8 @@
|
|||
as classic read or write requests on character devices) then
|
||||
a synchronization flag should be set in the buffer
|
||||
descriptor and <function>tsleep()</function> called. Later
|
||||
when the callback gets called it will do it's processing and
|
||||
check this synchronization flag. If it's set then the
|
||||
when the callback gets called it will do its processing and
|
||||
check this synchronization flag. If it is set then the
|
||||
callback should issue a wakeup. In this approach the
|
||||
callback function could either do all the needed processing
|
||||
(just like the previous case) or simply save the segments
|
||||
|
@ -1470,7 +1470,7 @@
|
|||
<!-- Section Marked up by Wylie -->
|
||||
<para>
|
||||
The Direct Memory Access (DMA) is implemented in the ISA bus
|
||||
through the DMA controller (actually, two of them but that's
|
||||
through the DMA controller (actually, two of them but that is
|
||||
an irrelevant detail). To make the early ISA devices simple
|
||||
and cheap the logic of the bus control and address
|
||||
generation was concentrated in the DMA controller.
|
||||
|
@ -1544,7 +1544,7 @@
|
|||
</para>
|
||||
<para>
|
||||
Allocate a bounce buffer for use with the specified
|
||||
channel. The requested size of the buffer can't exceed
|
||||
channel. The requested size of the buffer can not exceed
|
||||
64KB. This bounce buffer will be automatically used
|
||||
later if a transfer buffer happens to be not
|
||||
physically contiguous or outside of the memory
|
||||
|
@ -1554,7 +1554,7 @@
|
|||
those allocated by
|
||||
<function>bus_dmamem_alloc()</function> with proper
|
||||
limitations) then <function>isa_dmainit()</function>
|
||||
does not have to be called. But it's quite convenient
|
||||
does not have to be called. But it is quite convenient
|
||||
to transfer arbitrary data using the DMA controller.
|
||||
The bounce buffer will automatically care of the
|
||||
scatter-gather issues.
|
||||
|
@ -1747,7 +1747,7 @@
|
|||
deallocated. If the probe completes successfully the
|
||||
descriptor will be preserved by the system and later passed
|
||||
to the routine <function>xxx_isa_attach()</function>. If a
|
||||
driver returns a negative value it can't be sure that it
|
||||
driver returns a negative value it can not be sure that it
|
||||
will have the highest priority and its attach routine will
|
||||
be called. So in this case it also must release all the
|
||||
resources before returning and if necessary allocate them
|
||||
|
@ -1805,7 +1805,7 @@
|
|||
return pnperror; </programlisting>
|
||||
|
||||
<para>
|
||||
No special treatment is required for the drivers which don't
|
||||
No special treatment is required for the drivers which do not
|
||||
support PnP because they pass an empty PnP ID table and will
|
||||
always get ENXIO if called on a PnP card.
|
||||
</para>
|
||||
|
@ -1836,7 +1836,7 @@
|
|||
The base port address is saved in the structure softc for
|
||||
future use. If it will be used very often then calling the
|
||||
resource function each time would be prohibitively slow. If
|
||||
we don't get a port we just return an error. Some device
|
||||
we do not get a port we just return an error. Some device
|
||||
drivers can instead be clever and try to probe all the
|
||||
possible ports, like this:
|
||||
</para>
|
||||
|
@ -1937,12 +1937,12 @@
|
|||
</para>
|
||||
|
||||
<para>
|
||||
Normally drivers don't set up the interrupt handlers until
|
||||
Normally drivers do not set up the interrupt handlers until
|
||||
the attach routine. Instead they do probes in the polling
|
||||
mode using the <function>DELAY()</function> function for
|
||||
timeout. The probe routine must never hang forever, all the
|
||||
waits for the device must be done with timeouts. If the
|
||||
device does not respond within the time it's probably broken
|
||||
device does not respond within the time it is probably broken
|
||||
or misconfigured and the driver must return error. When
|
||||
determining the timeout interval give the device some extra
|
||||
time to be on the safe side: although
|
||||
|
@ -1954,7 +1954,7 @@
|
|||
<para>
|
||||
If the probe routine really wants to check that the
|
||||
interrupts really work it may configure and probe the
|
||||
interrupts too. But that's not recommended.
|
||||
interrupts too. But that is not recommended.
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
|
@ -1995,7 +1995,7 @@
|
|||
both sources are available and different, which one should
|
||||
be used? Probably if the user bothered to set the address
|
||||
explicitly in the kernel configuration file they know what
|
||||
they're doing and this one should take precedence. An
|
||||
they are doing and this one should take precedence. An
|
||||
example of implementation could be:
|
||||
</para>
|
||||
<programlisting>
|
||||
|
@ -2073,7 +2073,7 @@
|
|||
|
||||
<para>
|
||||
That would be all for the probe routine. Freeing of
|
||||
resources is done from multiple places, so it's moved to a
|
||||
resources is done from multiple places, so it is moved to a
|
||||
function which may look like:
|
||||
</para>
|
||||
|
||||
|
@ -2415,7 +2415,7 @@
|
|||
with proprietary identification protocols). In any case
|
||||
disabling DMA and interrupts in the device registers and
|
||||
stopping any ongoing transfers is a good idea. The exact
|
||||
action depends on the hardware, so we don't consider it here
|
||||
action depends on the hardware, so we do not consider it here
|
||||
in any details.
|
||||
</para>
|
||||
</sect1>
|
||||
|
|
|
@ -139,7 +139,7 @@ KOBJMETHOD(NAME, FUNC)</programlisting>
|
|||
|
||||
<para>The <literal>INTERFACE</literal> keyword is used to define
|
||||
the interface name. This name is concatenated with each method
|
||||
name as [interface name]_[method name]. It's syntax is
|
||||
name as [interface name]_[method name]. Its syntax is
|
||||
INTERFACE [interface name];.</para>
|
||||
|
||||
<para>For example:</para>
|
||||
|
@ -147,7 +147,7 @@ KOBJMETHOD(NAME, FUNC)</programlisting>
|
|||
<programlisting>INTERFACE foo;</programlisting>
|
||||
|
||||
<para>The <literal>CODE</literal> keyword copies its arguments
|
||||
verbatim into the code file. It's syntax is
|
||||
verbatim into the code file. Its syntax is
|
||||
<literal>CODE { [whatever] };</literal></para>
|
||||
|
||||
<para>For example:</para>
|
||||
|
@ -159,7 +159,7 @@ KOBJMETHOD(NAME, FUNC)</programlisting>
|
|||
}
|
||||
};</programlisting>
|
||||
|
||||
<para>The <literal>METHOD</literal> keyword describes a method. It's syntax is
|
||||
<para>The <literal>METHOD</literal> keyword describes a method. Its syntax is
|
||||
<literal>METHOD [return type] [method name] { [object [,
|
||||
arguments]] };</literal></para>
|
||||
|
||||
|
@ -188,7 +188,7 @@ KOBJMETHOD(NAME, FUNC)</programlisting>
|
|||
} DEFAULT foo_hack;</programlisting>
|
||||
|
||||
<para>The <literal>STATICMETHOD</literal> keyword is used like
|
||||
the <literal>METHOD</literal> keyword except the kobj data isn't
|
||||
the <literal>METHOD</literal> keyword except the kobj data is not
|
||||
at the head of the object structure so casting to kobj_t would
|
||||
be incorrect. Instead <literal>STATICMETHOD</literal> relies on the Kobj data being
|
||||
referenced as 'ops'. This is also useful for calling
|
||||
|
|
|
@ -358,7 +358,7 @@ board_write(struct ni_softc *sc, uint16_t address, uint16_t value) {
|
|||
<sect2>
|
||||
<title>Deallocating Resources</title>
|
||||
|
||||
<para>It's very important to deallocate all of the resources
|
||||
<para>It is very important to deallocate all of the resources
|
||||
that were allocated during <function>attach()</function>.
|
||||
Care must be taken to deallocate the correct stuff even on a
|
||||
failure condition so that the system will remain usable while
|
||||
|
|
|
@ -1,7 +1,7 @@
|
|||
<!--
|
||||
The FreeBSD Documentation Project
|
||||
|
||||
$FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/scsi/chapter.sgml,v 1.4 2001/06/13 11:35:56 tom Exp $
|
||||
$FreeBSD$
|
||||
-->
|
||||
|
||||
<chapter id="scsi">
|
||||
|
@ -40,7 +40,7 @@
|
|||
|
||||
<para>The document is illustrated with examples in
|
||||
pseudo-code. Although sometimes the examples have many details
|
||||
and look like real code, it's still pseudo-code. It was written
|
||||
and look like real code, it is still pseudo-code. It was written
|
||||
to demonstrate the concepts in an understandable way. For a real
|
||||
driver other approaches may be more modular and efficient. It
|
||||
also abstracts from the hardware details, as well as issues that
|
||||
|
@ -56,7 +56,7 @@
|
|||
<sect1>
|
||||
<title>General architecture</title>
|
||||
|
||||
<para>CAM stands for Common Access Method. It's a generic way to
|
||||
<para>CAM stands for Common Access Method. It is a generic way to
|
||||
address the I/O buses in a SCSI-like way. This allows a
|
||||
separation of the generic device drivers from the drivers
|
||||
controlling the I/O bus: for example the disk driver becomes able
|
||||
|
@ -101,10 +101,10 @@
|
|||
<function>xxx_attach()</function> function (here and further
|
||||
xxx_ is used to denote the unique driver name prefix). The
|
||||
<function>xxx_attach()</function> function itself is called by
|
||||
the system bus auto-configuration code which we don't describe
|
||||
the system bus auto-configuration code which we do not describe
|
||||
here.</para>
|
||||
|
||||
<para>This is achieved in multiple steps: first it's necessary to
|
||||
<para>This is achieved in multiple steps: first it is necessary to
|
||||
allocate the queue of requests associated with this SIM:</para>
|
||||
|
||||
<programlisting> struct cam_devq *devq;
|
||||
|
@ -114,7 +114,7 @@
|
|||
}</programlisting>
|
||||
|
||||
<para>Here SIZE is the size of the queue to be allocated, maximal
|
||||
number of requests it could contain. It's the number of requests
|
||||
number of requests it could contain. It is the number of requests
|
||||
that the SIM driver can handle in parallel on one SCSI
|
||||
card. Commonly it can be calculated as:</para>
|
||||
|
||||
|
@ -242,7 +242,7 @@
|
|||
that transaction may be re-used to report this event (this is
|
||||
safe because the event path is copied in the event reporting
|
||||
routine but not deallocated nor passed anywhere further). Also
|
||||
it's safe to allocate paths dynamically at any time including
|
||||
it is safe to allocate paths dynamically at any time including
|
||||
the interrupt routines, although that incurs certain overhead,
|
||||
and a possible problem with this approach is that there may be
|
||||
no free memory at that time. For a bus reset event we need to
|
||||
|
@ -279,7 +279,7 @@
|
|||
"all LUNs")</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>If the driver can't allocate this path it won't be able to
|
||||
<para>If the driver can not allocate this path it will not be able to
|
||||
work normally, so in that case we dismantle that SCSI
|
||||
bus.</para>
|
||||
|
||||
|
@ -288,7 +288,7 @@
|
|||
that we save the value of sim (or we can also discard it on the
|
||||
exit from <function>xxx_probe()</function> if we wish).</para>
|
||||
|
||||
<para>That's all for a minimalistic initialization. To do things
|
||||
<para>That is all for a minimalistic initialization. To do things
|
||||
right there is one more issue left. </para>
|
||||
|
||||
<para>For a SIM driver there is one particularly interesting
|
||||
|
@ -394,7 +394,7 @@
|
|||
<para>Actually, the CCB status is not only assigned as a return
|
||||
code but a CCB has some status all the time. Before CCB is
|
||||
passed to the <function>xxx_action()</function> routine it gets
|
||||
the status CCB_REQ_INPROG meaning that it's in progress. There
|
||||
the status CCB_REQ_INPROG meaning that it is in progress. There
|
||||
are a surprising number of status values defined in
|
||||
<filename>/sys/cam/cam.h</filename> which should be able to
|
||||
represent the status of a request in great detail. More
|
||||
|
@ -543,7 +543,7 @@
|
|||
of tag to use:
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>CAM_TAG_ACTION_NONE - don't use tags for this
|
||||
<listitem><para>CAM_TAG_ACTION_NONE - do not use tags for this
|
||||
transaction</para></listitem>
|
||||
<listitem><para>MSG_SIMPLE_Q_TAG, MSG_HEAD_OF_Q_TAG,
|
||||
MSG_ORDERED_Q_TAG - value equal to the appropriate tag
|
||||
|
@ -587,7 +587,7 @@
|
|||
|
||||
<para>Then allocate whatever data structures (such as
|
||||
card-dependent hardware control block) we need to process this
|
||||
request. If we can't then freeze the SIM queue and remember
|
||||
request. If we ca not then freeze the SIM queue and remember
|
||||
that we have a pending operation, return the CCB back and ask
|
||||
CAM to re-queue it. Later when the resources become available
|
||||
the SIM queue must be unfrozen by returning a ccb with the
|
||||
|
@ -636,13 +636,13 @@
|
|||
due to special Alpha quirks. [IMHO it would be much better to
|
||||
have two separate functions, vtop() and ptobus() then vtobus()
|
||||
would be a simple superposition of them.] In case if a
|
||||
physical address is requested it's OK to return the CCB with
|
||||
physical address is requested it is OK to return the CCB with
|
||||
the status CAM_REQ_INVALID, the current drivers do that. But
|
||||
it's also possible to compile the Alpha-specific piece of
|
||||
it is also possible to compile the Alpha-specific piece of
|
||||
code, as in this example (there should be a more direct way to
|
||||
do that, without conditional compilation in the drivers). If
|
||||
necessary a physical address can be also converted or mapped
|
||||
back to a virtual address but with big pain, so we don't do
|
||||
back to a virtual address but with big pain, so we do not do
|
||||
that.</para>
|
||||
|
||||
<programlisting> if(ccb_h->flags & CAM_CDB_POINTER) {
|
||||
|
@ -664,7 +664,7 @@
|
|||
}
|
||||
hcb->cmdlen = csio->cdb_len;</programlisting>
|
||||
|
||||
<para>Now it's time to set up the data. Again, the data storage
|
||||
<para>Now it is time to set up the data. Again, the data storage
|
||||
may be specified in the CCB in many interesting ways,
|
||||
specified by the CCB flags. First we get the direction of the
|
||||
data transfer. The simplest case is if there is no data to
|
||||
|
@ -686,11 +686,11 @@
|
|||
implementation. See description of the SCSI command (CDB)
|
||||
handling for the details on the address-translation issues.
|
||||
If some variation is too difficult or impossible to implement
|
||||
with a particular card it's OK to return the status
|
||||
with a particular card it is OK to return the status
|
||||
CAM_REQ_INVALID. Actually, it seems like the scatter-gather
|
||||
ability is not used anywhere in the CAM code now. But at least
|
||||
the case for a single non-scattered virtual buffer must be
|
||||
implemented, it's actively used by CAM.</para>
|
||||
implemented, it is actively used by CAM.</para>
|
||||
|
||||
<programlisting> int rv;
|
||||
|
||||
|
@ -900,7 +900,7 @@
|
|||
return;
|
||||
}</programlisting>
|
||||
|
||||
<para>Then it's necessary to find this CCB in our queue. This can
|
||||
<para>Then it is necessary to find this CCB in our queue. This can
|
||||
be done by walking the list of all our hardware control blocks
|
||||
in search for one associated with this CCB:</para>
|
||||
|
||||
|
@ -933,7 +933,7 @@
|
|||
SCSI bus, being transferred right now, or disconnected and
|
||||
waiting for the result of the command, or actually completed by
|
||||
hardware but not yet marked as done by software. To make sure
|
||||
that we don't get in any races with hardware we mark the HCB as
|
||||
that we do not get in any races with hardware we mark the HCB as
|
||||
being aborted, so that if this HCB is about to be sent to the
|
||||
SCSI bus the SCSI controller will see this flag and skip
|
||||
it.</para>
|
||||
|
@ -1003,7 +1003,7 @@
|
|||
xpt_done(ccb);
|
||||
return;</programlisting>
|
||||
|
||||
<para>That's all for the ABORT request, although there is one more
|
||||
<para>That is all for the ABORT request, although there is one more
|
||||
issue. Because the ABORT message cleans all the ongoing
|
||||
transactions on a LUN we have to mark all the other active
|
||||
transactions on this LUN as aborted. That should be done in the
|
||||
|
@ -1091,7 +1091,7 @@ of the union ccb:</para>
|
|||
its ideas about the parameters. Setting the user parameters
|
||||
does not cause re-negotiation of the transfer rates. But when
|
||||
the SCSI controller does a negotiation it must never set the
|
||||
values higher than the user parameters, so it's essentially the
|
||||
values higher than the user parameters, so it is essentially the
|
||||
top boundary.</para>
|
||||
|
||||
<para>The current settings are, as the name says,
|
||||
|
@ -1540,7 +1540,7 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)<
|
|||
(probably caused by another SCSI controller on the same SCSI
|
||||
bus). If so we drop all the enqueued and disconnected requests,
|
||||
report the events and re-initialize our SCSI controller. It is
|
||||
important that during this initialization the controller won't
|
||||
important that during this initialization the controller will not
|
||||
issue another reset or else two controllers on the same SCSI bus
|
||||
could ping-pong resets forever. The case of fatal controller
|
||||
error/hang could be handled in the same place, but it will
|
||||
|
@ -1942,7 +1942,7 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)<
|
|||
<para>When the timeout for an HCB expires that request should be
|
||||
aborted, just like with an XPT_ABORT request. The only
|
||||
difference is that the returned status of aborted request should
|
||||
be CAM_CMD_TIMEOUT instead of CAM_REQ_ABORTED (that's why
|
||||
be CAM_CMD_TIMEOUT instead of CAM_REQ_ABORTED (that is why
|
||||
implementation of the abort better be done as a function). But
|
||||
there is one more possible problem: what if the abort request
|
||||
itself will get stuck? In this case the SCSI bus should be
|
||||
|
|
|
@ -1,7 +1,7 @@
|
|||
<!--
|
||||
The FreeBSD Documentation Project
|
||||
|
||||
$FreeBSD: doc/en_US.ISO_8859-1/books/developers-handbook/usb/chapter.sgml,v 1.1 2001/04/13 09:05:13 murray Exp $
|
||||
$FreeBSD$
|
||||
-->
|
||||
|
||||
<chapter id="vm">
|
||||
|
@ -149,7 +149,7 @@
|
|||
<literal>vm_map_t</literal>/<literal>vm_entry_t</literal>/
|
||||
<literal>vm_object_t</literal> hierarchy. Remember when I mentioned
|
||||
that physical pages are only directly associated with a
|
||||
<literal>vm_object</literal>. Well, that isn't quite true.
|
||||
<literal>vm_object</literal>. Well, that is not quite true.
|
||||
<literal>vm_page_t</literal>'s are also linked into page tables that
|
||||
they are actively associated with. One <literal>vm_page_t</literal>
|
||||
can be linked into several <emphasis>pmaps</emphasis>, as page tables
|
||||
|
|
|
@ -345,7 +345,7 @@
|
|||
values intact. The RAM chips actually handle the task of
|
||||
pumping power back into all of the appropriate locations in RAM,
|
||||
but they must be told when to do it by the rest of the computer
|
||||
so that the refresh activity won't interfere with the computer
|
||||
so that the refresh activity will not interfere with the computer
|
||||
wanting to access RAM normally. If the computer is unable to
|
||||
refresh memory, the contents of memory will become corrupted in
|
||||
just a few milliseconds.</para>
|
||||
|
|
|
@ -415,7 +415,7 @@
|
|||
like "fe80::1%ne0". This way you will be able to specify link-local
|
||||
scoped address without much trouble.</para>
|
||||
|
||||
<para>To use this extension in your program, you'll need to use
|
||||
<para>To use this extension in your program, you will need to use
|
||||
&man.getaddrinfo.3;, and &man.getnameinfo.3; with NI_WITHSCOPEID.
|
||||
The implementation currently assumes 1-to-1 relationship between a
|
||||
link and an interface, which is stronger than what specs say.</para>
|
||||
|
@ -771,7 +771,7 @@ fe80:2::%ep0/64 link#2 UC ep0</screen>
|
|||
packet with massive number of IPsec headers, kernel stack may blow
|
||||
up. IPsec-over-IPv6 is okay. (Off-course, for those all IPsec
|
||||
headers to be processed, each such IPsec header must pass each
|
||||
IPsec check. So an anonymous attacker won't be able to do such an
|
||||
IPsec check. So an anonymous attacker will not be able to do such an
|
||||
attack.)</para>
|
||||
</sect3>
|
||||
|
||||
|
@ -810,11 +810,11 @@ fe80:2::%ep0/64 link#2 UC ep0</screen>
|
|||
So, all IP6 functions except TCP never convert network byte
|
||||
order into host byte order, to save the original packet.</para>
|
||||
|
||||
<para>tcp_input(), udp6_input() and icmp6_input() can't assume that
|
||||
<para>tcp_input(), udp6_input() and icmp6_input() can not assume that
|
||||
IP6 header is preceding the transport headers due to extension
|
||||
headers. So, in6_cksum() was implemented to handle packets whose IP6
|
||||
header and transport header is not continuous. TCP/IP6 nor UDP6/IP6
|
||||
header structure don't exist for checksum calculation.</para>
|
||||
header structures do not exist for checksum calculation.</para>
|
||||
|
||||
<para>To process IP6 header, extension headers and transport headers
|
||||
easily, network drivers are now required to store packets in one
|
||||
|
@ -893,13 +893,13 @@ FreeBSD 4.x configurable supported
|
|||
about the behavior in the kernel. Using &man.getaddrinfo.3; is the
|
||||
safest way. Port number space and wildcard bind issues were discussed
|
||||
in detail on ipv6imp mailing list, in mid March 1999 and it looks
|
||||
that there's no concrete consensus (means, up to implementers).
|
||||
that there is no concrete consensus (means, up to implementers).
|
||||
You may want to check the mailing list archives.</para>
|
||||
|
||||
<para>If a server application would like to accept IPv4 and IPv6
|
||||
connections, there will be two alternatives.</para>
|
||||
|
||||
<para>One is using AF_INET and AF_INET6 socket (you'll need two
|
||||
<para>One is using AF_INET and AF_INET6 socket (you will need two
|
||||
sockets). Use &man.getaddrinfo.3; with AI_PASSIVE into ai_flags,
|
||||
and &man.socket.2; and &man.bind.2; to all the addresses returned.
|
||||
By opening multiple sockets, you can accept connections onto the
|
||||
|
@ -1028,7 +1028,7 @@ FreeBSD 4.x configurable supported
|
|||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>there's no AF_INET socket that matches the IPv4
|
||||
<para>there is no AF_INET socket that matches the IPv4
|
||||
connection</para>
|
||||
</listitem>
|
||||
|
||||
|
@ -1038,7 +1038,7 @@ FreeBSD 4.x configurable supported
|
|||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>There's no problem with open/close ordering.</para>
|
||||
<para>There is no problem with open/close ordering.</para>
|
||||
</sect5>
|
||||
|
||||
<sect5>
|
||||
|
@ -1057,7 +1057,7 @@ FreeBSD 4.x configurable supported
|
|||
<para>When RFC2553 was about to be finalized, there was discussion on
|
||||
how struct sockaddr_storage members are named. One proposal is to
|
||||
prepend "__" to the members (like "__ss_len") as they should not be
|
||||
touched. The other proposal was that don't prepend it (like "ss_len")
|
||||
touched. The other proposal was not to prepend it (like "ss_len")
|
||||
as we need to touch those members directly. There was no clear
|
||||
consensus on it.</para>
|
||||
|
||||
|
@ -1133,8 +1133,8 @@ FreeBSD 4.x configurable supported
|
|||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
<para>If any of the driver don't support the requirements, then
|
||||
the driver can't be used for IPv6 and/or IPsec communication. If
|
||||
<para>If any of the drivers do not support the requirements, then
|
||||
the drivers can not be used for IPv6 and/or IPsec communication. If
|
||||
you find any problem with your card using IPv6/IPsec, then, please
|
||||
report it to <email>freebsd-bugs@FreeBSD.org</email>.</para>
|
||||
|
||||
|
@ -1251,7 +1251,7 @@ FreeBSD 4.x configurable supported
|
|||
</para>
|
||||
|
||||
<para>The home-brew IKE daemon, "racoon" is included in the
|
||||
kit (kame/kame/racoon). Basically you'll need to run racoon as
|
||||
kit (kame/kame/racoon). Basically you will need to run racoon as
|
||||
daemon, then setup a policy to require keys (like
|
||||
<command>ping -P 'out ipsec esp/transport//use'</command>).
|
||||
The kernel will contact racoon daemon as necessary to exchange
|
||||
|
@ -1301,7 +1301,7 @@ FreeBSD 4.x configurable supported
|
|||
|
||||
<listitem>
|
||||
<para>Authentication model for AH tunnel must be revisited.
|
||||
We'll need to improve the policy management engine,
|
||||
We will need to improve the policy management engine,
|
||||
eventually.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
@ -1531,7 +1531,7 @@ ECN allowed copy TOS bits except for ECN use inner TOS bits with some
|
|||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>if both IPsec tunnel endpoint are capable of ECN-friendly
|
||||
behavior, you'd better configure both end to "ECN allowed"
|
||||
behavior, you should better configure both end to <quote>ECN allowed</quote>
|
||||
(sysctl value 1).</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
|
|
|
@ -259,7 +259,7 @@
|
|||
<para>The values of port, IRQ and so on are converted to the
|
||||
resource values associated with the device. They are optional,
|
||||
depending on the device needs and abilities for
|
||||
auto-configuration. For example, some devices don't need DRQ
|
||||
auto-configuration. For example, some devices do not need DRQ
|
||||
at all and some allow the driver to read the IRQ setting from
|
||||
the device configuration ports. If a machine has multiple ISA
|
||||
buses the exact bus may be specified in the configuration
|
||||
|
@ -287,7 +287,7 @@
|
|||
|
||||
<para>If a driver supports both auto-identified and legacy
|
||||
devices and both kinds are installed at once in one machine
|
||||
then it's enough to describe in the config file the legacy
|
||||
then it is enough to describe in the config file the legacy
|
||||
devices only. The auto-identified devices will be added
|
||||
automatically.</para>
|
||||
|
||||
|
@ -359,8 +359,8 @@
|
|||
<para>Because the PnP devices are disabled when probing the
|
||||
legacy devices they will not be attached twice (once as legacy
|
||||
and once as PnP). But in case of device-dependent identify
|
||||
routines it's the responsibility of the driver to make sure
|
||||
that the same device won't be attached by the driver twice:
|
||||
routines it is the responsibility of the driver to make sure
|
||||
that the same device will not be attached by the driver twice:
|
||||
once as legacy user-configured and once as
|
||||
auto-identified.</para>
|
||||
|
||||
|
@ -393,7 +393,7 @@
|
|||
device_t and the bus resources associated with it. The drivers
|
||||
may access the configuration resources directly using
|
||||
functions resource_* for more complex cases of
|
||||
configuration. But generally it's not needed nor recommended,
|
||||
configuration. But generally it is not needed nor recommended,
|
||||
so this issue is not discussed further.</para>
|
||||
|
||||
<para>The bus resources are associated with each device. They
|
||||
|
@ -428,7 +428,7 @@
|
|||
SYS_RES_MEMORY numbered 0 and 1. The resource type has
|
||||
nothing to do with the C language type, all the resource
|
||||
values have the C language type "unsigned long" and must be
|
||||
cast as necessary. The resource numbers don't have to be
|
||||
cast as necessary. The resource numbers do not have to be
|
||||
contiguous although for ISA they normally would be. The
|
||||
permitted resource numbers for ISA devices are:</para>
|
||||
|
||||
|
@ -523,14 +523,14 @@
|
|||
<para>Allocate a resource as a range of count values not
|
||||
allocated by anyone else, somewhere between start and
|
||||
end. Alas, alignment is not supported. If the resource
|
||||
was not set yet it's automatically created. The special
|
||||
was not set yet it is automatically created. The special
|
||||
values of start 0 and end ~0 (all ones) means that the
|
||||
fixed values previously set by
|
||||
<function>bus_set_resource()</function> must be used
|
||||
instead: start and count as themselves and
|
||||
end=(start+count), in this case if the resource was not
|
||||
defined before then an error is returned. Although rid is
|
||||
passed by reference it's not set anywhere by the resource
|
||||
passed by reference it is not set anywhere by the resource
|
||||
allocation code of the ISA bus. (The other buses may use a
|
||||
different approach and modify it).</para>
|
||||
</listitem>
|
||||
|
@ -707,7 +707,7 @@
|
|||
address obtained using
|
||||
<function>rman_get_virtual()</function>. The older drivers
|
||||
used the function <function>pmap_mapdev()</function> for this
|
||||
purpose, which should not be used directly any more. Now it's
|
||||
purpose, which should not be used directly any more. Now it is
|
||||
one of the internal steps of resource activation.</para>
|
||||
|
||||
<para>Most of the ISA cards will have their memory configured
|
||||
|
@ -755,14 +755,14 @@
|
|||
tag requirements may be allocated (and later may be
|
||||
freed). This is normally used to allocate relatively
|
||||
long-living areas of memory for communication with the
|
||||
device. Loading of such memory into a map is trivial: it's
|
||||
device. Loading of such memory into a map is trivial: it is
|
||||
always considered as one chunk in the appropriate physical
|
||||
memory range.</para>
|
||||
|
||||
<para>Second, an arbitrary area of virtual memory may be loaded
|
||||
into a map. Each page of this memory will be checked for
|
||||
conformance to the map requirement. If it conforms then it's
|
||||
left at it's original location. If it is not then a fresh
|
||||
conformance to the map requirement. If it conforms then it is
|
||||
left at its original location. If it is not then a fresh
|
||||
conformant "bounce page" is allocated and used as intermediate
|
||||
storage. When writing the data from the non-conformant
|
||||
original pages they will be copied to their bounce pages first
|
||||
|
@ -860,7 +860,7 @@
|
|||
<listitem>
|
||||
<para><emphasis>maxsize</emphasis> - the maximal size of
|
||||
memory (in bytes) that may be allocated through this
|
||||
tag. In case it's difficult to estimate or could be
|
||||
tag. In case it is difficult to estimate or could be
|
||||
arbitrarily big, the value for ISA devices would be
|
||||
BUS_SPACE_MAXSIZE_24BIT.</para>
|
||||
</listitem>
|
||||
|
@ -876,7 +876,7 @@
|
|||
maps, they may be used only as parent tags. The
|
||||
practical limit for nsegments seems to be about 250-300,
|
||||
higher values will cause kernel stack overflow. But
|
||||
anyway the hardware normally can't support that many
|
||||
anyway the hardware normally can not support that many
|
||||
scatter-gather buffers.</para>
|
||||
</listitem>
|
||||
|
||||
|
@ -1162,7 +1162,7 @@
|
|||
<listitem>
|
||||
<para>
|
||||
<emphasis>error</emphasis> - indication of the
|
||||
segment number overflow: if it's set to EFBIG then
|
||||
segment number overflow: if it is set to EFBIG then
|
||||
the buffer did not fit into the maximal number of
|
||||
segments permitted by the tag. In this case only the
|
||||
permitted number of descriptors will be in the
|
||||
|
@ -1317,7 +1317,7 @@
|
|||
</para>
|
||||
<para>
|
||||
If the hardware does not support scatter-gather at all or
|
||||
the driver wants to support some buffer size even if it's
|
||||
the driver wants to support some buffer size even if it is
|
||||
heavily fragmented then the solution is to allocate a
|
||||
contiguous buffer in the driver and use it as intermediate
|
||||
storage if the original buffer does not fit.
|
||||
|
@ -1398,7 +1398,7 @@
|
|||
(void *) &psomedata, /*flags*/0); </programlisting>
|
||||
|
||||
<para>
|
||||
Looks a bit long and complicated but that's the way to do
|
||||
Looks a bit long and complicated but that is the way to do
|
||||
it. The practical consequence is: if multiple memory areas
|
||||
are allocated always together it would be a really good idea
|
||||
to combine them all into one structure and allocate as one
|
||||
|
@ -1441,7 +1441,7 @@
|
|||
1. If requests are completed by marking them explicitly as
|
||||
done (such as the CAM requests) then it would be simpler to
|
||||
put all the further processing into the callback driver
|
||||
which would mark the request when it's done. Then not much
|
||||
which would mark the request when it is done. Then not much
|
||||
extra synchronization is needed. For the flow control
|
||||
reasons it may be a good idea to freeze the request queue
|
||||
until this request gets completed.
|
||||
|
@ -1451,8 +1451,8 @@
|
|||
as classic read or write requests on character devices) then
|
||||
a synchronization flag should be set in the buffer
|
||||
descriptor and <function>tsleep()</function> called. Later
|
||||
when the callback gets called it will do it's processing and
|
||||
check this synchronization flag. If it's set then the
|
||||
when the callback gets called it will do its processing and
|
||||
check this synchronization flag. If it is set then the
|
||||
callback should issue a wakeup. In this approach the
|
||||
callback function could either do all the needed processing
|
||||
(just like the previous case) or simply save the segments
|
||||
|
@ -1470,7 +1470,7 @@
|
|||
<!-- Section Marked up by Wylie -->
|
||||
<para>
|
||||
The Direct Memory Access (DMA) is implemented in the ISA bus
|
||||
through the DMA controller (actually, two of them but that's
|
||||
through the DMA controller (actually, two of them but that is
|
||||
an irrelevant detail). To make the early ISA devices simple
|
||||
and cheap the logic of the bus control and address
|
||||
generation was concentrated in the DMA controller.
|
||||
|
@ -1544,7 +1544,7 @@
|
|||
</para>
|
||||
<para>
|
||||
Allocate a bounce buffer for use with the specified
|
||||
channel. The requested size of the buffer can't exceed
|
||||
channel. The requested size of the buffer can not exceed
|
||||
64KB. This bounce buffer will be automatically used
|
||||
later if a transfer buffer happens to be not
|
||||
physically contiguous or outside of the memory
|
||||
|
@ -1554,7 +1554,7 @@
|
|||
those allocated by
|
||||
<function>bus_dmamem_alloc()</function> with proper
|
||||
limitations) then <function>isa_dmainit()</function>
|
||||
does not have to be called. But it's quite convenient
|
||||
does not have to be called. But it is quite convenient
|
||||
to transfer arbitrary data using the DMA controller.
|
||||
The bounce buffer will automatically care of the
|
||||
scatter-gather issues.
|
||||
|
@ -1747,7 +1747,7 @@
|
|||
deallocated. If the probe completes successfully the
|
||||
descriptor will be preserved by the system and later passed
|
||||
to the routine <function>xxx_isa_attach()</function>. If a
|
||||
driver returns a negative value it can't be sure that it
|
||||
driver returns a negative value it can not be sure that it
|
||||
will have the highest priority and its attach routine will
|
||||
be called. So in this case it also must release all the
|
||||
resources before returning and if necessary allocate them
|
||||
|
@ -1805,7 +1805,7 @@
|
|||
return pnperror; </programlisting>
|
||||
|
||||
<para>
|
||||
No special treatment is required for the drivers which don't
|
||||
No special treatment is required for the drivers which do not
|
||||
support PnP because they pass an empty PnP ID table and will
|
||||
always get ENXIO if called on a PnP card.
|
||||
</para>
|
||||
|
@ -1836,7 +1836,7 @@
|
|||
The base port address is saved in the structure softc for
|
||||
future use. If it will be used very often then calling the
|
||||
resource function each time would be prohibitively slow. If
|
||||
we don't get a port we just return an error. Some device
|
||||
we do not get a port we just return an error. Some device
|
||||
drivers can instead be clever and try to probe all the
|
||||
possible ports, like this:
|
||||
</para>
|
||||
|
@ -1937,12 +1937,12 @@
|
|||
</para>
|
||||
|
||||
<para>
|
||||
Normally drivers don't set up the interrupt handlers until
|
||||
Normally drivers do not set up the interrupt handlers until
|
||||
the attach routine. Instead they do probes in the polling
|
||||
mode using the <function>DELAY()</function> function for
|
||||
timeout. The probe routine must never hang forever, all the
|
||||
waits for the device must be done with timeouts. If the
|
||||
device does not respond within the time it's probably broken
|
||||
device does not respond within the time it is probably broken
|
||||
or misconfigured and the driver must return error. When
|
||||
determining the timeout interval give the device some extra
|
||||
time to be on the safe side: although
|
||||
|
@ -1954,7 +1954,7 @@
|
|||
<para>
|
||||
If the probe routine really wants to check that the
|
||||
interrupts really work it may configure and probe the
|
||||
interrupts too. But that's not recommended.
|
||||
interrupts too. But that is not recommended.
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
|
@ -1995,7 +1995,7 @@
|
|||
both sources are available and different, which one should
|
||||
be used? Probably if the user bothered to set the address
|
||||
explicitly in the kernel configuration file they know what
|
||||
they're doing and this one should take precedence. An
|
||||
they are doing and this one should take precedence. An
|
||||
example of implementation could be:
|
||||
</para>
|
||||
<programlisting>
|
||||
|
@ -2073,7 +2073,7 @@
|
|||
|
||||
<para>
|
||||
That would be all for the probe routine. Freeing of
|
||||
resources is done from multiple places, so it's moved to a
|
||||
resources is done from multiple places, so it is moved to a
|
||||
function which may look like:
|
||||
</para>
|
||||
|
||||
|
@ -2415,7 +2415,7 @@
|
|||
with proprietary identification protocols). In any case
|
||||
disabling DMA and interrupts in the device registers and
|
||||
stopping any ongoing transfers is a good idea. The exact
|
||||
action depends on the hardware, so we don't consider it here
|
||||
action depends on the hardware, so we do not consider it here
|
||||
in any details.
|
||||
</para>
|
||||
</sect1>
|
||||
|
|
|
@ -55,7 +55,7 @@
|
|||
<screen>&prompt.root; <userinput>cp kernel kernel.debug</userinput>
|
||||
&prompt.root; <userinput>strip -g kernel</userinput></screen>
|
||||
|
||||
<para>This stage isn't necessary, but it is recommended. (In
|
||||
<para>This stage is not necessary, but it is recommended. (In
|
||||
FreeBSD 4 and later releases this step is performed automatically
|
||||
at the end of the kernel <command>make</command> process.)
|
||||
When the kernel has been stripped, either automatically or by
|
||||
|
@ -591,7 +591,7 @@ Id Refs Address Size Name
|
|||
3 1 0xc0ad7000 2000 warp_saver.ko
|
||||
4 1 0xc0adc000 11000 linux.ko</screen>
|
||||
|
||||
<para>If you are debugging a crash dump, you'll need to walk the
|
||||
<para>If you are debugging a crash dump, you will need to walk the
|
||||
<literal>linker_files</literal> list, starting at
|
||||
<literal>linker_files->tqh_first</literal> and following the
|
||||
<literal>link.tqe_next</literal> pointers until you find the
|
||||
|
|
|
@ -139,7 +139,7 @@ KOBJMETHOD(NAME, FUNC)</programlisting>
|
|||
|
||||
<para>The <literal>INTERFACE</literal> keyword is used to define
|
||||
the interface name. This name is concatenated with each method
|
||||
name as [interface name]_[method name]. It's syntax is
|
||||
name as [interface name]_[method name]. Its syntax is
|
||||
INTERFACE [interface name];.</para>
|
||||
|
||||
<para>For example:</para>
|
||||
|
@ -147,7 +147,7 @@ KOBJMETHOD(NAME, FUNC)</programlisting>
|
|||
<programlisting>INTERFACE foo;</programlisting>
|
||||
|
||||
<para>The <literal>CODE</literal> keyword copies its arguments
|
||||
verbatim into the code file. It's syntax is
|
||||
verbatim into the code file. Its syntax is
|
||||
<literal>CODE { [whatever] };</literal></para>
|
||||
|
||||
<para>For example:</para>
|
||||
|
@ -159,7 +159,7 @@ KOBJMETHOD(NAME, FUNC)</programlisting>
|
|||
}
|
||||
};</programlisting>
|
||||
|
||||
<para>The <literal>METHOD</literal> keyword describes a method. It's syntax is
|
||||
<para>The <literal>METHOD</literal> keyword describes a method. Its syntax is
|
||||
<literal>METHOD [return type] [method name] { [object [,
|
||||
arguments]] };</literal></para>
|
||||
|
||||
|
@ -188,7 +188,7 @@ KOBJMETHOD(NAME, FUNC)</programlisting>
|
|||
} DEFAULT foo_hack;</programlisting>
|
||||
|
||||
<para>The <literal>STATICMETHOD</literal> keyword is used like
|
||||
the <literal>METHOD</literal> keyword except the kobj data isn't
|
||||
the <literal>METHOD</literal> keyword except the kobj data is not
|
||||
at the head of the object structure so casting to kobj_t would
|
||||
be incorrect. Instead <literal>STATICMETHOD</literal> relies on the Kobj data being
|
||||
referenced as 'ops'. This is also useful for calling
|
||||
|
|
|
@ -358,7 +358,7 @@ board_write(struct ni_softc *sc, uint16_t address, uint16_t value) {
|
|||
<sect2>
|
||||
<title>Deallocating Resources</title>
|
||||
|
||||
<para>It's very important to deallocate all of the resources
|
||||
<para>It is very important to deallocate all of the resources
|
||||
that were allocated during <function>attach()</function>.
|
||||
Care must be taken to deallocate the correct stuff even on a
|
||||
failure condition so that the system will remain usable while
|
||||
|
|
|
@ -43,7 +43,7 @@
|
|||
|
||||
<para>It is of course not acceptable to add a person or group as
|
||||
maintainer unless they agree to assume this duty. On the other hand it
|
||||
doesn't have to be a committer and it can easily be a group of
|
||||
does not have to be a committer and it can easily be a group of
|
||||
people.</para>
|
||||
</sect1>
|
||||
|
||||
|
@ -320,7 +320,7 @@ obrien@FreeBSD.org - 30 March 1997</programlisting>
|
|||
December 1996.</emphasis></para>
|
||||
|
||||
<para>If you are adding shared library support to a port or other piece of
|
||||
software that doesn't have one, the version numbers should follow these
|
||||
software that does not have one, the version numbers should follow these
|
||||
rules. Generally, the resulting numbers will have nothing to do with
|
||||
the release version of the software.</para>
|
||||
|
||||
|
|
|
@ -1,7 +1,7 @@
|
|||
<!--
|
||||
The FreeBSD Documentation Project
|
||||
|
||||
$FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/scsi/chapter.sgml,v 1.4 2001/06/13 11:35:56 tom Exp $
|
||||
$FreeBSD$
|
||||
-->
|
||||
|
||||
<chapter id="scsi">
|
||||
|
@ -40,7 +40,7 @@
|
|||
|
||||
<para>The document is illustrated with examples in
|
||||
pseudo-code. Although sometimes the examples have many details
|
||||
and look like real code, it's still pseudo-code. It was written
|
||||
and look like real code, it is still pseudo-code. It was written
|
||||
to demonstrate the concepts in an understandable way. For a real
|
||||
driver other approaches may be more modular and efficient. It
|
||||
also abstracts from the hardware details, as well as issues that
|
||||
|
@ -56,7 +56,7 @@
|
|||
<sect1>
|
||||
<title>General architecture</title>
|
||||
|
||||
<para>CAM stands for Common Access Method. It's a generic way to
|
||||
<para>CAM stands for Common Access Method. It is a generic way to
|
||||
address the I/O buses in a SCSI-like way. This allows a
|
||||
separation of the generic device drivers from the drivers
|
||||
controlling the I/O bus: for example the disk driver becomes able
|
||||
|
@ -101,10 +101,10 @@
|
|||
<function>xxx_attach()</function> function (here and further
|
||||
xxx_ is used to denote the unique driver name prefix). The
|
||||
<function>xxx_attach()</function> function itself is called by
|
||||
the system bus auto-configuration code which we don't describe
|
||||
the system bus auto-configuration code which we do not describe
|
||||
here.</para>
|
||||
|
||||
<para>This is achieved in multiple steps: first it's necessary to
|
||||
<para>This is achieved in multiple steps: first it is necessary to
|
||||
allocate the queue of requests associated with this SIM:</para>
|
||||
|
||||
<programlisting> struct cam_devq *devq;
|
||||
|
@ -114,7 +114,7 @@
|
|||
}</programlisting>
|
||||
|
||||
<para>Here SIZE is the size of the queue to be allocated, maximal
|
||||
number of requests it could contain. It's the number of requests
|
||||
number of requests it could contain. It is the number of requests
|
||||
that the SIM driver can handle in parallel on one SCSI
|
||||
card. Commonly it can be calculated as:</para>
|
||||
|
||||
|
@ -242,7 +242,7 @@
|
|||
that transaction may be re-used to report this event (this is
|
||||
safe because the event path is copied in the event reporting
|
||||
routine but not deallocated nor passed anywhere further). Also
|
||||
it's safe to allocate paths dynamically at any time including
|
||||
it is safe to allocate paths dynamically at any time including
|
||||
the interrupt routines, although that incurs certain overhead,
|
||||
and a possible problem with this approach is that there may be
|
||||
no free memory at that time. For a bus reset event we need to
|
||||
|
@ -279,7 +279,7 @@
|
|||
"all LUNs")</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>If the driver can't allocate this path it won't be able to
|
||||
<para>If the driver can not allocate this path it will not be able to
|
||||
work normally, so in that case we dismantle that SCSI
|
||||
bus.</para>
|
||||
|
||||
|
@ -288,7 +288,7 @@
|
|||
that we save the value of sim (or we can also discard it on the
|
||||
exit from <function>xxx_probe()</function> if we wish).</para>
|
||||
|
||||
<para>That's all for a minimalistic initialization. To do things
|
||||
<para>That is all for a minimalistic initialization. To do things
|
||||
right there is one more issue left. </para>
|
||||
|
||||
<para>For a SIM driver there is one particularly interesting
|
||||
|
@ -394,7 +394,7 @@
|
|||
<para>Actually, the CCB status is not only assigned as a return
|
||||
code but a CCB has some status all the time. Before CCB is
|
||||
passed to the <function>xxx_action()</function> routine it gets
|
||||
the status CCB_REQ_INPROG meaning that it's in progress. There
|
||||
the status CCB_REQ_INPROG meaning that it is in progress. There
|
||||
are a surprising number of status values defined in
|
||||
<filename>/sys/cam/cam.h</filename> which should be able to
|
||||
represent the status of a request in great detail. More
|
||||
|
@ -543,7 +543,7 @@
|
|||
of tag to use:
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>CAM_TAG_ACTION_NONE - don't use tags for this
|
||||
<listitem><para>CAM_TAG_ACTION_NONE - do not use tags for this
|
||||
transaction</para></listitem>
|
||||
<listitem><para>MSG_SIMPLE_Q_TAG, MSG_HEAD_OF_Q_TAG,
|
||||
MSG_ORDERED_Q_TAG - value equal to the appropriate tag
|
||||
|
@ -587,7 +587,7 @@
|
|||
|
||||
<para>Then allocate whatever data structures (such as
|
||||
card-dependent hardware control block) we need to process this
|
||||
request. If we can't then freeze the SIM queue and remember
|
||||
request. If we ca not then freeze the SIM queue and remember
|
||||
that we have a pending operation, return the CCB back and ask
|
||||
CAM to re-queue it. Later when the resources become available
|
||||
the SIM queue must be unfrozen by returning a ccb with the
|
||||
|
@ -636,13 +636,13 @@
|
|||
due to special Alpha quirks. [IMHO it would be much better to
|
||||
have two separate functions, vtop() and ptobus() then vtobus()
|
||||
would be a simple superposition of them.] In case if a
|
||||
physical address is requested it's OK to return the CCB with
|
||||
physical address is requested it is OK to return the CCB with
|
||||
the status CAM_REQ_INVALID, the current drivers do that. But
|
||||
it's also possible to compile the Alpha-specific piece of
|
||||
it is also possible to compile the Alpha-specific piece of
|
||||
code, as in this example (there should be a more direct way to
|
||||
do that, without conditional compilation in the drivers). If
|
||||
necessary a physical address can be also converted or mapped
|
||||
back to a virtual address but with big pain, so we don't do
|
||||
back to a virtual address but with big pain, so we do not do
|
||||
that.</para>
|
||||
|
||||
<programlisting> if(ccb_h->flags & CAM_CDB_POINTER) {
|
||||
|
@ -664,7 +664,7 @@
|
|||
}
|
||||
hcb->cmdlen = csio->cdb_len;</programlisting>
|
||||
|
||||
<para>Now it's time to set up the data. Again, the data storage
|
||||
<para>Now it is time to set up the data. Again, the data storage
|
||||
may be specified in the CCB in many interesting ways,
|
||||
specified by the CCB flags. First we get the direction of the
|
||||
data transfer. The simplest case is if there is no data to
|
||||
|
@ -686,11 +686,11 @@
|
|||
implementation. See description of the SCSI command (CDB)
|
||||
handling for the details on the address-translation issues.
|
||||
If some variation is too difficult or impossible to implement
|
||||
with a particular card it's OK to return the status
|
||||
with a particular card it is OK to return the status
|
||||
CAM_REQ_INVALID. Actually, it seems like the scatter-gather
|
||||
ability is not used anywhere in the CAM code now. But at least
|
||||
the case for a single non-scattered virtual buffer must be
|
||||
implemented, it's actively used by CAM.</para>
|
||||
implemented, it is actively used by CAM.</para>
|
||||
|
||||
<programlisting> int rv;
|
||||
|
||||
|
@ -900,7 +900,7 @@
|
|||
return;
|
||||
}</programlisting>
|
||||
|
||||
<para>Then it's necessary to find this CCB in our queue. This can
|
||||
<para>Then it is necessary to find this CCB in our queue. This can
|
||||
be done by walking the list of all our hardware control blocks
|
||||
in search for one associated with this CCB:</para>
|
||||
|
||||
|
@ -933,7 +933,7 @@
|
|||
SCSI bus, being transferred right now, or disconnected and
|
||||
waiting for the result of the command, or actually completed by
|
||||
hardware but not yet marked as done by software. To make sure
|
||||
that we don't get in any races with hardware we mark the HCB as
|
||||
that we do not get in any races with hardware we mark the HCB as
|
||||
being aborted, so that if this HCB is about to be sent to the
|
||||
SCSI bus the SCSI controller will see this flag and skip
|
||||
it.</para>
|
||||
|
@ -1003,7 +1003,7 @@
|
|||
xpt_done(ccb);
|
||||
return;</programlisting>
|
||||
|
||||
<para>That's all for the ABORT request, although there is one more
|
||||
<para>That is all for the ABORT request, although there is one more
|
||||
issue. Because the ABORT message cleans all the ongoing
|
||||
transactions on a LUN we have to mark all the other active
|
||||
transactions on this LUN as aborted. That should be done in the
|
||||
|
@ -1091,7 +1091,7 @@ of the union ccb:</para>
|
|||
its ideas about the parameters. Setting the user parameters
|
||||
does not cause re-negotiation of the transfer rates. But when
|
||||
the SCSI controller does a negotiation it must never set the
|
||||
values higher than the user parameters, so it's essentially the
|
||||
values higher than the user parameters, so it is essentially the
|
||||
top boundary.</para>
|
||||
|
||||
<para>The current settings are, as the name says,
|
||||
|
@ -1540,7 +1540,7 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)<
|
|||
(probably caused by another SCSI controller on the same SCSI
|
||||
bus). If so we drop all the enqueued and disconnected requests,
|
||||
report the events and re-initialize our SCSI controller. It is
|
||||
important that during this initialization the controller won't
|
||||
important that during this initialization the controller will not
|
||||
issue another reset or else two controllers on the same SCSI bus
|
||||
could ping-pong resets forever. The case of fatal controller
|
||||
error/hang could be handled in the same place, but it will
|
||||
|
@ -1942,7 +1942,7 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)<
|
|||
<para>When the timeout for an HCB expires that request should be
|
||||
aborted, just like with an XPT_ABORT request. The only
|
||||
difference is that the returned status of aborted request should
|
||||
be CAM_CMD_TIMEOUT instead of CAM_REQ_ABORTED (that's why
|
||||
be CAM_CMD_TIMEOUT instead of CAM_REQ_ABORTED (that is why
|
||||
implementation of the abort better be done as a function). But
|
||||
there is one more possible problem: what if the abort request
|
||||
itself will get stuck? In this case the SCSI bus should be
|
||||
|
|
|
@ -50,7 +50,7 @@
|
|||
platforms.</para>
|
||||
|
||||
<para>However, all this power can be rather overwhelming at first
|
||||
if you've never written programs on a Unix platform before.
|
||||
if you have never written programs on a Unix platform before.
|
||||
This document aims to help you get up and running, without
|
||||
getting too deeply into more advanced topics. The intention is
|
||||
that this document should give you enough of the basics to be
|
||||
|
@ -140,7 +140,7 @@
|
|||
University students to program and provided with every
|
||||
self-respecting personal computer in the 1980s,
|
||||
<acronym>BASIC</acronym> has been the first programming
|
||||
language for many programmers. It's also the foundation
|
||||
language for many programmers. It is also the foundation
|
||||
for Visual Basic.</para>
|
||||
|
||||
<para>The <ulink
|
||||
|
@ -261,7 +261,7 @@
|
|||
which are very difficult or even impossible with an
|
||||
interpreter, such as writing code which interacts closely with
|
||||
the operating system—or even writing your own operating
|
||||
system! It's also useful if you need to write very efficient
|
||||
system! It is also useful if you need to write very efficient
|
||||
code, as the compiler can take its time and optimise the code,
|
||||
which would not be acceptable in an interpreter. And
|
||||
distributing a program written for a compiler is usually more
|
||||
|
@ -273,7 +273,7 @@
|
|||
are rather unforgiving languages, and best suited to more
|
||||
experienced programmers; Pascal, on the other hand, was
|
||||
designed as an educational language, and is quite a good
|
||||
language to start with. FreeBSD doesn't include Pascal
|
||||
language to start with. FreeBSD does not include Pascal
|
||||
support in the base system, but the GNU Pascal Compiler (gpc)
|
||||
is available in the ports collection.</para>
|
||||
|
||||
|
@ -303,7 +303,7 @@
|
|||
in the documentation and on-line help for the
|
||||
interpreter.</para>
|
||||
|
||||
<para>Once you've written your masterpiece, the next step is to
|
||||
<para>Once you have written your masterpiece, the next step is to
|
||||
convert it into something that will (hopefully!) run on FreeBSD.
|
||||
This usually involves several steps, each of which is done by a
|
||||
separate program.</para>
|
||||
|
@ -388,9 +388,9 @@
|
|||
sort.
|
||||
|
||||
<footnote>
|
||||
<para>In case you didn't know, a binary sort is an efficient
|
||||
<para>In case you did not know, a binary sort is an efficient
|
||||
way of sorting things into order and a bubble sort
|
||||
isn't.</para>
|
||||
is not.</para>
|
||||
</footnote></para>
|
||||
|
||||
<para>There are lots and lots of options for <command>cc</command>, which
|
||||
|
@ -452,7 +452,7 @@
|
|||
all this extra information makes the program much bigger.
|
||||
Normally, you compile with <option>-g</option> while you
|
||||
are developing a program and then compile a <quote>release
|
||||
version</quote> without <option>-g</option> when you're
|
||||
version</quote> without <option>-g</option> when you are
|
||||
satisfied it works properly.</para>
|
||||
|
||||
<informalexample>
|
||||
|
@ -464,7 +464,7 @@
|
|||
program.
|
||||
|
||||
<footnote>
|
||||
<para>Note, we didn't use the <option>-o</option> flag
|
||||
<para>Note, we did not use the <option>-o</option> flag
|
||||
to specify the executable name, so we will get an
|
||||
executable called <filename>a.out</filename>.
|
||||
Producing a debug version called
|
||||
|
@ -854,7 +854,7 @@ int main() {
|
|||
<qandaentry>
|
||||
<question>
|
||||
<para>When my program dumped core, it said something about
|
||||
a <errorname>segmentation fault</errorname>. What's
|
||||
a <errorname>segmentation fault</errorname>. What is
|
||||
that?</para>
|
||||
</question>
|
||||
|
||||
|
@ -877,7 +877,7 @@ strcpy(foo, "bang!");
|
|||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Using a pointer that hasn't been initialised,
|
||||
<para>Using a pointer that has not been initialised,
|
||||
eg</para>
|
||||
|
||||
<programlisting>char *foo;
|
||||
|
@ -886,9 +886,9 @@ strcpy(foo, "bang!");
|
|||
|
||||
<para>The pointer will have some random value that,
|
||||
with luck, will point into an area of memory that
|
||||
isn't available to your program and the kernel will
|
||||
is not available to your program and the kernel will
|
||||
kill your program before it can do any damage. If
|
||||
you're unlucky, it'll point somewhere inside your
|
||||
you are unlucky, it will point somewhere inside your
|
||||
own program and corrupt one of your data structures,
|
||||
causing the program to fail mysteriously.</para>
|
||||
</listitem>
|
||||
|
@ -954,7 +954,7 @@ free(foo);
|
|||
<para>No, fortunately not (unless of course you really do
|
||||
have a hardware problem…). This is usually
|
||||
another way of saying that you accessed memory in a way
|
||||
you shouldn't have.</para>
|
||||
you should not have.</para>
|
||||
</answer>
|
||||
</qandaentry>
|
||||
|
||||
|
@ -962,7 +962,7 @@ free(foo);
|
|||
<question>
|
||||
<para>This dumping core business sounds as though it could
|
||||
be quite useful, if I can make it happen when I want to.
|
||||
Can I do this, or do I have to wait until there's an
|
||||
Can I do this, or do I have to wait until there is an
|
||||
error?</para>
|
||||
</question>
|
||||
|
||||
|
@ -993,7 +993,7 @@ free(foo);
|
|||
of &man.abort.3; to learn more.</para>
|
||||
|
||||
<para>If you want to create a core dump from outside your
|
||||
program, but don't want the process to terminate, you
|
||||
program, but do not want the process to terminate, you
|
||||
can use the <command>gcore</command> program. See the
|
||||
man page of &man.gcore.1 for more information.</para>
|
||||
|
||||
|
@ -1009,7 +1009,7 @@ free(foo);
|
|||
<sect2>
|
||||
<title>What is <command>make</command>?</title>
|
||||
|
||||
<para>When you're working on a simple program with only one or
|
||||
<para>When you are working on a simple program with only one or
|
||||
two source files, typing in</para>
|
||||
|
||||
<screen>&prompt.user; <userinput>cc file1.c file2.c</userinput></screen>
|
||||
|
@ -1024,9 +1024,9 @@ free(foo);
|
|||
|
||||
<screen>&prompt.user; <userinput>cc file1.o file2.o</userinput> … <userinput>file37.c</userinput> &hellip</screen>
|
||||
|
||||
<para>if we'd changed <filename>file37.c</filename>, but not any
|
||||
<para>if we had changed <filename>file37.c</filename>, but not any
|
||||
of the others, since the last time we compiled. This may
|
||||
speed up the compilation quite a bit, but doesn't solve the
|
||||
speed up the compilation quite a bit, but does not solve the
|
||||
typing problem.</para>
|
||||
|
||||
<para>Or we could write a shell script to solve the typing
|
||||
|
@ -1034,20 +1034,20 @@ free(foo);
|
|||
very inefficient on a large project.</para>
|
||||
|
||||
<para>What happens if we have hundreds of source files lying
|
||||
about? What if we're working in a team with other people who
|
||||
forget to tell us when they've changed one of their source
|
||||
about? What if we are working in a team with other people who
|
||||
forget to tell us when they have changed one of their source
|
||||
files that we use?</para>
|
||||
|
||||
<para>Perhaps we could put the two solutions together and write
|
||||
something like a shell script that would contain some kind of
|
||||
magic rule saying when a source file needs compiling. Now all
|
||||
we need now is a program that can understand these rules, as
|
||||
it's a bit too complicated for the shell.</para>
|
||||
it is a bit too complicated for the shell.</para>
|
||||
|
||||
<para>This program is called <command>make</command>. It reads
|
||||
in a file, called a <firstterm>makefile</firstterm>, that
|
||||
tells it how different files depend on each other, and works
|
||||
out which files need to be re-compiled and which ones don't.
|
||||
out which files need to be re-compiled and which ones do not.
|
||||
For example, a rule could say something like <quote>if
|
||||
<filename>fromboz.o</filename> is older than
|
||||
<filename>fromboz.c</filename>, that means someone must have
|
||||
|
@ -1065,7 +1065,7 @@ free(foo);
|
|||
seen.
|
||||
|
||||
<footnote>
|
||||
<para>They don't use the <filename>MAKEFILE</filename> form
|
||||
<para>They do not use the <filename>MAKEFILE</filename> form
|
||||
as block capitals are often used for documentation files
|
||||
like <filename>README</filename>.</para>
|
||||
</footnote></para>
|
||||
|
@ -1074,7 +1074,7 @@ free(foo);
|
|||
<sect2>
|
||||
<title>Example of using <command>make</command></title>
|
||||
|
||||
<para>Here's a very simple make file:</para>
|
||||
<para>Here is a very simple make file:</para>
|
||||
|
||||
<programlisting>foo: foo.c
|
||||
cc -o foo foo.c</programlisting>
|
||||
|
@ -1114,7 +1114,7 @@ free(foo);
|
|||
world</userinput> in the appropriate directory!</para>
|
||||
|
||||
<para>Another useful property of makefiles is that the targets
|
||||
don't have to be programs. For instance, we could have a make
|
||||
do not have to be programs. For instance, we could have a make
|
||||
file that looks like this:</para>
|
||||
|
||||
<programlisting>foo: foo.c
|
||||
|
@ -1141,7 +1141,7 @@ install:
|
|||
<filename>foo</filename> if necessary, and then stop without
|
||||
going on to the <action>install</action> target.</para>
|
||||
|
||||
<para>Notice that the <action>install</action> target doesn't
|
||||
<para>Notice that the <action>install</action> target does not
|
||||
actually depend on anything! This means that the command on
|
||||
the following line is always executed when we try to make that
|
||||
target by typing <userinput>make install</userinput>. In this
|
||||
|
@ -1151,7 +1151,7 @@ install:
|
|||
directory when it has been correctly compiled.</para>
|
||||
|
||||
<para>This is a slightly confusing subject to try and explain.
|
||||
If you don't quite understand how <command>make</command>
|
||||
If you do not quite understand how <command>make</command>
|
||||
works, the best thing to do is to write a simple program like
|
||||
<quote>hello world</quote> and a make file like the one above
|
||||
and experiment. Then progress to using more than one source
|
||||
|
@ -1166,7 +1166,7 @@ install:
|
|||
|
||||
<para>C code often starts with a list of files to include, for
|
||||
example stdio.h. Some of these files are system-include
|
||||
files, some of them are from the project you're now working
|
||||
files, some of them are from the project you are now working
|
||||
on:
|
||||
</para>
|
||||
|
||||
|
@ -1206,7 +1206,7 @@ int main(....</programlisting>
|
|||
you run <command>make</command> all files depending on
|
||||
<filename>foo.h</filename> will be recompiled.</para>
|
||||
|
||||
<para>Don't forget to run <command>make depend</command> each
|
||||
<para>Do not forget to run <command>make depend</command> each
|
||||
time you add an include-file to one of your files.</para>
|
||||
</sect2>
|
||||
|
||||
|
@ -1216,7 +1216,7 @@ int main(....</programlisting>
|
|||
<para>Makefiles can be rather complicated to write. Fortunately,
|
||||
BSD-based systems like FreeBSD come with some very powerful
|
||||
ones as part of the system. One very good example of this is
|
||||
the FreeBSD ports system. Here's the essential part of a
|
||||
the FreeBSD ports system. Here is the essential part of a
|
||||
typical ports <filename>Makefile</filename>:</para>
|
||||
|
||||
<programlisting>MASTER_SITES= ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/
|
||||
|
@ -1234,7 +1234,7 @@ DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz
|
|||
</step>
|
||||
|
||||
<step>
|
||||
<para>If it isn't, an FTP connection to the URL in
|
||||
<para>If it is not, an FTP connection to the URL in
|
||||
<symbol>MASTER_SITES</symbol> is set up to download the
|
||||
source.</para>
|
||||
</step>
|
||||
|
@ -1281,22 +1281,22 @@ DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz
|
|||
</step>
|
||||
</procedure>
|
||||
|
||||
<para>Now I think you'll agree that's rather impressive for a
|
||||
<para>Now I think you will agree that is rather impressive for a
|
||||
four line script!</para>
|
||||
|
||||
<para>The secret lies in the last line, which tells
|
||||
<command>make</command> to look in the system makefile called
|
||||
<filename>bsd.port.mk</filename>. It's easy to overlook this
|
||||
<filename>bsd.port.mk</filename>. It is easy to overlook this
|
||||
line, but this is where all the clever stuff comes
|
||||
from—someone has written a makefile that tells
|
||||
<command>make</command> to do all the things above (plus a
|
||||
couple of other things I didn't mention, including handling
|
||||
couple of other things I did not mention, including handling
|
||||
any errors that may occur) and anyone can get access to that
|
||||
just by putting a single line in their own make file!</para>
|
||||
|
||||
<para>If you want to have a look at these system makefiles,
|
||||
they're in <filename>/usr/share/mk</filename>, but it's
|
||||
probably best to wait until you've had a bit of practice with
|
||||
they are in <filename>/usr/share/mk</filename>, but it is
|
||||
probably best to wait until you have had a bit of practice with
|
||||
makefiles, as they are very complicated (and if you do look at
|
||||
them, make sure you have a flask of strong coffee
|
||||
handy!)</para>
|
||||
|
@ -1326,7 +1326,7 @@ DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz
|
|||
make</application>, which has a very good set of
|
||||
<quote>info</quote> pages. If you have installed any of these
|
||||
ports, <application>GNU make</application> will automatically
|
||||
have been installed as <command>gmake</command>. It's also
|
||||
have been installed as <command>gmake</command>. It is also
|
||||
available as a port and package in its own right.</para>
|
||||
|
||||
<para>To view the info pages for <application>GNU
|
||||
|
@ -1367,17 +1367,17 @@ DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz
|
|||
program a line at a time, inspect the value of variables,
|
||||
change them, tell the debugger to run up to a certain point
|
||||
and then stop, and so on. You can even attach to a program
|
||||
that's already running, or load a core file to investigate why
|
||||
the program crashed. It's even possible to debug the kernel,
|
||||
though that's a little trickier than the user applications
|
||||
we'll be discussing in this section.</para>
|
||||
that is already running, or load a core file to investigate why
|
||||
the program crashed. It is even possible to debug the kernel,
|
||||
though that is a little trickier than the user applications
|
||||
we will be discussing in this section.</para>
|
||||
|
||||
<para><command>gdb</command> has quite good on-line help, as
|
||||
well as a set of info pages, so this section will concentrate
|
||||
on a few of the basic commands.</para>
|
||||
|
||||
<para>Finally, if you find its text-based command-prompt style
|
||||
off-putting, there's a graphical front-end for it <ulink
|
||||
off-putting, there is a graphical front-end for it <ulink
|
||||
URL="../../../../ports/devel.html">xxgdb</ulink> in the ports
|
||||
collection.</para>
|
||||
|
||||
|
@ -1389,16 +1389,16 @@ DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz
|
|||
<sect2>
|
||||
<title>Running a program in the debugger</title>
|
||||
|
||||
<para>You'll need to have compiled the program with the
|
||||
<para>You will need to have compiled the program with the
|
||||
<option>-g</option> option to get the most out of using
|
||||
<command>gdb</command>. It will work without, but you'll only
|
||||
see the name of the function you're in, instead of the source
|
||||
<command>gdb</command>. It will work without, but you will only
|
||||
see the name of the function you are in, instead of the source
|
||||
code. If you see a line like:</para>
|
||||
|
||||
<screen>… (no debugging symbols found) …</screen>
|
||||
|
||||
<para>when <command>gdb</command> starts up, you'll know that
|
||||
the program wasn't compiled with the <option>-g</option>
|
||||
<para>when <command>gdb</command> starts up, you will know that
|
||||
the program was not compiled with the <option>-g</option>
|
||||
option.</para>
|
||||
|
||||
<para>At the <command>gdb</command> prompt, type
|
||||
|
@ -1408,18 +1408,18 @@ DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz
|
|||
<userinput>run</userinput> to start the program—it will
|
||||
start at the beginning of the set-up code and then get stopped
|
||||
by the debugger when it calls <function>main()</function>.
|
||||
(If you've ever wondered where <function>main()</function>
|
||||
(If you have ever wondered where <function>main()</function>
|
||||
gets called from, now you know!).</para>
|
||||
|
||||
<para>You can now step through the program, a line at a time, by
|
||||
pressing <command>n</command>. If you get to a function call,
|
||||
you can step into it by pressing <command>s</command>. Once
|
||||
you're in a function call, you can return from stepping into a
|
||||
you are in a function call, you can return from stepping into a
|
||||
function call by pressing <command>f</command>. You can also
|
||||
use <command>up</command> and <command>down</command> to take
|
||||
a quick look at the caller.</para>
|
||||
|
||||
<para>Here's a simple example of how to spot a mistake in a
|
||||
<para>Here is a simple example of how to spot a mistake in a
|
||||
program with <command>gdb</command>. This is our program
|
||||
(with a deliberate mistake):</para>
|
||||
|
||||
|
@ -1452,7 +1452,7 @@ int bazz(int anint) {
|
|||
This is my program
|
||||
anint = 4231</screen>
|
||||
|
||||
<para>That wasn't what we expected! Time to see what's going
|
||||
<para>That was not what we expected! Time to see what is going
|
||||
on!</para>
|
||||
|
||||
<screen>&prompt.user; <userinput>gdb temp</userinput>
|
||||
|
@ -1473,7 +1473,7 @@ bazz (anint=4231) at temp.c:17 <lineannotation><command>gdb</command> displays
|
|||
(gdb)</screen>
|
||||
|
||||
<para>Hang on a minute! How did <symbol>anint</symbol> get to be
|
||||
<literal>4231</literal>? Didn't we set it to be
|
||||
<literal>4231</literal>? Did we not we set it to be
|
||||
<literal>5</literal> in <function>main()</function>? Let's
|
||||
move up to <function>main()</function> and have a look.</para>
|
||||
|
||||
|
@ -1494,18 +1494,18 @@ main() {
|
|||
<lineannotation>&hellip</></programlisting>
|
||||
|
||||
<para>but we left the <literal>i=5;</literal> line out. As we
|
||||
didn't initialise <symbol>i</symbol>, it had whatever number
|
||||
did not initialise <symbol>i</symbol>, it had whatever number
|
||||
happened to be in that area of memory when the program ran,
|
||||
which in this case happened to be
|
||||
<literal>4231</literal>.</para>
|
||||
|
||||
<note>
|
||||
<para><command>gdb</command> displays the stack frame every
|
||||
time we go into or out of a function, even if we're using
|
||||
time we go into or out of a function, even if we are using
|
||||
<command>up</command> and <command>down</command> to move
|
||||
around the call stack. This shows the name of the function
|
||||
and the values of its arguments, which helps us keep track
|
||||
of where we are and what's going on. (The stack is a
|
||||
of where we are and what is going on. (The stack is a
|
||||
storage area where the program stores information about the
|
||||
arguments passed to functions and where to go when it
|
||||
returns from a function call).</para>
|
||||
|
@ -1531,8 +1531,8 @@ main() {
|
|||
|
||||
<screen>(gdb) <userinput>core <replaceable>progname</replaceable>.core</userinput></screen>
|
||||
|
||||
<para>If you're not in the same directory as the core file,
|
||||
you'll have to do <userinput>dir
|
||||
<para>If you are not in the same directory as the core file,
|
||||
you will have to do <userinput>dir
|
||||
/path/to/core/file</userinput> first.</para>
|
||||
|
||||
<para>You should see something like this:</para>
|
||||
|
@ -1556,7 +1556,7 @@ Cannot access memory at address 0x7020796d.
|
|||
available to it in a function called
|
||||
<function>bazz</function>.</para>
|
||||
|
||||
<para>Sometimes it's useful to be able to see how a function was
|
||||
<para>Sometimes it is useful to be able to see how a function was
|
||||
called, as the problem could have occurred a long way up the
|
||||
call stack in a complex program. The <command>bt</command>
|
||||
command causes <command>gdb</command> to print out a
|
||||
|
@ -1577,7 +1577,7 @@ Cannot access memory at address 0x7020796d.
|
|||
<title>Attaching to a running program</title>
|
||||
|
||||
<para>One of the neatest features about <command>gdb</command>
|
||||
is that it can attach to a program that's already running. Of
|
||||
is that it can attach to a program that is already running. Of
|
||||
course, that assumes you have sufficient permissions to do so.
|
||||
A common problem is when you are stepping through a program
|
||||
that forks, and you want to trace the child, but the debugger
|
||||
|
@ -1591,10 +1591,10 @@ Cannot access memory at address 0x7020796d.
|
|||
|
||||
<para>in <command>gdb</command>, and then debug as usual.</para>
|
||||
|
||||
<para><quote>That's all very well,</quote> you're probably
|
||||
thinking, <quote>but by the time I've done that, the child
|
||||
<para><quote>That is all very well,</quote> you are probably
|
||||
thinking, <quote>but by the time I have done that, the child
|
||||
process will be over the hill and far away</quote>. Fear
|
||||
not, gentle reader, here's how to do it (courtesy of the
|
||||
not, gentle reader, here is how to do it (courtesy of the
|
||||
<command>gdb</command> info pages):</para>
|
||||
|
||||
<screen><lineannotation>&hellip</lineannotation>
|
||||
|
@ -1621,8 +1621,8 @@ else if (pid == 0) { /* child */
|
|||
<sect2>
|
||||
<title>Emacs</title>
|
||||
|
||||
<para>Unfortunately, Unix systems don't come with the kind of
|
||||
everything-you-ever-wanted-and-lots-more-you-didn't-in-one-gigantic-package
|
||||
<para>Unfortunately, Unix systems do nnot come with the kind of
|
||||
everything-you-ever-wanted-and-lots-more-you-did-not-in-one-gigantic-package
|
||||
integrated development environments that other systems
|
||||
have.
|
||||
|
||||
|
@ -1633,24 +1633,24 @@ else if (pid == 0) { /* child */
|
|||
|
||||
However, it is possible to set up your own environment. It
|
||||
may not be as pretty, and it may not be quite as integrated,
|
||||
but you can set it up the way you want it. And it's free.
|
||||
but you can set it up the way you want it. And it is free.
|
||||
And you have the source to it.</para>
|
||||
|
||||
<para>The key to it all is Emacs. Now there are some people who
|
||||
loathe it, but many who love it. If you're one of the former,
|
||||
I'm afraid this section will hold little of interest to you.
|
||||
Also, you'll need a fair amount of memory to run it—I'd
|
||||
loathe it, but many who love it. If you are one of the former,
|
||||
I am afraid this section will hold little of interest to you.
|
||||
Also, you will need a fair amount of memory to run it—I would
|
||||
recommend 8MB in text mode and 16MB in X as the bare minimum
|
||||
to get reasonable performance.</para>
|
||||
|
||||
<para>Emacs is basically a highly customisable
|
||||
editor—indeed, it has been customised to the point where
|
||||
it's more like an operating system than an editor! Many
|
||||
it is more like an operating system than an editor! Many
|
||||
developers and sysadmins do in fact spend practically all
|
||||
their time working inside Emacs, leaving it only to log
|
||||
out.</para>
|
||||
|
||||
<para>It's impossible even to summarise everything Emacs can do
|
||||
<para>It is impossible even to summarise everything Emacs can do
|
||||
here, but here are some of the features of interest to
|
||||
developers:</para>
|
||||
|
||||
|
@ -1702,13 +1702,13 @@ else if (pid == 0) { /* child */
|
|||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>And doubtless many more that I've overlooked.</para>
|
||||
<para>And doubtless many more that I have overlooked.</para>
|
||||
|
||||
<para>Emacs can be installed on FreeBSD using <ulink
|
||||
URL="../../../../ports/editors.html">the Emacs
|
||||
port</ulink>.</para>
|
||||
|
||||
<para>Once it's installed, start it up and do <userinput>C-h
|
||||
<para>Once it is installed, start it up and do <userinput>C-h
|
||||
t</userinput> to read an Emacs tutorial—that means
|
||||
hold down the <keycap>control</keycap> key, press
|
||||
<keycap>h</keycap>, let go of the <keycap>control</keycap>
|
||||
|
@ -1717,25 +1717,25 @@ else if (pid == 0) { /* child */
|
|||
Tutorial</guimenuitem> from the <guimenu>Help</guimenu>
|
||||
menu).</para>
|
||||
|
||||
<para>Although Emacs does have menus, it's well worth learning
|
||||
the key bindings, as it's much quicker when you're editing
|
||||
<para>Although Emacs does have menus, it is well worth learning
|
||||
the key bindings, as it is much quicker when you are editing
|
||||
something to press a couple of keys than to try and find the
|
||||
mouse and then click on the right place. And, when you're
|
||||
talking to seasoned Emacs users, you'll find they often
|
||||
mouse and then click on the right place. And, when you are
|
||||
talking to seasoned Emacs users, you will find they often
|
||||
casually throw around expressions like <quote><literal>M-x
|
||||
replace-s RET foo RET bar RET</literal></quote> so it's
|
||||
replace-s RET foo RET bar RET</literal></quote> so it is
|
||||
useful to know what they mean. And in any case, Emacs has far
|
||||
too many useful functions for them to all fit on the menu
|
||||
bars.</para>
|
||||
|
||||
<para>Fortunately, it's quite easy to pick up the key-bindings,
|
||||
as they're displayed next to the menu item. My advice is to
|
||||
<para>Fortunately, it is quite easy to pick up the key-bindings,
|
||||
as they are displayed next to the menu item. My advice is to
|
||||
use the menu item for, say, opening a file until you
|
||||
understand how it works and feel confident with it, then try
|
||||
doing C-x C-f. When you're happy with that, move on to
|
||||
doing C-x C-f. When you are happy with that, move on to
|
||||
another menu command.</para>
|
||||
|
||||
<para>If you can't remember what a particular combination of
|
||||
<para>If you can not remember what a particular combination of
|
||||
keys does, select <guimenuitem>Describe Key</guimenuitem> from
|
||||
the <guimenu>Help</guimenu> menu and type it in—Emacs
|
||||
will tell you what it does. You can also use the
|
||||
|
@ -1754,12 +1754,12 @@ else if (pid == 0) { /* child */
|
|||
<keysym>return</keysym> key, type bar (the string you want to
|
||||
replace <literal>foo</literal> with) and press
|
||||
<keysym>return</keysym> again. Emacs will then do the
|
||||
search-and-replace operation you've just requested.</para>
|
||||
search-and-replace operation you have just requested.</para>
|
||||
|
||||
<para>If you're wondering what on earth the
|
||||
<keysym>Meta</keysym> key is, it's a special key that many
|
||||
Unix workstations have. Unfortunately, PC's don't have one,
|
||||
so it's usually the <keycap>alt</keycap> key (or if you're
|
||||
<para>If you are wondering what on earth the
|
||||
<keysym>Meta</keysym> key is, it is a special key that many
|
||||
Unix workstations have. Unfortunately, PC's do not have one,
|
||||
so it is usually the <keycap>alt</keycap> key (or if you are
|
||||
unlucky, the <keysym>escape</keysym> key).</para>
|
||||
|
||||
<para>Oh, and to get out of Emacs, do <command>C-x C-c</command>
|
||||
|
@ -1770,8 +1770,8 @@ else if (pid == 0) { /* child */
|
|||
the bit in the documentation where it says
|
||||
<command>C-z</command> is the usual way to leave
|
||||
Emacs—that leaves Emacs hanging around in the
|
||||
background, and is only really useful if you're on a system
|
||||
which doesn't have virtual terminals).</para>
|
||||
background, and is only really useful if you are on a system
|
||||
which does not have virtual terminals).</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
|
@ -1784,18 +1784,18 @@ else if (pid == 0) { /* child */
|
|||
configuration, Emacs uses a version of Lisp specially adapted
|
||||
for editors, known as Emacs Lisp. This can be quite useful if
|
||||
you want to go on and learn something like Common Lisp, as
|
||||
it's considerably smaller than Common Lisp (although still
|
||||
it is considerably smaller than Common Lisp (although still
|
||||
quite big!).</para>
|
||||
|
||||
<para>The best way to learn Emacs Lisp is to download the <ulink
|
||||
URL="ftp://prep.ai.mit.edu/pub/gnu/elisp-manual-19-2.4.tar.gz">Emacs
|
||||
Tutorial</ulink></para>
|
||||
|
||||
<para>However, there's no need to actually know any Lisp to get
|
||||
started with configuring Emacs, as I've included a sample
|
||||
<para>However, there is no need to actually know any Lisp to get
|
||||
started with configuring Emacs, as I have included a sample
|
||||
<filename>.emacs</filename> file, which should be enough to
|
||||
get you started. Just copy it into your home directory and
|
||||
restart Emacs if it's already running; it will read the
|
||||
restart Emacs if it is already running; it will read the
|
||||
commands from the file and (hopefully) give you a useful basic
|
||||
setup.</para>
|
||||
</sect2>
|
||||
|
@ -1803,7 +1803,7 @@ else if (pid == 0) { /* child */
|
|||
<sect2>
|
||||
<title>A sample <filename>.emacs</filename> file</title>
|
||||
|
||||
<para>Unfortunately, there's far too much here to explain it in
|
||||
<para>Unfortunately, there is far too much here to explain it in
|
||||
detail; however there are one or two points worth
|
||||
mentioning.</para>
|
||||
|
||||
|
@ -1828,8 +1828,8 @@ else if (pid == 0) { /* child */
|
|||
indentation function in some modes, so when you press the
|
||||
tab key, it will indent the current line of code. If you
|
||||
want to put a <token>tab</token> character in whatever
|
||||
you're writing, hold the <keysym>control</keysym> key down
|
||||
while you're pressing the <keysym>tab</keysym> key.</para>
|
||||
you are writing, hold the <keysym>control</keysym> key down
|
||||
while you are pressing the <keysym>tab</keysym> key.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
@ -1853,7 +1853,7 @@ else if (pid == 0) { /* child */
|
|||
|
||||
<listitem>
|
||||
<para>We enable Emacs's ability to act as a server, so that
|
||||
if you're doing something outside Emacs and you want to
|
||||
if you are doing something outside Emacs and you want to
|
||||
edit a file, you can just type in</para>
|
||||
|
||||
<screen>&prompt.user; <userinput>emacsclient <replaceable>filename</replaceable></userinput>
|
||||
|
@ -2212,7 +2212,7 @@ in font-lock-auto-mode-list"
|
|||
<function>whizbang-mode</function> when you edit a file ending
|
||||
in <filename>.wiz</filename>.</para>
|
||||
|
||||
<para>Just below this, you'll find the
|
||||
<para>Just below this, you will find the
|
||||
<symbol>font-lock-auto-mode-list</symbol> entry. Add
|
||||
<function>whizbang-mode</function> to it like so:</para>
|
||||
|
||||
|
@ -2225,7 +2225,7 @@ in font-lock-auto-mode-list"
|
|||
<function>font-lock-mode</function> (ie syntax highlighting)
|
||||
when editing a <filename>.wiz</filename> file.</para>
|
||||
|
||||
<para>And that's all that's needed. If there's anything else
|
||||
<para>And that is all that is needed. If there is anything else
|
||||
you want done automatically when you open up a
|
||||
<filename>.wiz</filename> file, you can add a
|
||||
<function>whizbang-mode hook</function> (see
|
||||
|
|
|
@ -1,7 +1,7 @@
|
|||
<!--
|
||||
The FreeBSD Documentation Project
|
||||
|
||||
$FreeBSD: doc/en_US.ISO_8859-1/books/developers-handbook/usb/chapter.sgml,v 1.1 2001/04/13 09:05:13 murray Exp $
|
||||
$FreeBSD$
|
||||
-->
|
||||
|
||||
<chapter id="vm">
|
||||
|
@ -149,7 +149,7 @@
|
|||
<literal>vm_map_t</literal>/<literal>vm_entry_t</literal>/
|
||||
<literal>vm_object_t</literal> hierarchy. Remember when I mentioned
|
||||
that physical pages are only directly associated with a
|
||||
<literal>vm_object</literal>. Well, that isn't quite true.
|
||||
<literal>vm_object</literal>. Well, that is not quite true.
|
||||
<literal>vm_page_t</literal>'s are also linked into page tables that
|
||||
they are actively associated with. One <literal>vm_page_t</literal>
|
||||
can be linked into several <emphasis>pmaps</emphasis>, as page tables
|
||||
|
|
|
@ -4268,7 +4268,7 @@ how do we treat two numbers separated by something else?
|
|||
<para>
|
||||
Personally, I like to keep it simple. Something either
|
||||
is a number, so I process it. Or it is not a number,
|
||||
so I discard it. I don't like the computer complaining
|
||||
so I discard it. I do not like the computer complaining
|
||||
about me typing in an extra character when it is
|
||||
<emphasis>obvious</emphasis> that it is an extra character. Duh!
|
||||
</para>
|
||||
|
|
Loading…
Reference in a new issue