diff --git a/share/man/man4/apic.4 b/share/man/man4/apic.4 index 224e4f6cdf4a..0856232f2afe 100644 --- a/share/man/man4/apic.4 +++ b/share/man/man4/apic.4 @@ -1,77 +1,77 @@ .\" Copyright (c) 2011 Alexander Motin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd December 20, 2011 .Dt APIC 4 .Os .Sh NAME .Nm apic .Nd Advanced Programmable Interrupt Controller (APIC) driver .Sh SYNOPSIS This driver is a mandatory part of amd64 kernel. To compile this driver into i386 or pc98 kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device apic" .Ed .Pp The following tunable is settable from the .Xr loader 8 : .Bl -ohang .It Va hint.apic. Ns Ar X Ns Va .clock controls event timers functionality support. Setting to 0, disables it. Default value is 1. .It Va hint.apic. Ns Ar X Ns Va .disabled Set this to 1 to disable APIC support, falling back to the legacy PIC. .El .Sh DESCRIPTION There are two components in the Intel APIC system, the local APIC (LAPIC) and the I/O APIC. There is one local APIC in each CPU in the system. There is typically one I/O APIC for each peripheral bus in the system. .Pp Local APICs manage all external interrupts for a specific processor. In addition, they are able to accept and generate inter-processor interrupts (IPIs). .Pp I/O APICs contain a redirection table, which is used to route the interrupts they receive from peripheral buses to one or more local APICs. .Pp -Each local APIC includes one 32-bit programable timer. +Each local APIC includes one 32-bit programmable timer. This driver uses them to supply kernel with one event timer named "LAPIC". Event timer provided by the driver supports both one-shot an periodic modes. Because of local APIC nature it is per-CPU. The timer frequency is not reported by the platform and so automatically measured by the driver on the first use. Depending on CPU model this timer may stop in C3 and deeper CPU sleep states. Driver automatically adjusts event timer priority and reports it to prevent entering dangerous sleep states when it is used. .Sh SEE ALSO .Xr atrtc 4 , .Xr attimer 4 , .Xr eventtimers 4 , .Xr hpet 4 diff --git a/share/man/man4/carp.4 b/share/man/man4/carp.4 index 1b59e72f8ad3..5a761ecf864d 100644 --- a/share/man/man4/carp.4 +++ b/share/man/man4/carp.4 @@ -1,312 +1,312 @@ .\" $OpenBSD: carp.4,v 1.16 2004/12/07 23:41:35 jmc Exp $ .\" .\" Copyright (c) 2003, Ryan McBride. All rights reserved. .\" Copyright (c) 2011, Gleb Smirnoff .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd December 20, 2011 .Dt CARP 4 .Os .Sh NAME .Nm carp .Nd Common Address Redundancy Protocol .Sh SYNOPSIS .Cd "device carp" .Sh DESCRIPTION The CARP allows multiple hosts on the same local network to share a set of IPv4 and/or IPv6 addresses. Its primary purpose is to ensure that these addresses are always available. .Pp To use .Nm , the administrator needs to configure at minimum a common virtual host ID (vhid) and attach at least one IP address to this vhid on each machine which is to take part in the virtual group. Additional parameters can also be set on a per-vhid basis: .Cm advbase and .Cm advskew , which are used to control how frequently the host sends advertisements when it is the master for a virtual host, and .Cm pass which is used to authenticate .Nm advertisements. The .Cm advbase parameter stands for .Dq "advertisement base" . It is measured in seconds and specifies the base of the advertisement interval. The .Cm advskew parameter stands for .Dq "advertisement skew" . It is measured in 1/256 of seconds. It is added to the base advertisement interval to make one host advertise a bit slower that the other does. Both .Cm advbase and .Cm advskew are put inside CARP advertisements. These configurations can be done using .Xr ifconfig 8 , or through the .Dv SIOCSVH .Xr ioctl 2 . .Pp CARP virtual hosts can be configured on multicast capable interfaces: Ethernet, layer 2 VLAN, FDDI and Token Ring. An arbitrary number of virtual host IDs can be configured on an interface. An arbitrary number of IPv4 or IPv6 addresses can be attached to a particular vhid. It is important that all hosts participating in a vhid have the same list of prefixes configured on the vhid, since all prefixes are included in the cryptographic checksum supplied in each advertisement. Multiple vhids running on one interface participate in master/backup elections independently. .Pp Additionally, there are a number of global parameters which can be set using .Xr sysctl 8 : .Bl -tag -width ".Va net.inet.carp.preempt" .It Va net.inet.carp.allow Accept incoming .Nm packets. Enabled by default. .It Va net.inet.carp.preempt Allow virtual hosts to preempt each other. It is also used to failover .Nm interfaces as a group. When the option is enabled and one of the .Nm enabled physical interfaces goes down, .Cm advskew is changed to 240 on all .Nm interfaces. See also the first example. Disabled by default. .It Va net.inet.carp.log Value of 0 disables any logging. Value of 1 enables logging state changes of .Nm interfaces. Values above 1 enable logging of bad .Nm packets. Default value is 1. .It Va net.inet.carp.demotion This value shows current level of CARP demotion. The value is added to the actual advskew sent in announcements for all vhids. At normal system operation the demotion factor is zero. However, problematic conditions raise its level: when .Nm experiences problem with sending announcements, when an interface running a vhid goes down, or while the .Xr pfsync 4 interface is not synchronized. The demotion value is writable, so that user may alter it depending on some external conditions, for example on status of some daemon utility. However, altering the value should be performed with care, do not conflict with subsystems that adjust demotion factor automatically: .Nm and .Xr pfsync 4 . .It Va net.inet.carp.ifdown_demotion_factor Value added to .Va net.inet.carp.demotion when interface running a vhid goes down. Default value is 240 (maximum advskew value). .It Va net.inet.carp.senderr_demotion_factor Value added to .Va net.inet.carp.demotion when .Nm experiences errors sending its announcements. Default value is 240 (maximum advskew value). .El .\".Sh ARP level load balancing .\"The .\".Nm .\"has limited abilities for load balancing the incoming connections .\"between hosts in Ethernet network. .\"For load balancing operation, one needs several CARP interfaces that .\"are configured to the same IP address, but to a different vhids. .\"Once an ARP request is received, the CARP protocol will use a hashing .\"function against the source IP address in the ARP request to determine .\"which vhid should this request belong to. .\"If the corresponding CARP interface is in master state, the ARP request .\"will be replied, otherwise it will be ignored. .\"See the .\".Sx EXAMPLES .\"section for a practical example of load balancing. .\".Pp .\"The ARP load balancing has some limitations. .\"First, ARP balancing only works on the local network segment. .\"It cannot balance traffic that crosses a router, because the .\"router itself will always be balanced to the same virtual host. .\"Second, ARP load balancing can lead to asymmetric routing .\"of incoming and outgoing traffic, and thus combining it with .\".Xr pfsync 4 .\"is dangerous, because this creates a race condition between .\"balanced routers and a host they are serving. .\"Imagine an incoming packet creating state on the first router, being .\"forwarded to its destination, and destination replying faster .\"than the state information is packed and synced with the second router. .\"If the reply would be load balanced to second router, it will be .\"dropped due to no state. .Sh STATE CHANGE NOTIFICATIONS Sometimes it is useful to get notified about .Nm status change events. This can be accomplished by using .Xr devd 8 hooks. Master/slave events are signalled under system .Dv CARP . -Subsystem specifies vhid and name of interface, where event occured. +Subsystem specifies vhid and name of interface, where event occurred. Type of the message displays new state of vhid. Please see .Xr devd.conf 5 and .Sx EXAMPLES section for more information. .Sh EXAMPLES For firewalls and routers with multiple interfaces, it is desirable to failover all of the .Nm interfaces together, when one of the physical interfaces goes down. This is achieved by the preempt option. Enable it on both host A and B: .Pp .Dl sysctl net.inet.carp.preempt=1 .Pp Assume that host A is the preferred master and we are running the 192.168.1.0/24 prefix on em0 and 192.168.2.0/24 on em1. This is the setup for host A: .Bd -literal -offset indent ifconfig em0 vhid 1 pass mekmitasdigoat 192.168.1.1/24 ifconfig em1 vhid 2 pass mekmitasdigoat 192.168.2.1/24 .Ed .Pp The setup for host B is identical, but it has a higher .Cm advskew : .Bd -literal -offset indent ifconfig em0 vhid 1 advskew 100 pass mekmitasdigoat 192.168.1.1/24 ifconfig em1 vhid 2 advskew 100 pass mekmitasdigoat 192.168.2.1/24 .Ed .Pp Because of the preempt option, when one of the physical interfaces of host A fails, .Cm advskew is adjusted to 240 on all its .Nm interfaces. This will cause host B to preempt on both interfaces instead of just the failed one. .\".Pp .\"In order to set up an ARP balanced virtual host, it is necessary to configure .\"one virtual host for each physical host which would respond to ARP requests .\"and thus handle the traffic. .\"In the following example, two virtual hosts are configured on two hosts to .\"provide balancing and failover for the IP address 192.168.1.10. .\".Pp .\"First the .\".Nm .\"interfaces on host A are configured. .\"The .\".Cm advskew .\"of 100 on the second virtual host means that its advertisements will be sent .\"out slightly less frequently. .\".Bd -literal -offset indent .\"ifconfig carp0 create .\"ifconfig carp0 vhid 1 pass mekmitasdigoat 192.168.1.10/24 .\"ifconfig carp1 create .\"ifconfig carp1 vhid 2 advskew 100 pass mekmitasdigoat 192.168.1.10/24 .\".Ed .\".Pp .\"The configuration for host B is identical, except the .\".Cm advskew .\"is on virtual host 1 rather than virtual host 2. .\".Bd -literal -offset indent .\"ifconfig carp0 create .\"ifconfig carp0 vhid 1 advskew 100 pass mekmitasdigoat 192.168.1.10/24 .\"ifconfig carp1 create .\"ifconfig carp1 vhid 2 pass mekmitasdigoat 192.168.1.10/24 .\".Ed .\".Pp .\"Finally, the ARP balancing feature must be enabled on both hosts: .\".Pp .\".Dl sysctl net.inet.carp.arpbalance=1 .\".Pp .\"When the hosts receive an ARP request for 192.168.1.10, the source IP address .\"of the request is used to compute which virtual host should answer the request. .\"The host which is master of the selected virtual host will reply to the .\"request, the other(s) will ignore it. .\".Pp .\"This way, locally connected systems will receive different ARP replies and .\"subsequent IP traffic will be balanced among the hosts. .\"If one of the hosts fails, the other will take over the virtual MAC address, .\"and begin answering ARP requests on its behalf. .Pp Processing of .Nm status change events can be set up by using the following devd.conf rule: .Bd -literal -offset indent notify 0 { match "system" "CARP"; match "subsystem" "[0-9]+@"; match "type" "(MASTER|BACKUP)"; action "/root/carpcontrol.sh $subsystem $type"; }; .Ed .Sh SEE ALSO .Xr inet 4 , .Xr pfsync 4 , .Xr rc.conf 5 , .Xr devd.conf 5 , .Xr ifconfig 8 , .Xr sysctl 8 .Sh HISTORY The .Nm device first appeared in .Ox 3.5 . The .Nm device was imported into .Fx 5.4 . In .Fx 10 the .Nm was significantly rewritten, and is no longer a pseudo-interface. diff --git a/share/man/man5/ar.5 b/share/man/man5/ar.5 index 81bc7e60dfa3..2acbde46393e 100644 --- a/share/man/man5/ar.5 +++ b/share/man/man5/ar.5 @@ -1,327 +1,327 @@ .\" Copyright (c) 2010 Joseph Koshy. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd November 28, 2010 .Os .Dt AR 5 .Sh NAME .Nm ar .Nd archive file format for .Xr ar 1 and .Xr ranlib 1 .Sh SYNOPSIS .In ar.h .Sh DESCRIPTION .Xr ar 1 archives are created and managed by the .Xr ar 1 and .Xr ranlib 1 utilities. These archives are typically used during program development to hold libraries of program objects. An .Xr ar 1 archive is contained in a single operating system file. .Pp This manual page documents two variants of the .Xr ar 1 archive format: the BSD archive format, and the SVR4/GNU archive format. .Pp In both variants the archive file starts with an identifying byte sequence of the seven ASCII characters .Sq Li "!" followed by a ASCII linefeed character .Po see the constant .Dq ARMAG in the header file .In ar.h .Pc . .Pp Archive members follow the initial identifying byte sequence. Each archive member is prefixed by a fixed size header describing the file attributes associated with the member. .Ss "Archive Headers" An archive header describes the file attributes for the archive member that follows it. The .Xr ar 5 format only supports a limited number of attributes: the file name, the file creation time stamp, the uid and gid of the creator, the file mode and the file size. .Pp Archive headers are placed at an even byte offset in the archive file. If the data for an archive member ends at an odd byte offset, then a padding byte with value 0x0A is used to position the next archive header on an even byte offset. .Pp An archive header comprises the following fixed sized fields: .Bl -tag -width "Li ar_name" .It Ar ar_name (16 bytes) The file name of the archive member. The format of this field varies between the BSD and SVR4/GNU formats and is described in more detail in the section .Sx "Representing File Names" below. .It Ar ar_date (12 bytes) The file modification time for the member in seconds since the epoch, encoded as a decimal number. .It Ar ar_uid (6 bytes) The uid associated with the archive member, encoded as a decimal number. .It Ar ar_gid (6 bytes) The gid associated with the archive member, encoded as a decimal number. .It Ar ar_mode (8 bytes) The file mode for the archive member, encoded as an octal number. .It Ar ar_size (10 bytes) In the SVR4/GNU archive format this field holds the size in bytes of the archive member, encoded as a decimal number. In the BSD archive format, for short file names, this field holds the size in bytes of the archive member, encoded as a decimal number. For long file names .Po see .Sx "Representing File Names" below .Pc , the field contains the combined size of the archive member and its file name, encoded as a decimal number. .It Ar ar_fmag (2 bytes) This field holds 2 bytes with values 0x96 and 0x0A respectively, marking the end of the header. .El .Pp Unused bytes in the fields of an archive header are set to the value 0x20. .Ss "Representing File Names" The BSD and SVR4/GNU variants use different schemes for encoding file names for members. .Bl -tag -width "SVR4/GNU" .It "BSD" -File names that are upto 16 bytes long and which do not contain +File names that are up to 16 bytes long and which do not contain embedded spaces are stored directly in the .Ar ar_name field of the archive header. File names that are either longer than 16 bytes or which contain embedded spaces are stored immediately after the archive header and the .Ar ar_name field of the archive header is set to the string .Dq "#1/" followed by a decimal representation of the number of bytes needed for the file name. In addition, the .Ar ar_size field of the archive header is set to the decimal representation of the combined sizes of the archive member and the file name. The file contents of the member follows the file name without further padding. .Pp As an example, if the file name for a member was .Dq "A B" and its contents was the string .Dq "C D" , then the .Ar ar_name field of the header would contain .Dq Li "#1/3" , the .Ar ar_size field of the header would contain .Dq Li 6 , and the bytes immediately following the header would be 0x41, 0x20, 0x42, 0x43, 0x20 and 0x44 .Po ASCII .Dq "A BC D" .Pc . .It "SVR4/GNU" -File names that are upto 15 characters long are stored directly in the +File names that are up to 15 characters long are stored directly in the .Ar ar_name field of the header, terminated by a .Dq Li / character. .Pp If the file name is larger than would fit in space for the .Ar ar_name field, then the actual file name is kept in the archive string table .Po see .Sx "Archive String Tables" below .Pc , and the decimal offset of the file name in the string table is stored in the .Ar ar_name field, prefixed by a .Dq Li / character. .Pp As an example, if the real file name has been stored at offset 768 in the archive string table, the .Ar ar_name field of the header will contain the string .Dq /768 . .El .Ss "Special Archive Members" The following archive members are special. .Bl -tag -width indent .It Dq Li / In the SVR4/GNU variant of the archive format, the archive member with name .Dq Li / denotes an archive symbol table. If present, this member will be the very first member in the archive. .It Dq Li // In the SVR4/GNU variant of the archive format, the archive member with name .Dq Li // denotes the archive string table. This special member is used to hold filenames that do not fit in the file name field of the header .Po see .Sx "Representing File Names" above .Pc . If present, this member immediately follows the archive symbol table if an archive symbol table is present, or is the first member otherwise. .It Dq Li "__.SYMDEF" This special member contains the archive symbol table in the BSD variant of the archive format. If present, this member will be the very first member in the archive. .El .Ss "Archive String Tables" An archive string table is used in the SVR4/GNU archive format to hold file names that are too large to fit into the constraints of the .Ar ar_name field of the archive header. An archive string table contains a sequence of file names. Each file name in the archive string table is terminated by the byte sequence 0x2F, 0x0A .Po the ASCII string .Dq "/\en" .Pc . No padding is used to separate adjacent file names. .Ss "Archive Symbol Tables" Archive symbol tables are used to speed up link editing by providing a mapping between the program symbols defined in the archive and the corresponding archive members. Archive symbol tables are managed by the .Xr ranlib 1 utility. .Pp The format of archive symbol tables is as follows: .Bl -tag -width "SVR4/GNU" .It BSD In the BSD archive format, the archive symbol table comprises of two parts: a part containing an array of .Vt "struct ranlib" descriptors, followed by a part containing a symbol string table. The sizes and layout of the structures that make up a BSD format archive symbol table are machine dependent. .Pp The part containing .Vt "struct ranlib" descriptors begins with a field containing the size in bytes of the array of .Vt "struct ranlib" descriptors encoded as a C .Vt long value. .Pp The array of .Vt "struct ranlib" descriptors follows the size field. Each .Vt "struct ranlib" descriptor describes one symbol. .Pp A .Vt "struct ranlib" descriptor comprises two fields: .Bl -tag -width "Ar ran_strx" -compact .It Ar ran_strx .Pq C Vt long This field contains the zero-based offset of the symbol name in the symbol string table. .It Ar ran_off .Pq C Vt long This field is the file offset to the archive header for the archive member defining the symbol. .El .Pp The part containing the symbol string table begins with a field containing the size in bytes of the string table, encoded as a C .Vt long value. This string table follows the size field, and contains NUL-terminated strings for the symbols in the symbol table. .It SVR4/GNU In the SVR4/GNU archive format, the archive symbol table starts with a 4-byte binary value containing the number of entries contained in the archive symbol table. This count of entries is stored most significant byte first. .Pp Next, there are .Ar count 4-byte numbers, each stored most significant byte first. Each number is a binary offset to the archive header for the member in the archive file for the corresponding symbol table entry. .Pp After the binary offset values, there are .Ar count NUL-terminated strings in sequence, holding the symbol names for the corresponding symbol table entries. .El .Sh STANDARDS COMPLIANCE The .Xr ar 1 archive format is not currently specified by a standard. .Pp This manual page documents the .Xr ar 1 archive formats used by the .Bx 4.4 and .Ux SVR4 operating system releases. .Sh SEE ALSO .Xr ar 1 , .Xr ld 1 , .Xr ranlib 1 , .Xr elf 3 , .Xr elf_getarsym 3 , .Xr elf_rand 3