os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Expand all contractions in the developer's handbook.

Browse source
This commit is contained in:
Giorgos Keramidas 2001-12-08 10:48:58 +00:00
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

64
en_US.ISO8859-1/books/arch-handbook/isa/chapter.sgml
View file

@ -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 *) &#38;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>

8
en_US.ISO8859-1/books/arch-handbook/kobj/chapter.sgml
View file

@ -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

2
en_US.ISO8859-1/books/arch-handbook/pci/chapter.sgml
View file

@ -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

48
en_US.ISO8859-1/books/arch-handbook/scsi/chapter.sgml
View file

@ -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 &amp; 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

4
en_US.ISO8859-1/books/arch-handbook/vm/chapter.sgml
View file

@ -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

2
en_US.ISO8859-1/books/developers-handbook/dma/chapter.sgml
View file

@ -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>

28
en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml
View file

@ -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>

64
en_US.ISO8859-1/books/developers-handbook/isa/chapter.sgml
View file

@ -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 *) &#38;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>

4
en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
View file

@ -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

8
en_US.ISO8859-1/books/developers-handbook/kobj/chapter.sgml
View file

@ -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

2
en_US.ISO8859-1/books/developers-handbook/pci/chapter.sgml
View file

@ -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

4
en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml
View file

@ -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>

48
en_US.ISO8859-1/books/developers-handbook/scsi/chapter.sgml
View file

@ -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 &amp; 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

198
en_US.ISO8859-1/books/developers-handbook/tools/chapter.sgml
View file

@ -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&mdash;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&hellip;). 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> &hellip; <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&mdash;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>&hellip; (no debugging symbols found) &hellip;</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&mdash;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&mdash;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&mdash;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&mdash;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&mdash;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&mdash;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&mdash;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

4
en_US.ISO8859-1/books/developers-handbook/vm/chapter.sgml
View file

@ -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

2
en_US.ISO8859-1/books/developers-handbook/x86/chapter.sgml
View file

@ -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>