Index: head/share/man/man4/acpi.4 =================================================================== --- head/share/man/man4/acpi.4 (revision 147397) +++ head/share/man/man4/acpi.4 (revision 147398) @@ -1,464 +1,468 @@ .\" .\" Copyright (c) 2001 Michael Smith .\" 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 February 13, 2005 .Dt ACPI 4 .Os .Sh NAME .Nm acpi .Nd Advanced Configuration and Power Management support .Sh SYNOPSIS .Cd "device acpi" .Pp .Cd "options ACPI_DEBUG" .Sh DESCRIPTION The .Nm driver provides support for the Intel/Microsoft/Compaq/Toshiba ACPI standard. This support includes platform hardware discovery (superseding the PnP and PCI BIOS), as well as power management (superseding APM) and other features. ACPI core support is provided by the ACPI CA reference implementation from Intel. .Pp Note that the .Nm driver is automatically loaded by the .Xr loader 8 , and should only be compiled into the kernel on platforms where ACPI is mandatory. .Sh SYSCTLS The .Nm driver is intended to provide power management without user intervention. Thus, some of these sysctls are controlled automatically by the .Pa power_profile .Xr rc 8 script, which can be configured via .Xr rc.conf 5 . If values are specified manually, they may be overridden. .Bl -tag -width indent .It Va hw.acpi.cpu.cx_usage Debugging information listing the percent of total usage for each sleep state. The values are reset when .Va hw.acpi.cpu.cx_lowest is modified. .It Va hw.acpi.cpu.cx_lowest Lowest Cx state to use for idling the CPU. A scheduling algorithm will select states between C1 and this setting as system load dictates. To enable ACPI CPU idling control, .Va machdep.cpu_idle_hlt must be set to 1. .It Va hw.acpi.cpu.cx_supported List of supported CPU idle states and their transition latency in microseconds. Each state has a type (e.g., C2). C1 is equivalent to the ia32 HLT instruction, C2 provides a deeper sleep with the same semantics, and C3 provides the deepest sleep but additionally requires bus mastering to be disabled. States greater than C3 provide even more power savings with the same semantics as the C3 state. Deeper sleeps provide more power savings but increased transition latency when an interrupt occurs. .El .Sh TUNABLES Tunables can be set at the .Xr loader 8 prompt before booting the kernel or stored in .Pa /boot/loader.conf . .Bl -tag -width indent .It Va acpi_dsdt_load Enables loading of a custom ACPI DSDT. .It Va acpi_dsdt_name Name of the DSDT table to load, if loading is enabled. .It Va debug.acpi.disabled Selectively disables portions of ACPI for debugging purposes. .It Va debug.acpi.max_threads Specify the number of task threads that are started on boot. Limiting this to 1 may help work around various BIOSes that cannot handle parallel requests. The default value is 3. .It Va debug.acpi.quirks Override any automatic quirks completely. .It Va hint.acpi.0.disabled Set this to 1 to disable all of ACPI. If ACPI has been disabled on your system due to a blacklist entry for your BIOS, you can set this to 0 to re-enable ACPI for testing. .It Va hw.acpi.ec.poll_timeout Delay in milliseconds to wait for the EC to respond. Try increasing this number if you get the error .Qq Li AE_NO_HARDWARE_RESPONSE . .It Va hw.acpi.host_mem_start Override the assumed memory starting address for PCI host bridges. .It Va hw.acpi.pci.link.%d.%d.%d.irq Override the interrupt to use. .It Va hw.acpi.reset_video Enables calling the VESA reset BIOS vector on the resume path. Some graphic chips have problems such as LCD white-out after resume. Try setting this to 0 if this causes problems for you. .It Va hw.acpi.serialize_methods Allow override of whether methods execute in parallel or not. Enable this for serial behavior, which fixes .Qq Li AE_ALREADY_EXISTS errors for AML that really cannot handle parallel method execution. It is off by default since this breaks recursive methods and some IBMs use such code. .It Va hw.acpi.verbose Turn on verbose debugging information about what ACPI is doing. .El .Sh DISABLING ACPI Since ACPI support on different platforms varies greatly, there are many debugging and tuning options available. .Pp For machines known not to work with .Nm enabled, there is a BIOS blacklist. Currently, the blacklist only controls whether .Nm should be disabled or not. In the future, it will have more granularity to control features (the infrastructure for that is already there). .Pp To enable .Nm (for debugging purposes, etc.) on machines that are on the blacklist, set the kernel environment variable .Va hint.acpi.0.disabled to 0. Before trying this, consider updating your BIOS to a more recent version that may be compatible with ACPI. .Pp To disable the .Nm driver completely, set the kernel environment variable .Va hint.acpi.0.disabled to 1. .Pp Some i386 machines totally fail to operate with some or all of ACPI disabled. Other i386 machines fail with ACPI enabled. Disabling all or part of ACPI on non-i386 platforms (i.e., platforms where ACPI support is mandatory) may result in a non-functional system. .Pp The .Nm driver comprises a set of drivers, which may be selectively disabled in case of problems. To disable a sub-driver, list it in the kernel environment variable .Va debug.acpi.disabled . Multiple entries can be listed, separated by a space. .Pp ACPI sub-devices and features that can be disabled: .Bl -tag -width ".Li sysresource" .It Li all Disable all ACPI features and devices. .It Li acad .Pq Vt device Supports AC adapter. .It Li bus .Pq Vt feature Probes and attaches subdevices. Disabling will avoid scanning the ACPI namespace entirely. .It Li children .Pq Vt feature Attaches standard ACPI sub-drivers and devices enumerated in the ACPI namespace. Disabling this has a similar effect to disabling .Dq Li bus , except that the ACPI namespace will still be scanned. .It Li button .Pq Vt device Supports ACPI button devices (typically power and sleep buttons). .It Li cmbat .Pq Vt device Control-method batteries device. .It Li cpu .Pq Vt device Supports CPU power-saving and speed-setting functions. .It Li ec .Pq Vt device Supports the ACPI Embedded Controller interface, used to communicate with embedded platform controllers. .It Li isa .Pq Vt device Supports an ISA bus bridge defined in the ACPI namespace, typically as a child of a PCI bus. .It Li lid .Pq Vt device Supports an ACPI laptop lid switch, which typically puts a system to sleep. .It Li quirks .Pq Vt feature Do not honor quirks. Quirks automatically disable ACPI functionality based on the XSDT table's OEM vendor name and revision date. .It Li pci .Pq Vt device Supports Host to PCI bridges. .It Li pci_link .Pq Vt feature Performs PCI interrupt routing. .It Li sysresource .Pq Vt device Pseudo-devices containing resources which ACPI claims. .It Li thermal .Pq Vt device Supports system cooling and heat management. .It Li timer .Pq Vt device Implements a timecounter using the ACPI fixed-frequency timer. .It Li video .Pq Vt device -Supports acpi_video which may conflict with agp device. +Supports +.Xr acpi_video 4 +which may conflict with +.Xr agp 4 +device. .El .Pp It is also possible to avoid portions of the ACPI namespace which may be causing problems, by listing the full path of the root of the region to be avoided in the kernel environment variable .Va debug.acpi.avoid . The object and all of its children will be ignored during the bus/children scan of the namespace. The ACPI CA code will still know about the avoided region. .Sh DEBUGGING OUTPUT To enable debugging output, .Nm must be compiled with .Cd "options ACPI_DEBUG" . Debugging output is separated between layers and levels, where a layer is a component of the ACPI subsystem, and a level is a particular kind of debugging output. .Pp Both layers and levels are specified as a whitespace-separated list of tokens, with layers listed in .Va debug.acpi.layer and levels in .Va debug.acpi.level . .Pp The first set of layers is for ACPI-CA components, and the second is for .Fx drivers. The ACPI-CA layer descriptions include the prefix for the files they refer to. The supported layers are: .Pp .Bl -tag -compact -width ".Li ACPI_CA_DISASSEMBLER" .It Li ACPI_UTILITIES Utility ("ut") functions .It Li ACPI_HARDWARE Hardware access ("hw") .It Li ACPI_EVENTS Event and GPE ("ev") .It Li ACPI_TABLES Table access ("tb") .It Li ACPI_NAMESPACE Namespace evaluation ("ns") .It Li ACPI_PARSER AML parser ("ps") .It Li ACPI_DISPATCHER Internal representation of interpreter state ("ds") .It Li ACPI_EXECUTER Execute AML methods ("ex") .It Li ACPI_RESOURCES Resource parsing ("rs") .It Li ACPI_CA_DEBUGGER Debugger implementation ("db", "dm") .It Li ACPI_OS_SERVICES Usermode support routines ("os") .It Li ACPI_CA_DISASSEMBLER Disassembler implementation (unused) .It Li ACPI_ALL_COMPONENTS All the above ACPI-CA components .It Li ACPI_AC_ADAPTER AC adapter driver .It Li ACPI_BATTERY Control-method battery driver .It Li ACPI_BUS ACPI, ISA, and PCI bus drivers .It Li ACPI_BUTTON Power and sleep button driver .It Li ACPI_EC Embedded controller driver .It Li ACPI_FAN Fan driver .It Li ACPI_OEM Platform-specific driver for hotkeys, LED, etc. .It Li ACPI_POWER Power resource driver .It Li ACPI_PROCESSOR CPU driver .It Li ACPI_THERMAL Thermal zone driver .It Li ACPI_TIMER Timer driver .It Li ACPI_ALL_DRIVERS All the above .Fx ACPI drivers .El .Pp The supported levels are: .Pp .Bl -tag -compact -width ".Li ACPI_LV_AML_DISASSEMBLE" .It Li ACPI_LV_ERROR Fatal error conditions .It Li ACPI_LV_WARN Warnings and potential problems .It Li ACPI_LV_INIT Initialization progress .It Li ACPI_LV_DEBUG_OBJECT Stores to objects .It Li ACPI_LV_INFO General information and progress .It Li ACPI_LV_ALL_EXCEPTIONS All the previous levels .It Li ACPI_LV_INIT_NAMES .It Li ACPI_LV_PARSE .It Li ACPI_LV_LOAD .It Li ACPI_LV_DISPATCH .It Li ACPI_LV_EXEC .It Li ACPI_LV_NAMES .It Li ACPI_LV_OPREGION .It Li ACPI_LV_BFIELD .It Li ACPI_LV_TABLES .It Li ACPI_LV_VALUES .It Li ACPI_LV_OBJECTS .It Li ACPI_LV_RESOURCES .It Li ACPI_LV_USER_REQUESTS .It Li ACPI_LV_PACKAGE .It Li ACPI_LV_VERBOSITY1 All the previous levels .It Li ACPI_LV_ALLOCATIONS .It Li ACPI_LV_FUNCTIONS .It Li ACPI_LV_OPTIMIZATIONS .It Li ACPI_LV_VERBOSITY2 .It Li ACPI_LV_ALL .It Li ACPI_LV_MUTEX .It Li ACPI_LV_THREADS .It Li ACPI_LV_IO .It Li ACPI_LV_INTERRUPTS .It Li ACPI_LV_VERBOSITY3 All the previous levels .It Li ACPI_LV_AML_DISASSEMBLE .It Li ACPI_LV_VERBOSE_INFO .It Li ACPI_LV_FULL_TABLES .It Li ACPI_LV_EVENTS .It Li ACPI_LV_VERBOSE All levels after .Qq Li ACPI_LV_VERBOSITY3 .El .Pp Selection of the appropriate layer and level values is important to avoid massive amounts of debugging output. For example, the following configuration is a good way to gather initial information. It enables debug output for both ACPI-CA and the .Nm driver, printing basic information about errors, warnings, and progress. .Bd -literal -offset indent debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS" debug.acpi.level="ACPI_LV_ALL_EXCEPTIONS" .Ed .Pp Debugging output by the ACPI CA subsystem is prefixed with the module name in lowercase, followed by a source line number. Output from the .Fx Ns -local code follows the same format, but the module name is uppercased. .Sh OVERRIDING YOUR BIOS BYTECODE ACPI interprets bytecode named AML (ACPI Machine Language) provided by the BIOS vendor as a memory image at boot time. Sometimes, the AML code contains a bug that does not appear when parsed by the Microsoft implementation. .Fx provides a way to override it with your own AML code to work around or debug such problems. Note that all AML in your DSDT and any SSDT tables is overridden. .Pp In order to load your AML code, you must edit .Pa /boot/loader.conf and include the following lines. .Bd -literal -offset indent acpi_dsdt_load="YES" acpi_dsdt_name="/boot/acpi_dsdt.aml" # You may change this name. .Ed .Pp In order to prepare your AML code, you will need the .Xr acpidump 8 and .Xr iasl 8 utilities and some ACPI knowledge. .Sh COMPATIBILITY ACPI is only found and supported on i386/ia32, ia64, and amd64. .Sh SEE ALSO .Xr kenv 1 , .Xr acpi_thermal 4 , .Xr device.hints 5 , .Xr loader.conf 5 , .Xr acpiconf 8 , .Xr acpidump 8 , .Xr config 8 , .Xr iasl 8 .Rs .%A "Compaq Computer Corporation" .%A "Intel Corporation" .%A "Microsoft Corporation" .%A "Phoenix Technologies Ltd." .%A "Toshiba Corporation" .%D August 25, 2003 .%T "Advanced Configuration and Power Interface Specification" .%O http://acpi.info/spec.htm .Re .Sh AUTHORS .An -nosplit The ACPI CA subsystem is developed and maintained by Intel Architecture Labs. .Pp The following people made notable contributions to the ACPI subsystem in .Fx : .An Michael Smith , .An Takanori Watanabe Aq takawata@jp.FreeBSD.org , .An Mitsuru IWASAKI Aq iwasaki@jp.FreeBSD.org , .An Munehiro Matsuda , .An Nate Lawson , the ACPI-jp mailing list at .Aq acpi-jp@jp.FreeBSD.org , and many other contributors. .Pp This manual page was written by .An Michael Smith Aq msmith@FreeBSD.org . .Sh BUGS If the .Nm driver is loaded as a module when it is already linked as part of the kernel, odd things may happen. Index: head/share/man/man4/cpufreq.4 =================================================================== --- head/share/man/man4/cpufreq.4 (revision 147397) +++ head/share/man/man4/cpufreq.4 (revision 147398) @@ -1,295 +1,295 @@ .\" Copyright (c) 2005 Nate Lawson .\" 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 April 10, 2005 .Dt CPUFREQ 4 .Os .Sh NAME .Nm cpufreq .Nd CPU frequency control framework .Sh SYNOPSIS .Cd "device cpufreq" .Pp .In sys/cpu.h .Ft int .Fn cpufreq_levels "device_t dev" "struct cf_level *levels" "int *count" .Ft int .Fn cpufreq_set "device_t dev" "const struct cf_level *level" "int priority" .Ft int .Fn cpufreq_get "device_t dev" "struct cf_level *level" .Ft int .Fo cpufreq_drv_settings .Fa "device_t dev" .Fa "struct cf_setting *sets" .Fa "int *count" .Fc .Ft int .Fn cpufreq_drv_type "device_t dev" "int *type" .Ft int .Fn cpufreq_drv_set "device_t dev" "const struct cf_setting *set" .Ft int .Fn cpufreq_drv_get "device_t dev" "struct cf_setting *set" .Sh DESCRIPTION The .Nm driver provides a unified kernel and user interface to CPU frequency control drivers. It combines multiple drivers offering different settings into a single interface of all possible levels. Users can access this interface directly via .Xr sysctl 8 or by indicating to -.Pa power_profile +.Pa /etc/rc.d/power_profile that it should switch settings when the AC line state changes via .Xr rc.conf 5 . .Sh SYSCTLS These settings may be overridden by kernel drivers requesting alternate settings. If this occurs, the original values will be restored once the condition has passed (e.g., the system has cooled sufficiently). If a sysctl cannot be set due to an override condition, it will return .Er EPERM . .Bl -tag -width indent .It Va dev.cpu.%d.freq Current active CPU frequency in MHz. .It Va dev.cpu.%d.freq_levels Currently available levels for the CPU (frequency/power usage). Values are in units of MHz and milliwatts. .It Va dev.DEVICE.%d.freq_settings Currently available settings for the driver (frequency/power usage). Values are in units of MHz and milliwatts. This is helpful for understanding which settings are offered by which driver for debugging purposes. .It Va debug.cpufreq.lowest Lowest CPU frequency in MHz to offer to users. This setting is also accessible via a tunable with the same name. This can be used to disable very low levels that may be unusable on some systems. .It Va debug.cpufreq.verbose Print verbose messages. This setting is also accessible via a tunable with the same name. .El .Sh SUPPORTED DRIVERS The following device drivers offer absolute frequency control via the .Nm interface. Usually, only one of these can be active at a time. .Pp .Bl -tag -compact -width ".Pa acpi_perf" .It Pa acpi_perf ACPI CPU performance states .It Pa est Intel Enhanced SpeedStep .It Pa ichss Intel SpeedStep for ICH .It Pa powernow -AMD PowerNow! for K7 and K8 +AMD PowerNow!\& for K7 and K8 .It Pa smist Intel SMI-based SpeedStep for PIIX4 .El .Pp The following device drivers offer relative frequency control and have an additive effect: .Pp .Bl -tag -compact -width ".Pa acpi_throttle" .It Pa acpi_throttle ACPI CPU throttling .It Pa p4tcc Pentium 4 Thermal Control Circuitry .El .Sh KERNEL INTERFACE Kernel components can query and set CPU frequencies through the .Nm kernel interface. This involves obtaining a .Nm device, calling .Fn cpufreq_levels to get the currently available frequency levels, checking the current level with .Fn cpufreq_get , and setting a new one from the list with .Fn cpufreq_set . Each level may actually reference more than one .Nm driver but kernel components do not need to be aware of this. The .Va total_set element of .Vt "struct cf_level" provides a summary of the frequency and power for this level. Unknown or irrelevant values are set to .Dv CPUFREQ_VAL_UNKNOWN . .Pp The .Fn cpufreq_levels method takes a .Nm device and an empty array of .Fa levels . The .Fa count value should be set to the number of levels available and after the function completes, will be set to the actual number of levels returned. If there are more levels than .Fa count will allow, it should return .Er E2BIG . .Pp The .Fn cpufreq_get method takes a pointer to space to store a .Fa level . After successful completion, the output will be the current active level and is equal to one of the levels returned by .Fn cpufreq_levels . .Pp The .Fn cpufreq_set method takes a pointer a .Fa level and attempts to activate it. The .Fa priority (i.e., .Dv CPUFREQ_PRIO_KERN ) tells .Nm whether to override previous settings while activating this level. If .Fa priority is higher than the current active level, that level will be saved and overridden with the new level. If a level is already saved, the new level is set without overwriting the older saved level. If .Fn cpufreq_set is called with a .Dv NULL .Fa level , the saved level will be restored. If there is no saved level, .Fn cpufreq_set will return .Er ENXIO . If .Fa priority is lower than the current active level's priority, this method returns .Er EPERM . .Sh DRIVER INTERFACE Kernel drivers offering hardware-specific CPU frequency control export their individual settings through the .Nm driver interface. This involves implementing these methods: .Fn cpufreq_drv_settings , .Fn cpufreq_drv_type , .Fn cpufreq_drv_set , and .Fn cpufreq_drv_get . Additionally, the driver must attach a device as a child of a CPU device so that these methods can be called by the .Nm framework. .Pp The .Fn cpufreq_drv_settings method returns an array of currently available settings, each of type .Vt "struct cf_setting" . The driver should set unknown or irrelevant values to .Dv CPUFREQ_VAL_UNKNOWN . All the following elements for each setting should be returned: .Bd -literal struct cf_setting { int freq; /* CPU clock in Mhz or 100ths of a percent. */ int volts; /* Voltage in mV. */ int power; /* Power consumed in mW. */ int lat; /* Transition latency in us. */ device_t dev; /* Driver providing this setting. */ }; .Ed .Pp On entry to this method, .Fa count contains the number of settings that can be returned. On successful completion, the driver sets it to the actual number of settings returned. If the driver offers more settings than .Fa count will allow, it should return .Er E2BIG . .Pp The .Fn cpufreq_drv_type method indicates the type of settings it offers, either .Dv CPUFREQ_TYPE_ABSOLUTE or .Dv CPUFREQ_TYPE_RELATIVE . Additionally, the driver may set the .Dv CPUFREQ_FLAG_INFO_ONLY flag if the settings it provides are information for other drivers only and cannot be passed to .Fn cpufreq_drv_set to activate them. .Pp The .Fn cpufreq_drv_set method takes a driver setting and makes it active. If the setting is invalid or not currently available, it should return .Er EINVAL . .Pp The .Fn cpufreq_drv_get method returns the currently-active driver setting. The .Vt "struct cf_setting" returned must be valid for passing to .Fn cpufreq_drv_set , including all elements being filled out correctly. If the driver cannot infer the current setting (even by estimating it with .Fn cpu_est_clockrate ) then it should set all elements to .Dv CPUFREQ_VAL_UNKNOWN . .Sh SEE ALSO .Xr acpi 4 , .Xr sysctl 8 .Sh AUTHORS .An Nate Lawson .An Bruno Ducrot contributed the .Pa powernow driver. .Sh BUGS The following drivers have not yet been converted to the .Nm interface: .Xr longrun 4 . .Pp Notification of CPU and bus frequency changes is not implemented yet. .Pp When multiple CPUs offer frequency control, they cannot be set to different levels and must all offer the same frequency settings. Index: head/share/man/man4/ed.4 =================================================================== --- head/share/man/man4/ed.4 (revision 147397) +++ head/share/man/man4/ed.4 (revision 147398) @@ -1,354 +1,354 @@ .\" .\" Copyright (c) 1994, David Greenman .\" 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. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by David Greenman. .\" 4. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" 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 February 9, 2005 +.Dd February 23, 2005 .Dt ED 4 .Os .Sh NAME .Nm ed .Nd NE-2000 and WD-80x3 Ethernet driver .Sh SYNOPSIS .Cd "device miibus" .Cd "device ed" .Sh DESCRIPTION The .Nm driver provides support for 8 and 16bit Ethernet cards that are based on the National Semiconductor DS8390 and similar NICs manufactured by other companies. .Pp The .Nm driver uses a unique multi-buffering mechanism to achieve high transmit performance. When using 16bit ISA cards, as high as 97% of the theoretical maximum performance of the IEEE 802.3 CSMA Ethernet is possible. .Pp In addition to the standard port and IRQ specifications, the .Nm driver also supports a number of .Cd flags which can force 8/16bit mode, enable/disable multi-buffering, and select the default interface type (AUI/BNC, and for cards with twisted pair, AUI/10BaseT). .Pp The .Cd flags are a bit field, and are summarized as follows: .Bl -tag -width indent .It Li 0x01 Disable transceiver. On those cards which support it, this flag causes the transceiver to be disabled and the AUI connection to be used by default. .It Li 0x02 Force 8bit mode. This flag forces the card to 8bit mode regardless of how the card identifies itself. This may be needed for some clones which incorrectly identify themselves as 16bit, even though they only have an 8bit interface. This flag takes precedence over force 16bit mode. .It Li 0x04 Force 16bit mode. This flag forces the card to 16bit mode regardless of how the card identifies itself. This may be needed for some clones which incorrectly identify themselves as 8bit, even though they have a 16bit ISA interface. .It Li 0x08 Disable transmitter multi-buffering. This flag disables the use of multiple transmit buffers and may be necessary in rare cases where packets are sent out faster than a machine on the other end can handle (as evidenced by severe packet lossage). Some .No ( non- Ns Fx :-)) machines have terrible Ethernet performance and simply cannot cope with 1100K+ data rates. Use of this flag also provides one more packet worth of receiver buffering, and on 8bit cards, this may help reduce receiver lossage. .El .Pp When using a 3c503 card, the AUI connection may be selected by specifying the .Cm link2 option to .Xr ifconfig 8 (BNC is the default). .Sh HARDWARE The .Nm driver supports the following Ethernet NICs: .Pp .Bl -bullet -compact .It 3Com 3c503 Etherlink II .Pq Cd "options ED_3C503" .It AR-P500 Ethernet .It Accton EN1644 (old model), EN1646 (old model), EN2203 (old model) (110pin) (flags 0xd00000) .It Accton EN2212/EN2216/UE2216 .It Allied Telesis CentreCOM LA100-PCM_V2 .It Allied Telesis LA-98 (flags 0x000000) (PC-98) .It Allied Telesis SIC-98, SIC-98NOTE (110pin), SIU-98 (flags 0x600000) (PC-98) .It Allied Telesis SIU-98-D (flags 0x610000) (PC-98) .It AmbiCom 10BaseT card .It Bay Networks NETGEAR FA410TXC Fast Ethernet .It Belkin F5D5020 PC Card Fast Ethernet .It CNet BC40 adapter .It Compex Net-A adapter .It Contec C-NET(98), RT-1007(98), C-NET(9N) (110pin) (flags 0xa00000) (PC-98) .It Contec C-NET(98)E-A, C-NET(98)L-A, C-NET(98)P (flags 0x300000) (PC-98) .It Corega Ether98-T (flags 0x000000) (PC-98) .It Corega Ether PCC-T/EtherII PCC-T/FEther PCC-TXF/PCC-TXD .It CyQ've ELA-010 .It DEC EtherWorks DE305 .It Danpex EN-6200P2 .It D-Link DE-298, DE-298P (flags 0x500000) (PC-98) .It D-Link DE-650/660 .It D-Link IC-CARD/IC-CARD+ Ethernet .It ELECOM LD-98P (flags 0x500000) (PC-98) .It ELECOM LD-BDN, LD-NW801G (flags 0x200000) (PC-98) .It ELECOM Laneed LD-CDL/TX, LD-CDF, LD-CDS, LD-10/100CD, LD-CDWA (DP83902A) .It HP PC Lan+ 27247B and 27252A .Pq Cd "options ED_HPP" .It IBM Creditcard Ethernet I/II .It ICM AD-ET2-T, DT-ET-25, DT-ET-T5, IF-2766ET, IF-2771ET, NB-ET-T (110pin) (flags 0x500000) (PC-98) .It I-O DATA LA/T-98, LA/T-98SB, LA2/T-98, ET/T-98 (flags 0x900000) (PC-98) .It I-O DATA ET2/T-PCI .It I-O DATA PCLATE .It Kansai KLA-98C/T (flags 0x900000) (PC-98) .It Kingston KNE-PC2, KNE-PCM/x Ethernet .It Linksys EC2T/PCMPC100/PCM100, PCMLM56 .It Linksys EtherFast 10/100 PC Card, Combo PCMCIA Ethernet Card (PCMPC100 V2) .It Logitec LAN-98T (flags 0xb00000) (PC-98) .It MACNICA Ethernet ME1 for JEIDA .It MACNICA ME98 (flags 0x900000) (PC-98) .It MACNICA NE2098 (flags 0x400000) (PC-98) .It MELCO EGY-98 (flags 0x300000) (PC-98) .It MELCO LGH-98, LGY-98, LGY-98-N (110pin), IND-SP, IND-SS (flags 0x400000) (PC-98) .It MELCO LGY-PCI-TR .It MELCO LPC-T/LPC2-T/LPC2-CLT/LPC2-TX/LPC3-TX/LPC3-CLX .It NDC Ethernet Instant-Link .It NEC PC-9801-77, PC-9801-78 (flags 0x910000) (PC-98) .It NEC PC-9801-107, PC-9801-108 (flags 0x800000) (PC-98) .It National Semiconductor InfoMover NE4100 .It NetGear FA-410TX .It NetVin 5000 .It Network Everywhere Ethernet 10BaseT PC Card .It Networld 98X3 (flags 0xd00000) (PC-98) .It Networld EC-98X, EP-98X (flags 0xd10000) (PC-98) .It Novell NE1000/NE2000/NE2100 .It PLANEX ENW-8300-T .It PLANEX EN-2298-C (flags 0x200000) (PC-98) .It PLANEX EN-2298P-T, EN-2298-T (flags 0x500000) (PC-98) .It PLANEX FNW-3600-T .It RealTek 8029 .It SMC Elite 16 WD8013 .It SMC Elite Ultra .It SMC EtherEZ98 (flags 0x000000) (PC-98) .It SMC WD8003E/WD8003EBT/WD8003S/WD8003SBT/WD8003W/WD8013EBT/WD8013W and clones .It Socket LP-E .It Surecom EtherPerfect EP-427 .It Surecom NE-34 .It TDK LAK-CD031, Grey Cell GCS2000 Ethernet Card .It Telecom Device SuperSocket RE450T .It VIA VT86C926 .It Winbond W89C940 .El .Pp C-Bus, ISA, PCI and PC Card devices are supported. .Sh DIAGNOSTICS .Bl -diag .It "ed%d: kernel configured irq %d doesn't match board configured irq %d." The IRQ number that was specified in the kernel config file (and then compiled into the kernel) differs from the IRQ that has been set on the interface card. .It "ed%d: failed to clear shared memory at %x - check configuration." When the card was probed at system boot time, the .Nm driver found that it could not clear the card's shared memory. This is most commonly caused by a BIOS extension ROM being configured in the same address space as the Ethernet card's shared memory. Either find the offending card and change its BIOS ROM to be at an address that does not conflict, or change the .Cd iomem option in the kernel config file so that the card's shared memory is mapped at a non-conflicting address. .It "ed%d: Invalid irq configuration (%d) must be 2-5 for 3c503." The IRQ number that was specified in the kernel config file is not valid for the 3Com 3c503 card. The 3c503 can only be assigned to IRQs 2 through 5. .It "ed%d: Cannot find start of RAM." .It "ed%d: Cannot find any RAM, start : %d, x = %d." The probe of a Gateway card was unsuccessful in configuring the card's packet memory. This likely indicates that the card was improperly recognized as a Gateway or that the card is defective. .It "ed: packets buffered, but transmitter idle." Indicates a logic problem in the driver. Should never happen. .It "ed%d: device timeout" Indicates that an expected transmitter interrupt did not occur. Usually caused by an interrupt conflict with another card on the ISA bus. This condition could also be caused if the kernel is configured for a different IRQ channel than the one the card is actually using. If that is the case, you will have to either reconfigure the card using a DOS utility or set the jumpers on the card appropriately. .It "ed%d: NIC memory corrupt - invalid packet length %d." Indicates that a packet was received with a packet length that was either larger than the maximum size or smaller than the minimum size allowed by the IEEE 802.3 standard. Usually caused by a conflict with another card on the ISA bus, but in some cases may also indicate faulty cabling. .It "ed%d: remote transmit DMA failed to complete." This indicates that a programmed I/O transfer to an NE1000 or NE2000 style card has failed to properly complete. Usually caused by the ISA bus speed being set too fast. .El .Sh CAVEATS Early revision DS8390 chips have problems. They lock up whenever the receive ring-buffer overflows. They occasionally switch the byte order of the length field in the packet ring header (several different causes of this related to an off-by-one byte alignment) - resulting in .Qq Li "NIC memory corrupt - invalid packet length" messages. The card is reset whenever these problems occur, but otherwise there is no problem with recovering from these conditions. .Pp The NIC memory access to 3Com and Novell cards is much slower than it is on WD/SMC cards; it is less than 1MB/second on 8bit boards and less than 2MB/second on the 16bit cards. This can lead to ring-buffer overruns resulting in dropped packets during heavy network traffic. .Pp 16bit Compex cards identify themselves as being 8bit. While these cards will work in 8bit mode, much higher performance can be achieved by specifying .Cd "flags 0x04" (force 16bit mode) in your kernel config file. In addition, you should also specify .Cd "iosiz 16384" to take advantage of the extra 8K of shared memory that 16bit mode provides. .Sh SEE ALSO .Xr arp 4 , .Xr miibus 4 , .Xr netintro 4 , .Xr ng_ether 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 1.0 . .Sh AUTHORS The .Nm device driver and this manual page were written by .An David Greenman . .Sh BUGS The .Nm driver is a bit too aggressive about resetting the card whenever any bad packets are received. As a result, it may throw out some good packets which have been received but not yet transferred from the card to main memory. Index: head/share/man/man4/geom.4 =================================================================== --- head/share/man/man4/geom.4 (revision 147397) +++ head/share/man/man4/geom.4 (revision 147398) @@ -1,371 +1,371 @@ .\" .\" Copyright (c) 2002 Poul-Henning Kamp .\" Copyright (c) 2002 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" This software was developed for the FreeBSD Project by Poul-Henning Kamp .\" and NAI Labs, the Security Research Division of Network Associates, Inc. .\" under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the .\" DARPA CHATS research program. .\" .\" 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. .\" 3. The names of the authors may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" 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 March 27, 2002 .Os .Dt GEOM 4 .Sh NAME .Nm GEOM .Nd modular disk I/O request transformation framework. .Sh DESCRIPTION The GEOM framework provides an infrastructure in which "classes" can perform transformations on disk I/O requests on their path from the upper kernel to the device drivers and back. .Pp Transformations in a GEOM context range from the simple geometric displacement performed in typical disk partitioning modules over RAID algorithms and device multipath resolution to full blown cryptographic protection of the stored data. .Pp Compared to traditional "volume management", GEOM differs from most and in some cases all previous implementations in the following ways: .Bl -bullet .It GEOM is extensible. It is trivially simple to write a new class of transformation and it will not be given stepchild treatment. If someone for some reason wanted to mount IBM MVS diskpacks, a class recognizing and configuring their VTOC information would be a trivial matter. .It GEOM is topologically agnostic. Most volume management implementations have very strict notions of how classes can fit together, very often one fixed hierarchy is provided for instance subdisk - plex - volume. .El .Pp Being extensible means that new transformations are treated no differently than existing transformations. .Pp Fixed hierarchies are bad because they make it impossible to express the intent efficiently. In the fixed hierarchy above it is not possible to mirror two physical disks and then partition the mirror into subdisks, instead one is forced to make subdisks on the physical volumes and to mirror these two and two resulting in a much more complex configuration. GEOM on the other hand does not care in which order things are done, the only restriction is that cycles in the graph will not be allowed. .Pp .Sh "TERMINOLOGY and TOPOLOGY" GEOM is quite object oriented and consequently the terminology borrows a lot of context and semantics from the OO vocabulary: .Pp A "class", represented by the data structure g_class implements one particular kind of transformation. Typical examples are MBR disk partition, BSD disklabel, and RAID5 classes. .Pp An instance of a class is called a "geom" and represented by the data structure "g_geom". In a typical i386 FreeBSD system, there will be one geom of class MBR for each disk. .Pp A "provider", represented by the data structure "g_provider", is the front gate at which a geom offers service. A provider is "a disk-like thing which appears in /dev" - a logical disk in other words. All providers have three main properties: name, sectorsize and size. .Pp A "consumer" is the backdoor through which a geom connects to another geom provider and through which I/O requests are sent. .Pp The topological relationship between these entities are as follows: .Bl -bullet .It A class has zero or more geom instances. .It A geom has exactly one class it is derived from. .It A geom has zero or more consumers. .It A geom has zero or more providers. .It A consumer can be attached to zero or one providers. .It A provider can have zero or more consumers attached. .El .Pp All geoms have a rank-number assigned, which is used to detect and prevent loops in the acyclic directed graph. This rank number is assigned as follows: .Bl -enum .It A geom with no attached consumers has rank=1 .It A geom with attached consumers has a rank one higher than the highest rank of the geoms of the providers its consumers are attached to. .El .Sh "SPECIAL TOPOLOGICAL MANEUVERS" In addition to the straightforward attach, which attaches a consumer to a provider, and detach, which breaks the bond, a number of special topological maneuvers exists to facilitate configuration and to improve the overall flexibility. .Pp .Em TASTING is a process that happens whenever a new class or new provider is created and it provides the class a chance to automatically configure an instance on providers, which it recognize as its own. A typical example is the MBR disk-partition class which will look for the MBR table in the first sector and if found and validated it will instantiate a geom to multiplex according to the contents of the MBR. .Pp A new class will be offered to all existing providers in turn and a new provider will be offered to all classes in turn. .Pp Exactly what a class does to recognize if it should accept the offered provider is not defined by GEOM, but the sensible set of options are: .Bl -bullet .It Examine specific data structures on the disk. .It Examine properties like sectorsize or mediasize for the provider. .It Examine the rank number of the provider's geom. .It Examine the method name of the provider's geom. .El .Pp .Em ORPHANIZATION is the process by which a provider is removed while it potentially is still being used. .Pp When a geom orphans a provider, all future I/O requests will "bounce" on the provider with an error code set by the geom. Any consumers attached to the provider will receive notification about the orphanization when the eventloop gets around to it, and they can take appropriate action at that time. .Pp A geom which came into being as a result of a normal taste operation should selfdestruct unless it has a way to keep functioning lacking the orphaned provider. Geoms like diskslicers should therefore selfdestruct whereas RAID5 or mirror geoms will be able to continue, as long as they do not loose quorum. .Pp When a provider is orphaned, this does not necessarily result in any immediate change in the topology: any attached consumers are still attached, any opened paths are still open, any outstanding I/O requests are still outstanding. .Pp The typical scenario is .Bl -bullet -offset indent -compact .It A device driver detects a disk has departed and orphans the provider for it. .It The geoms on top of the disk receive the orphanization event and orphans all their providers in turn. Providers, which are not attached to, will typically self-destruct right away. This process continues in a quasi-recursive fashion until all relevant pieces of the tree has heard the bad news. .It Eventually the buck stops when it reaches geom_dev at the top of the stack. .It Geom_dev will call destroy_dev(9) to stop any more request from coming in. It will sleep until all (if any) outstanding I/O requests have been returned. It will explicitly close (ie: zero the access counts), a change which will propagate all the way down through the mesh. It will then detach and destroy its geom. .It The geom whose provider is now attached will destroy the provider, detach and destroy its consumer and destroy its geom. .It This process percolates all the way down through the mesh, until the cleanup is complete. .El .Pp While this approach seems byzantine, it does provide the maximum flexibility and robustness in handling disappearing devices. .Pp The one absolutely crucial detail to be aware is that if the device driver does not return all I/O requests, the tree will not unravel. .Pp .Em SPOILING is a special case of orphanization used to protect against stale metadata. It is probably easiest to understand spoiling by going through an example. .Pp Imagine a disk, "da0" on top of which a MBR geom provides "da0s1" and "da0s2" and on top of "da0s1" a BSD geom provides "da0s1a" through "da0s1e", both the MBR and BSD geoms have autoconfigured based on data structures on the disk media. Now imagine the case where "da0" is opened for writing and those data structures are modified or overwritten: Now the geoms would be operating on stale metadata unless some notification system can inform them otherwise. .Pp To avoid this situation, when the open of "da0" for write happens, all attached consumers are told about this, and geoms like MBR and BSD will selfdestruct as a result. When "da0" is closed again, it will be offered for tasting again and if the data structures for MBR and BSD are still there, new geoms will instantiate themselves anew. .Pp Now for the fine print: .Pp If any of the paths through the MBR or BSD module were open, they would have opened downwards with an exclusive bit rendering it impossible to open "da0" for writing in that case and conversely the requested exclusive bit would render it impossible to open a path through the MBR geom while "da0" is open for writing. .Pp From this it also follows that changing the size of open geoms can only be done with their cooperation. .Pp Finally: the spoiling only happens when the write count goes from zero to non-zero and the retasting only when the write count goes from non-zero to zero. .Pp .Em INSERT/DELETE are a very special operation which allows a new geom to be instantiated between a consumer and a provider attached to each other and to remove it again. .Pp To understand the utility of this, imagine a provider with being mounted as a file system. Between the DEVFS geoms consumer and its provider we insert a mirror module which configures itself with one mirror copy and consequently is transparent to the I/O requests on the path. We can now configure yet a mirror copy on the mirror geom, request a synchronization, and finally drop the first mirror copy. We have now in essence moved a mounted file system from one disk to another while it was being used. At this point the mirror geom can be deleted from the path again, it has served its purpose. .Pp .Em CONFIGURE is the process where the administrator issues instructions for a particular class to instantiate itself. There are multiple ways to express intent in this case, a particular provider can be specified with a level of override forcing for instance a BSD disklabel module to attach to a provider which was not found palatable during the TASTE operation. .Pp Finally IO is the reason we even do this: it concerns itself with sending I/O requests through the graph. .Pp .Em "I/O REQUESTS represented by struct bio, originate at a consumer, are scheduled on its attached provider, and when processed, returned to the consumer. It is important to realize that the struct bio which enters through the provider of a particular geom does not "come out on the other side". Even simple transformations like MBR and BSD will clone the struct bio, modify the clone, and schedule the clone on their own consumer. Note that cloning the struct bio does not involve cloning the actual data area specified in the IO request. .Pp In total four different IO requests exist in GEOM: read, write, delete, and get attribute. .Pp Read and write are self explanatory. .Pp Delete indicates that a certain range of data is no longer used and that it can be erased or freed as the underlying technology supports. Technologies like flash adaptation layers can arrange to erase the relevant blocks before they will become reassigned and cryptographic devices may want to fill random bits into the range to reduce the amount of data available for attack. .Pp It is important to recognize that a delete indication is not a request and consequently there is no guarantee that the data actually will be erased or made unavailable unless guaranteed by specific geoms in the graph. If "secure delete" semantics are required, a geom should be pushed which converts delete indications into (a sequence of) write requests. .Pp Get attribute supports inspection and manipulation of out-of-band attributes on a particular provider or path. Attributes are named by ascii strings and they will be discussed in a separate section below. .Pp (stay tuned while the author rests his brain and fingers: more to come.) .Sh DIAGNOSTICS Several flags are provided for tracing GEOM operations and unlocking protection mechanisms via the .Va kern.geom.debugflags sysctl. All of these flags are off by default, and great care should be taken in turning them on. .Bl -tag -width FAIL -.It 0x01 (G_T_TOPOLOGY) +.It 0x01 Pq Dv G_T_TOPOLOGY Provide tracing of topology change events. -.It 0x02 (G_T_BIO) +.It 0x02 Pq Dv G_T_BIO Provide tracing of buffer I/O requests. -.It 0x04 (G_T_ACCESS) +.It 0x04 Pq Dv G_T_ACCESS Provide tracing of access check controls. .It 0x08 (unused) .It 0x10 (allow foot shooting) Allow writing to Rank 1 providers. This would, for example, allow the super-user to overwrite the MBR on the root -disk or write random sectors elsewhere to a mounted disk. The implications -are obvious. -.It 0x20 (G_T_DETAILS) +disk or write random sectors elsewhere to a mounted disk. +The implications are obvious. +.It 0x20 Pq Dv G_T_DETAILS This appears to be unused at this time. -.It 0x40 (G_F_DISKIOCTL) +.It 0x40 Pq Dv G_F_DISKIOCTL This appears to be unused at this time. -.It 0x80 (G_F_CTLDUMP) +.It 0x80 Pq Dv G_F_CTLDUMP Dump contents of gctl requests. .El .Sh HISTORY This software was developed for the FreeBSD Project by Poul-Henning Kamp -and NAI Labs, the Security Research Division of Network Associates, Inc. +and NAI Labs, the Security Research Division of Network Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the DARPA CHATS research program. .Pp The first precursor for GEOM was a gruesome hack to Minix 1.2 and was never distributed. An earlier attempt to implement a less general scheme in FreeBSD never succeeded. .Sh AUTHORS .An "Poul-Henning Kamp" Aq phk@FreeBSD.org Index: head/share/man/man4/icmp6.4 =================================================================== --- head/share/man/man4/icmp6.4 (revision 147397) +++ head/share/man/man4/icmp6.4 (revision 147398) @@ -1,257 +1,265 @@ .\" $KAME: icmp6.4,v 1.6 2004/12/27 05:30:56 itojun Exp $ .\" $OpenBSD: icmp6.4,v 1.19 2004/12/23 20:33:03 jaredy Exp $ .\" .\" Copyright (c) 1986, 1991, 1993 .\" The Regents of the University of California. 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. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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, 2004 .Dt ICMP6 4 .Os .Sh NAME .Nm icmp6 .Nd Internet Control Message Protocol for IPv6 .Sh SYNOPSIS .In sys/socket.h .In netinet/in.h .In netinet/icmp6.h .Ft int .Fn socket AF_INET6 SOCK_RAW IPPROTO_ICMPV6 .Sh DESCRIPTION ICMPv6 is the error and control message protocol used by IPv6 and the IPv6 protocol family (see .Xr ip6 4 and .Xr inet6 4 ) . It may be accessed through a .Dq raw socket for network monitoring and diagnostic functions. .Pp The .Fa proto parameter to the .Xr socket 2 call to create an ICMPv6 socket may be obtained from .Xr getprotobyname 3 . ICMPv6 sockets are connectionless, and are normally used with the .Xr sendto 2 and .Xr recvfrom 2 calls, though the .Xr connect 2 call may also be used to fix the destination for future packets (in which case .Xr read 2 or .Xr recv 2 and .Xr write 2 or .Xr send 2 system calls may be used). .Pp Outgoing packets automatically have an IPv6 header prepended to them (based on the destination address). Incoming packets on the socket are received with the IPv6 header and any extension headers removed. .Ss Types ICMPv6 messages are classified according to the type and code fields present in the ICMPv6 header. The abbreviations for the types and codes may be used in rules in .Xr pf.conf 5 . The following types are defined: .Bl -column x xxxxxxxxxxxx -offset indent .It Sy Num Ta Sy Abbrev. Ta Sy Description .It 1 Ta unreach Ta "Destination unreachable" .It 2 Ta toobig Ta "Packet too big" .It 3 Ta timex Ta "Time exceeded" .It 4 Ta paramprob Ta "Invalid IPv6 header" .It 128 Ta echoreq Ta "Echo service request" .It 129 Ta echorep Ta "Echo service reply" .It 130 Ta groupqry Ta "Group membership query" .It 130 Ta listqry Ta "Multicast listener query" .It 131 Ta grouprep Ta "Group membership report" .It 131 Ta listenrep Ta "Multicast listener report" .It 132 Ta groupterm Ta "Group membership termination" .It 132 Ta listendone Ta "Multicast listerner done" .It 133 Ta routersol Ta "Router solicitation" .It 134 Ta routeradv Ta "Router advertisement" .It 135 Ta neighbrsol Ta "Neighbor solicitation" .It 136 Ta neighbradv Ta "Neighbor advertisement" .It 137 Ta redir Ta "Shorter route exists" .It 138 Ta routrrenum Ta "Route renumbering" .It 139 Ta fqdnreq Ta "FQDN query" .It 139 Ta niqry Ta "Node information query" .It 139 Ta wrureq Ta "Who-are-you request" .It 140 Ta fqdnrep Ta "FQDN reply" .It 140 Ta nirep Ta "Node information reply" .It 140 Ta wrurep Ta "Who-are-you reply" .It 200 Ta mtraceresp Ta "mtrace response" .It 201 Ta mtrace Ta "mtrace messages" .El .Pp The following codes are defined: .Bl -column x xxxxxxxxxxxx xxxxxxxx -offset indent .It Sy Num Ta Sy Abbrev. Ta Sy Type Ta .Sy Description .It 0 Ta noroute-unr Ta unreach Ta "No route to destination" .It 1 Ta admin-unr Ta unreach Ta "Administratively prohibited" .It 2 Ta beyond-unr Ta unreach Ta "Beyond scope of source address" .It 2 Ta notnbr-unr Ta unreach Ta "Not a neighbor (obselete)" .It 3 Ta addr-unr Ta unreach Ta "Address unreachable" .It 4 Ta port-unr Ta unreach Ta "Port unreachable" .It 0 Ta transit Ta timex Ta "Time exceeded in transit" .It 1 Ta reassemb Ta timex Ta "Time exceeded in reassembly" .It 0 Ta badhead Ta paramprob Ta "Erroneous header field" .It 1 Ta nxthdr Ta paramprob Ta "Unrecognized next header" .It 2 Ta "" Ta redir Ta "Unrecognized option" .It 0 Ta redironlink Ta redir Ta "Redirection to on-link node" .It 1 Ta redirrouter Ta redir Ta "Redirection to better router" .El .Ss Headers All ICMPv6 messages are prefixed with an ICMPv6 header. This header corresponds to the .Vt icmp6_hdr structure and has the following definition: .Bd -literal -offset indent struct icmp6_hdr { u_int8_t icmp6_type; /* type field */ u_int8_t icmp6_code; /* code field */ u_int16_t icmp6_cksum; /* checksum field */ union { u_int32_t icmp6_un_data32[1]; /* type-specific */ u_int16_t icmp6_un_data16[2]; /* type-specific */ u_int8_t icmp6_un_data8[4]; /* type-specific */ } icmp6_dataun; } __packed; #define icmp6_data32 icmp6_dataun.icmp6_un_data32 #define icmp6_data16 icmp6_dataun.icmp6_un_data16 #define icmp6_data8 icmp6_dataun.icmp6_un_data8 #define icmp6_pptr icmp6_data32[0] /* parameter prob */ #define icmp6_mtu icmp6_data32[0] /* packet too big */ #define icmp6_id icmp6_data16[0] /* echo request/reply */ #define icmp6_seq icmp6_data16[1] /* echo request/reply */ #define icmp6_maxdelay icmp6_data16[0] /* mcast group membership*/ .Ed .Pp .Va icmp6_type describes the type of the message. Suitable values are defined in .Aq Pa netinet/icmp6.h . .Va icmp6_code describes the sub-type of the message and depends on .Va icmp6_type . .Va icmp6_cksum contains the checksum for the message and is filled in by the kernel on outgoing messages. The other fields are used for type-specific purposes. .Ss Filters Because of the extra functionality of ICMPv6 in comparison to ICMPv4, a larger number of messages may be potentially received on an ICMPv6 socket. Input filters may therefore be used to restrict input to a subset of the incoming ICMPv6 messages so only interesting messages are returned by the .Xr recv 2 family of calls to an application. .Pp The .Vt icmp6_filter structure may be used to refine the input message set according to the ICMPv6 type. By default, all messages types are allowed on newly created raw ICMPv6 sockets. The following macros may be used to refine the input set: .Bl -tag -width Ds .It Fn "void ICMP6_FILTER_SETPASSALL" "struct icmp6_filter *filterp" Allow all incoming messages. .Va filterp is modified to allow all message types. .It Fn "void ICMP6_FILTER_SETBLOCKALL" "struct icmp6_filter *filterp" Ignore all incoming messages. .Va filterp is modified to ignore all message types. -.It Fn "void ICMP6_FILTER_SETPASS" "int type" \ - "struct icmp6_filter *filterp" +.It Xo +.Ft void +.Fn ICMP6_FILTER_SETPASS "int type" "struct icmp6_filter *filterp" +.Xc Allow ICMPv6 messages with the given .Fa type . .Va filterp is modified to allow such messages. -.It Fn "void ICMP6_FILTER_SETBLOCK" "int type" \ - "struct icmp6_filter *filterp" +.It Xo +.Ft void +.Fn ICMP6_FILTER_SETBLOCK" "int type" "struct icmp6_filter *filterp" +.Xc Ignore ICMPv6 messages with the given .Fa type . .Va filterp is modified to ignore such messages. -.It Fn "int ICMP6_FILTER_WILLPASS" "int type" \ - "const struct icmp6_filter *filterp" +.It Xo +.Ft int +.Fn ICMP6_FILTER_WILLPASS" "int type" "const struct icmp6_filter *filterp" +.Xc Determine if the given filter will allow an ICMPv6 message of the given type. -.It Fn "int ICMP6_FILTER_WILLBLOCK" "int type" \ - "const struct icmp6_filter *filterp" +.It Xo +.Ft int +.Fn ICMP6_FILTER_WILLBLOCK" "int type" "const struct icmp6_filter *filterp" +.Xc Determine if the given filter will ignore an ICMPv6 message of the given type. .El .Pp The .Xr getsockopt 2 and .Xr setsockopt 2 calls may be used to obtain and install the filter on ICMPv6 sockets at option level .Dv IPPROTO_ICMPV6 and name .Dv ICMPV6_FILTER with a pointer to the .Vt icmp6_filter structure as the option value. .Sh SEE ALSO .Xr getsockopt 2 , .Xr recv 2 , .Xr send 2 , .Xr setsockopt 2 , .Xr socket 2 , .Xr getprotobyname 3 , .Xr inet6 4 , .Xr ip6 4 , .Xr netintro 4 .Rs .%A W. Stevens .%A M. Thomas .%T Advanced Sockets API for IPv6 .%N RFC 2292 .%D February 1998 .Re .Rs .%A A. Conta .%A S. Deering .%T "Internet Control Message Protocol (ICMPv6) for the Internet" \ "Protocol Version 6 (IPv6) Specification" .%N RFC 2463 .%D December 1998 .Re Index: head/share/man/man4/ng_netflow.4 =================================================================== --- head/share/man/man4/ng_netflow.4 (revision 147397) +++ head/share/man/man4/ng_netflow.4 (revision 147398) @@ -1,274 +1,274 @@ .\" Copyright (c) 2004-2005 Gleb Smirnoff .\" 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 May 11, 2005 .Os .Dt NG_NETFLOW 4 .Sh NAME .Nm ng_netflow .Nd Cisco's NetFlow implementation .Sh SYNOPSIS .In sys/types.h .In netinet/in.h .In netgraph/netflow/ng_netflow.h .Sh DESCRIPTION The .Nm node implements Cisco's NetFlow export protocol on a router running .Fx . The .Nm node listens for incoming traffic and identifies unique flows in it. Flows are distinguished by endpoint IP addresses, TCP/UDP port numbers, ToS and input interface. Expired flows are exported out of the node in NetFlow version 5 UDP datagrams. Expiration reason can be one of the following: .Bl -dash .It RST or FIN TCP segment. .It Active timeout. Flows cannot live more than the specified period of time. The default is 1800 seconds (30 minutes). .It Inactive timeout. A flow was inactive for the specified period of time. The default is 15 seconds. .El .Pp Export information is stored in NetFlow version 5 datagrams. .Sh HOOKS This node type supports up to .Dv NG_NETFLOW_MAXIFACES hooks named .Va iface0 , iface1 , etc., and the same number of hooks named .Va out0 , out1 , etc., plus a single hook named .Va export . The node does NetFlow accounting of data received on .Va iface* hooks. If corresponding .Va out hook is connected, unmodified data is bypassed to it, otherwise data is freed. If data is received on .Va out hook, it is bypassed to corresponding .Va iface hook without any processing. When full export datagram is built it is sent to the .Va export hook. In normal operation, the .Va export hook is connected to the .Va inet/dgram/udp hook of the .Xr ng_ksocket 4 node. .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width indent .It Dv NGM_NETFLOW_INFO Returns some node statistics and the current timeout values in a .Vt "struct ng_netflow_info" . .It Dv NGM_NETFLOW_IFINFO Returns information about the .Va iface Ns Ar N hook. The hook number is passed as an argument. .It Dv NGM_NETFLOW_SETDLT Sets data link type on the .Va iface Ns Ar N hook. Currently, supported types are raw IP datagrams and Ethernet. This messsage type uses .Vt "struct ng_netflow_setdlt" as an argument: .Bd -literal -offset 4n struct ng_netflow_setdlt { uint16_t iface; /* which iface to operate on */ uint8_t dlt; /* DLT_XXX from bpf.h */ }; .Ed .Pp The requested .Va iface Ns Ar N hook must already be connected, otherwise message send operation will return an error. .It Dv NGM_NETFLOW_SETIFINDEX In some cases, .Nm may be unable to determine the input interface index of a packet. This can happen if traffic enters the .Nm node before it comes to the system interface's input queue. An example of such a setup is capturing a traffic .Em between synchronous data line and .Xr ng_iface 4 . In this case, the input index should be associated with a given hook. The interface's index can be determined via .Xr if_nametoindex 3 from userland. This message requires .Vt "struct ng_netflow_setifindex" as an argument: .Bd -literal -offset 4n struct ng_netflow_setifindex { u_int16_t iface; /* which iface to operate on */ u_int16_t index; /* new index */ }; .Ed .Pp The requested .Va iface Ns Ar N hook must already be connected, otherwise the message send operation will return an error. .It Dv NGM_NETFLOW_SETTIMEOUTS Sets values in seconds for NetFlow active/inactive timeouts. This message requires .Vt "struct ng_netflow_settimeouts" as an argument: .Bd -literal -offset 4n struct ng_netflow_settimeouts { uint32_t inactive_timeout; uint32_t active_timeout; }; .Ed .It Dv NGM_NETFLOW_SHOW This control message asks a node to dump the entire contents of the flow cache. It is called from .Xr flowctl 8 , not directly from .Xr ngctl 8 . See also .Sx BUGS section. .El .Sh ASCII CONTROL MESSAGES Most binary control messages have an .Tn ASCII equivalent. The supported .Tn ASCII commands are: .Pp .Bl -tag -width ".Dv NGM_NETFLOW_SETTIMEOUTS" -compact .It Dv NGM_NETFLOW_INFO .Qq Li info .It Dv NGM_NETFLOW_IFINFO .Qq Li "ifinfo %u" .It Dv NGM_NETFLOW_SETDLT .Qq Li "setdlt { iface = %u dlt = %u }" .It Dv NGM_NETFLOW_SETIFINDEX .Qq Li "setifindex { iface = %u index = %u }" .It Dv NGM_NETFLOW_SETTIMEOUTS .Qq Li "settimeouts { inactive = %u active = %u }" .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh EXAMPLES The simplest possible configuration is one Ethernet interface, where flow collecting is enabled. .Bd -literal -offset indent /usr/sbin/ngctl -f- <<-SEQ mkpeer fxp0: netflow lower iface0 name fxp0:lower netflow connect fxp0: netflow: upper out0 mkpeer netflow: ksocket export inet/dgram/udp msg netflow:export connect inet/10.0.0.1:4444 SEQ .Ed .Pp This is a more complicated example of a router with 2 NetFlow-enabled interfaces .Li fxp0 and .Li ng0 . Note that the .Va ng0: node in this example is connected to .Xr ng_tee 4 . The latter sends us a copy of IP packets, which we analyze and free. On .Va fxp0: we do not use tee, but send packets back to ether node. .Bd -literal -offset indent /usr/sbin/ngctl -f- <<-SEQ # connect ng0's tee to iface0 hook mkpeer ng0:inet netflow right2left iface0 name ng0:inet.right2left netflow # set DLT to raw mode msg netflow: setdlt { iface=0 dlt=12 } # set interface index (5 in this example) msg netflow: setifindex { iface=0 index=5 } # Connect fxp0: to iface1 and out1 hook connect fxp0: netflow: lower iface1 connect fxp0: netflow: upper out1 # Create ksocket node on export hook, and configure it # to send exports to proper destination mkpeer netflow: ksocket export inet/dgram/udp msg netflow:export connect inet/10.0.0.1:4444 SEQ .Ed .Sh SEE ALSO -.Xr flowctl 8 , .Xr netgraph 4 , .Xr ng_ksocket 4 , .Xr ng_tee 4 , +.Xr flowctl 8 , .Xr ngctl 8 .Pp .Pa http://www.cisco.com/warp/public/cc/pd/iosw/ioft/neflct/tech/napps_wp.htm .Sh AUTHORS .An -nosplit The .Nm node type was written by .An Gleb Smirnoff Aq glebius@FreeBSD.org , based on .Nm ng_ipacct written by .An Roman V. Palagin Aq romanp@unshadow.net . .Sh BUGS Cache snapshot obtained via .Dv NGM_NETFLOW_SHOW command may lack some percentage of entries under severe load. .Pp The .Nm node type does not fill in AS numbers. This is due to the lack of necessary information in the kernel routing table. However, this information can be injected into the kernel from a routing daemon such as GNU Zebra. This functionality may become available in future releases. Index: head/share/man/man4/ng_source.4 =================================================================== --- head/share/man/man4/ng_source.4 (revision 147397) +++ head/share/man/man4/ng_source.4 (revision 147398) @@ -1,281 +1,289 @@ .\" Copyright 2002 Sandvine Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Sandvine Inc.; provided, .\" however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Sandvine Inc. .\" trademarks, including the mark "SANDVINE" on advertising, endorsements, .\" or otherwise except as such appears in the above copyright notice or in .\" the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY SANDVINE "AS IS", AND TO THE MAXIMUM .\" EXTENT PERMITTED BY LAW, SANDVINE MAKES NO REPRESENTATIONS OR WARRANTIES, .\" EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, .\" ANY AND ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR .\" PURPOSE, OR NON-INFRINGEMENT. SANDVINE DOES NOT WARRANT, GUARANTEE, OR .\" MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE .\" USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY .\" OR OTHERWISE. IN NO EVENT SHALL SANDVINE BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 SANDVINE IS ADVISED OF THE POSSIBILITY OF SUCH .\" DAMAGE. .\" .\" Author: Dave Chapeskie .\" $FreeBSD$ .\" .Dd April 5, 2005 .Dt NG_SOURCE 4 .Os .Sh NAME .Nm ng_source .Nd netgraph node for traffic generation .Sh SYNOPSIS .In sys/types.h .In netgraph/ng_source.h .Sh DESCRIPTION The .Nm source node acts as a source of packets according to the parameters set up using control messages and input packets. The .Nm node type is used primarily for testing and benchmarking. .Sh HOOKS The .Nm source node has two hooks: .Va input and .Va output . The .Va output hook must remain connected, its disconnection will shutdown the node. .Sh OPERATION The operation of the node is as follows. Packets received on the .Va input hook are queued internally. -When +When .Va output hook is connected, .Nm node assumes that its neighbour node is of -.Xr ng_ether +.Xr ng_ether 4 node type. -The neighbor is queried for its interface name. +The neighbour is queried for its interface name. +The .Nm node then uses queue of the interface for its evil purposes. +The .Nm node also disables .Va autosrc option on neighbour -.Xr ng_ether +.Xr ng_ether 4 node. -If interface name can't be obtained automatically, it should -be configured explicitly with help of -.Dv NGM_SOURCE_SETIFACE +If interface name cannot be obtained automatically, it should +be configured explicitly with the +.Dv NGM_SOURCE_SETIFACE control message, and .Va autosrc should be turned off on -.Xr ng_ether +.Xr ng_ether 4 node manually. .Pp -Once interface is configured, upon receival of +Once interface is configured, upon receipt of a .Dv NGM_SOURCE_START control message the node starts sending the previously queued packets out the .Va output hook on every clock tick as fast as the connected interface will take them. While active, on every clock tick the node checks the available space in the interface queue and sends that many packets out its .Va output hook. -Once the number of packets indicated in the start message have been -sent, or upon reception of a stop message, the node stops sending data. +Once the number of packets indicated in the start message has been +sent, or upon receipt of a +.Dv NGM_SOURCE_STOP +message, the node stops sending data. .Sh CONTROL MESSAGES This node type supports the generic control messages as well as the following, which must be sent with the .Dv NGM_SOURCE_COOKIE attached. .Bl -tag -width indent .It Dv NGM_SOURCE_GET_STATS Pq Ic getstats Returns a structure containing the following fields: .Bl -tag -width indent .It Va outOctets The number of octets/bytes sent out the -.Dv output +.Va output hook. .It Va outFrames The number of frames/packets sent out the -.Dv output +.Va output hook. .It Va queueOctets The number of octets queued from the -.Dv input +.Va input hook. .It Va queueFrames The number of frames queued from the -.Dv input +.Va input hook. .It Va startTime The time the last start message was received. .It Va endTime The time the last end message was received or the output packet count was reached. .It Va elapsedTime Either .Va endTime Li \- Va startTime or current time \- .Va startTime . .El .It Dv NGM_SOURCE_CLR_STATS Pq Ic clrstats Clears and resets the statistics returned by .Ic getstats (except .Va queueOctets and .Va queueFrames ) . .It Dv NGM_SOURCE_GETCLR_STATS Pq Ic getclrstats As .Ic getstats but clears the statistics at the same time. .It Dv NGM_SOURCE_START Pq Ic start This message requires a single .Vt uint64_t parameter which is the number of packets to send before stopping. -Node starts sending the queued packets out the output hook. -The output hook must be connected and node must have +Node starts sending the queued packets out the +.Va output +hook. +The +.Va output +hook must be connected and node must have interface configured. .It Dv NGM_SOURCE_STOP Pq Ic stop Stops the node if it is active. .It Dv NGM_SOURCE_CLR_DATA Pq Ic clrdata Clears the packets queued from the -.Dv input +.Va input hook. .It Dv NGM_SOURCE_SETIFACE Pq Ic setiface -This message requires a string argument - name of the interface -to be configured. +This message requires the name of the interface +to be configured as an argument. .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN -control message, when all hooks has been disconnected, or when the +control message, when all hooks have been disconnected, or when the .Va output hook has been disconnected. .Sh EXAMPLES Attach the node to an .Xr ng_ether 4 node for an interface. If .Nm ng_ether is not already loaded you will need to do so. For example, these commands load the .Nm ng_ether module and attach the -.Dv output +.Va output hook of a new .Nm source node to -.Dv orphans +.Va orphans hook of the .Li bge0: .Nm ng_ether node. .Bd -literal -offset indent kldload ng_ether ngctl mkpeer bge0: source orphans output .Ed .Pp At this point the new node can be referred to as .Dq Li bge0:orphans . The node can be given its own name like this: .Pp .Dl "ngctl name bge0:orphans src0" .Pp After which it can be referred to as .Dq Li src0: . .Pp Once created, packets need to be sent to the node, the TCL net package can be used to generate these packets: .Pp [Sandvine specific TCL code example omitted] .Pp To feed the output of the above TCL script to the .Nm source node's -.Dv input +.Va input hook via .Xr nghook 8 : .Pp .Dl "tcl genPacket | nghook bge0:orphans input" .Pp To check that the node has queued these packets you can get the node statistics: .Bd -literal -offset indent ngctl msg bge0:orphans getstats Args: { queueOctets=64 queueFrames=1 } .Ed .Pp Send as many packets as required out the -.Dv output +.Va output hook: .Pp .Dl "ngctl msg bge0:orphans start 16" .Pp Either wait for them to be sent (periodically fetching stats if desired) or send the stop message: .Pp .Dl "ngctl msg bge0:orphans stop" .Pp Check the statistics (here we use .Ic getclrstats to also clear the statistics): .Bd -literal -offset indent ngctl msg bge0:orphans getclrstats Args: { outOctets=1024 outFrames=16 queueOctets=64 queueFrames=1 startTime={ tv_sec=1035305880 tv_usec=758036 } endTime={ tv_sec=1035305880 tv_usec=759041 } elapsedTime={ tv_usec=1005 } } .Ed .Pp The times are from .Vt "struct timeval" Ns s , the .Va tv_sec field is seconds since the Epoch and can be converted into a date string via TCL's [clock format] or via the .Xr date 1 command: .Bd -literal -offset indent date -r 1035305880 Tue Oct 22 12:58:00 EDT 2002 .Ed .Sh SEE ALSO .Xr netgraph 4 , .Xr ng_echo 4 , .Xr ng_hole 4 , .Xr ng_tee 4 , .Xr ngctl 8 , .Xr nghook 8 .Sh HISTORY The .Nm node type was implemented in .Fx 4.8 . .Sh AUTHORS .An Dave Chapeskie Aq dchapeskie@SANDVINE.com Index: head/share/man/man4/snd_emu10k1.4 =================================================================== --- head/share/man/man4/snd_emu10k1.4 (revision 147397) +++ head/share/man/man4/snd_emu10k1.4 (revision 147398) @@ -1,67 +1,67 @@ .\" Copyright (c) 2004 Atte Peltomaki .\" 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 August 27, 2004 .Dt SND_EMU10K1 4 .Os .Sh NAME .Nm snd_emu10k1 .Nd "SoundBlaster Live! and Audigy PCI bridge device driver" .Sh SYNOPSIS .Cd "device sound" .Cd "device snd_emu10k1" .Sh DESCRIPTION The .Nm bridge driver allows the generic audio driver .Xr sound 4 -to attach to the SoundBlaster Live! and Audigy audio cards. +to attach to the SoundBlaster Live!\& and Audigy audio cards. .Pp Digital output is supported by default. .Sh HARDWARE The .Nm driver supports the following sound cards: .Pp .Bl -bullet -compact .It -Creative SoundBlaster Live! (EMU10K1 Chipset) +Creative SoundBlaster Live!\& (EMU10K1 Chipset) .It Creative SoundBlaster Audigy (EMU10K2 Chipset) .El .Sh SEE ALSO .Xr sound 4 .Sh HISTORY The .Nm manual page first appeared in .Fx 5.3 . .Sh AUTHORS .An "David O'Brien" Aq obrien@FreeBSD.org .An "Orlando Bassotto" Aq orlando.bassotto@ieo-research.it .An "Cameron Grant" Aq cg@FreeBSD.org .Sh BUGS Fancy features like DD5.1 output are not supported. Index: head/share/man/man4/snd_maestro3.4 =================================================================== --- head/share/man/man4/snd_maestro3.4 (revision 147397) +++ head/share/man/man4/snd_maestro3.4 (revision 147398) @@ -1,89 +1,89 @@ .\" Copyright (c) 2001 Scott Long .\" 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 14, 2004 .Dt SND_MAESTRO3 4 .Os .Sh NAME .Nm snd_maestro3 .Nd "ESS Maestro3/Allegro-1 bridge device driver" .Sh SYNOPSIS .Cd "device sound" .Cd "device snd_maestro3" .Sh DESCRIPTION The .Nm driver provides support for the ESS Maestro3 and Allegro-1 sound chips under the PCM framework. These chips are mostly found in laptop computers and feature an AC97 mixer, a multi-channel sample rate converter that can mix up to four digital audio streams in hardware, recording support, and external volume control buttons. .Pp The firmware for the sound processor is licensed under the GNU Public License, and thus this driver is not included in the default .Pa GENERIC kernel. A convenient way to automatically load the driver is to add the line .Pp .Dl snd_maestro3_load="YES" .Pp to the file .Pa /boot/loader.conf . .Sh HARDWARE The .Nm driver supports the following audio devices: .Pp .Bl -bullet -compact .It ESS Technology Allegro-1 .It ESS Technology Maestro3 .El .Sh DIAGNOSTICS The hardware volume control buttons can be connected to two different pin -sets(GPIO or GD) on the chip, depending on the manufacturer. +sets (GPIO or GD) on the chip, depending on the manufacturer. The driver has no way of determining this configuration, so a hint may be used to override the default guess. The default setting for hardware volume control assumes that GD pins are wired to control the hardware volume. For systems that have the GPIO pins wired to the hardware volume control buttons, add the line .Dq Li hint.pcm.0.hwvol_config="0" to the file .Pa /boot/device.hints to override the default setting. .Sh SEE ALSO .Xr sound 4 , .Xr loader.conf 5 .Sh HISTORY The .Nm driver first appeared in .Fx 4.3 . .Sh AUTHORS .An Scott Long Aq scottl@FreeBSD.org .An Darrel Anderson Aq anderson@cs.duke.edu Index: head/share/man/man4/unix.4 =================================================================== --- head/share/man/man4/unix.4 (revision 147397) +++ head/share/man/man4/unix.4 (revision 147398) @@ -1,259 +1,275 @@ .\" Copyright (c) 1991, 1993 .\" The Regents of the University of California. 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. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. .\" .\" @(#)unix.4 8.1 (Berkeley) 6/9/93 .\" $FreeBSD$ .\" .Dd July 15, 2001 .Dt UNIX 4 .Os .Sh NAME .Nm unix .Nd UNIX-domain protocol family .Sh SYNOPSIS .In sys/types.h .In sys/un.h .Sh DESCRIPTION The .Ux Ns -domain protocol family is a collection of protocols that provides local (on-machine) interprocess communication through the normal .Xr socket 2 mechanisms. The .Ux Ns -domain family supports the .Dv SOCK_STREAM and .Dv SOCK_DGRAM socket types and uses file system pathnames for addressing. .Sh ADDRESSING .Ux Ns -domain addresses are variable-length file system pathnames of at most 104 characters. The include file .In sys/un.h defines this address: .Bd -literal -offset indent struct sockaddr_un { u_char sun_len; u_char sun_family; char sun_path[104]; }; .Ed .Pp Binding a name to a .Ux Ns -domain socket with .Xr bind 2 causes a socket file to be created in the file system. This file is .Em not removed when the socket is closed \(em .Xr unlink 2 must be used to remove the file. .Pp The length of .Ux Ns -domain address, required by .Xr bind 2 and .Xr connect 2 , can be calculated by the macro .Fn SUN_LEN defined in .In sys/un.h . The -.Ar sun_path -field must be terminated by a NUL character to be used with +.Va sun_path +field must be terminated by a +.Dv NUL +character to be used with .Fn SUN_LEN , -but the terminating NUL is +but the terminating +.Dv NUL +is .Em not part of the address. .Pp The .Ux Ns -domain protocol family does not support broadcast addressing or any form of .Dq wildcard matching on incoming messages. All addresses are absolute- or relative-pathnames of other .Ux Ns -domain sockets. Normal file system access-control mechanisms are also applied when referencing pathnames; e.g., the destination of a .Xr connect 2 or .Xr sendto 2 must be writable. .Sh PROTOCOLS The .Ux Ns -domain protocol family is comprised of simple transport protocols that support the .Dv SOCK_STREAM and .Dv SOCK_DGRAM abstractions. .Dv SOCK_STREAM sockets also support the communication of .Ux file descriptors through the use of the .Va msg_control field in the .Fa msg argument to .Xr sendmsg 2 and .Xr recvmsg 2 . .Pp Any valid descriptor may be sent in a message. The file descriptor(s) to be passed are described using a .Vt "struct cmsghdr" that is defined in the include file .In sys/socket.h . The type of the message is .Dv SCM_RIGHTS , and the data portion of the messages is an array of integers representing the file descriptors to be passed. The number of descriptors being passed is defined by the length field of the message; the length field is the sum of the size of the header plus the size of the array of file descriptors. .Pp The received descriptor is a .Em duplicate of the sender's descriptor, as if it were created with a call to .Xr dup 2 . Per-process descriptor flags, set with .Xr fcntl 2 , are .Em not passed to a receiver. Descriptors that are awaiting delivery, or that are purposely not received, are automatically closed by the system when the destination socket is closed. .Pp The effective credentials (i.e., the user ID and group list) of a peer on a .Dv SOCK_STREAM socket may be obtained using the .Dv LOCAL_PEERCRED socket option. This may be used by a server to obtain and verify the credentials of its client, and vice versa by the client to verify the credentials of the server. These will arrive in the form of a filled in .Vt "struct xucred" (defined in .In sys/ucred.h ) . The credentials presented to the server (the .Xr listen 2 caller) are those of the client when it called .Xr connect 2 ; the credentials presented to the client (the .Xr connect 2 caller) are those of the server when it called .Xr listen 2 . This mechanism is reliable; there is no way for either party to influence the credentials presented to its peer except by calling the appropriate system call (e.g., .Xr connect 2 or .Xr listen 2 ) under different effective credentials. .Pp - .Tn UNIX domain sockets support a number of socket options which can be set with .Xr setsockopt 2 and tested with .Xr getsockopt 2 : .Bl -tag -width ".Dv LOCAL_CONNWAIT" .It Dv LOCAL_CREDS This option may be enabled on a .Dv SOCK_DGRAM or a .Dv SOCK_STREAM -socket. This option provides a mechanism for the receiver to +socket. +This option provides a mechanism for the receiver to receive the credentials of the process as a .Xr recvmsg 2 -control message. The msg_control field in the msghdr structure points -to a buffer that contains a cmsghdr structure followed by a variable -length sockcred structure, defined in -.Pa \*[Lt]sys/socket.h\*[Gt] +control message. +The +.Va msg_control +field in the +.Vt msghdr +structure points to a buffer that contains a +.Vt cmsghdr +structure followed by a variable length +.Vt sockcred +structure, defined in +.In sys/socket.h as follows: .Bd -literal struct sockcred { id_t sc_uid; /* real user id */ uid_t sc_euid; /* effective user id */ gid_t sc_gid; /* real group id */ gid_t sc_egid; /* effective group id */ int sc_ngroups; /* number of supplemental groups */ gid_t sc_groups[1]; /* variable length */ }; .Ed .Pp The .Fn SOCKCREDSIZE -macro computes the size of the sockcred structure for a specified number +macro computes the size of the +.Vt sockcred +structure for a specified number of groups. -The cmsghdr fields have the following values: +The +.Vt cmsghdr +fields have the following values: .Bd -literal cmsg_len = sizeof(struct cmsghdr) + SOCKCREDSIZE(ngroups) cmsg_level = SOL_SOCKET cmsg_type = SCM_CREDS .Ed .It Dv LOCAL_CONNWAIT -Used with +Used with .Dv SOCK_STREAM sockets, this option causes the .Xr connect 2 function to block until .Xr accept 2 has been called on the listening socket. +.El .Sh SEE ALSO .Xr socket 2 , .Xr intro 4 .Rs .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" .%B PS1 .%N 7 .Re .Rs .%T "An Advanced 4.3 BSD Interprocess Communication Tutorial" .%B PS1 .%N 8 .Re Index: head/share/man/man4/witness.4 =================================================================== --- head/share/man/man4/witness.4 (revision 147397) +++ head/share/man/man4/witness.4 (revision 147398) @@ -1,139 +1,140 @@ .\" Copyright (c) 2001 John H. Baldwin .\" 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 February 18, 2001 .Dt WITNESS 4 .Os .Sh NAME .Nm witness .Nd lock validation facility .Sh SYNOPSIS .Cd options WITNESS .Cd options WITNESS_KDB .Cd options WITNESS_SKIPSPIN .Sh DESCRIPTION The .Nm module keeps track of the locks acquired and released by each thread. It also keeps track of the order in which locks are acquired with respect to each other. Each time a lock is acquired, .Nm uses these two lists to verify that a lock is not being acquired in the wrong order. If a lock order violation is detected, then a message is output to the kernel console detailing the locks involved and the locations in question. Witness can also be configured to drop into the kernel debugger when an order violation occurs. .Pp The .Nm code also checks various other conditions such as verifying that one does not recurse on a non-recursive lock. For sleep locks, .Nm verifies that a new process would not be switched to when a lock is released or a lock is blocked on during an acquire while any spin locks are held. If any of these checks fail, then the kernel will panic. .Pp The flag that controls whether or not the kernel debugger is entered when a lock order violation is detected can be set in a variety of ways. By default, the flag is off, but if the .Dv WITNESS_KDB kernel option is specified, then the flag will default to on. It can also be set from the .Xr loader 8 via the .Va debug.witness.kdb environment variable or after the kernel has booted via the .Va debug.witness.kdb sysctl. If the flag is set to zero, then the debugger will not be entered. If the flag is non-zero, then the debugger will be entered. .Pp The .Nm code can also be configured to skip all checks on spin mutexes. By default, this flag defaults to off, but it can be turned on by specifying the .Dv WITNESS_SKIPSPIN kernel option. The flag can also be set via the .Xr loader 8 environment variable .Va debug.witness.skipspin . If the variable is set to a non-zero value, then spin mutexes are skipped. Once the kernel has booted, the status of this flag can be examined but not set via the read-only sysctl .Va debug.witness.skipspin . .Pp The sysctl .Va debug.witness.watch -specifies the level of witness involvment in the system. A value of -1 specifies that witness is enabled. A value of 0 specifies that -witness is disabled. This sysctl can be written to in order to +specifies the level of witness involvment in the system. +A value of 1 specifies that witness is enabled. +A value of 0 specifies that witness is disabled. +This sysctl can be written to in order to disable witness, however it may not be used to enable witness. .Va debug.witness.watch can be set via .Xr loader 8 . .Pp The .Nm code also provides two extra .Xr ddb 4 commands if both .Nm and .Xr ddb 4 are compiled into the kernel: .Bl -ohang .It Ic show locks Outputs the list of locks held by the current thread to the kernel console along with the filename and line number at which each lock was last acquired by this thread. .It Ic show witness Dump the current order list to the kernel console. The code first displays the lock order tree for all of the sleep locks. Then it displays the lock order tree for all of the spin locks. Finally, it displays a list of locks that have not yet been acquired. .El .Sh SEE ALSO .Xr ddb 4 , .Xr mutex 9 .Sh HISTORY The .Nm code first appeared in .Bsx 5.0 and was imported from there into .Fx 5.0 . .Sh BUGS The .Nm code currently does not handle recursion of shared .Xr sx 9 locks properly. Index: head/share/man/man5/autofs.5 =================================================================== --- head/share/man/man5/autofs.5 (revision 147397) +++ head/share/man/man5/autofs.5 (revision 147398) @@ -1,58 +1,58 @@ .\" Copyright (c) 2004 Alfred Perlstein .\" 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. .\" .\" $Id: autofs.5,v 1.1 2004/08/31 16:05:39 bright Exp $ .\" $FreeBSD$ .Dd August 30, 2004 .Dt AUTOFS 5 .Os .Sh NAME .Nm autofs .Nd auto file system .Sh SYNOPSIS .Bd -literal autofs /auto autofs rw 0 0 .Ed .Sh DESCRIPTION The auto file system, or .Nm , provides a method to dynamically graft mountpoints into the file system namespace. .Sh SEE ALSO +.Xr libautofs 3 , .Xr mount_autofs 8 -.Xr libautofs 3 .Sh HISTORY The .Nm file system first appeared in .Fx 6.0 . The .Nm manual page first appeared in .Fx 6.0 . .Sh AUTHORS The .Nm manual page was written by .An Alfred Perlstein Aq alfred@FreeBSD.org . Index: head/share/man/man5/elf.5 =================================================================== --- head/share/man/man5/elf.5 (revision 147397) +++ head/share/man/man5/elf.5 (revision 147398) @@ -1,1300 +1,1300 @@ .\" Copyright (c) 1999 Jeroen Ruigrok van der Werven .\" 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 July 31, 1999 .Dt ELF 5 .Os .Sh NAME .Nm elf .Nd format of ELF executable binary files .Sh SYNOPSIS .In elf.h .Sh DESCRIPTION The header file .In elf.h defines the format of ELF executable binary files. Amongst these files are normal executable files, relocatable object files, core files and shared libraries. .Pp An executable file using the ELF file format consists of an ELF header, followed by a program header table or a section header table, or both. The ELF header is always at offset zero of the file. The program header table and the section header table's offset in the file are defined in the ELF header. The two tables describe the rest of the particularities of the file. .Pp Applications which wish to process ELF binary files for their native architecture only should include .In elf.h in their source code. These applications should need to refer to all the types and structures by their generic names .Dq Elf_xxx and to the macros by .Dq ELF_xxx . Applications written this way can be compiled on any architecture, regardless whether the host is 32-bit or 64-bit. .Pp Should an application need to process ELF files of an unknown architecture then the application needs to include both .In sys/elf32.h and .In sys/elf64.h instead of .In elf.h . Furthermore, all types and structures need to be identified by either .Dq Elf32_xxx or .Dq Elf64_xxx . The macros need to be identified by .Dq ELF32_xxx or .Dq ELF64_xxx . .Pp Whatever the system's architecture is, it will always include .In sys/elf_common.h as well as .In sys/elf_generic.h . .Pp These header files describe the above mentioned headers as C structures and also include structures for dynamic sections, relocation sections and symbol tables. .Pp The following types are being used for 32-bit architectures: .Bd -literal -offset indent Elf32_Addr Unsigned program address Elf32_Half Unsigned halfword field Elf32_Off Unsigned file offset Elf32_Sword Signed large integer Elf32_Word Field or unsigned large integer Elf32_Size Unsigned object size .Ed .Pp For 64-bit architectures we have the following types: .Bd -literal -offset indent Elf64_Addr Unsigned program address Elf64_Half Unsigned halfword field Elf64_Off Unsigned file offset Elf64_Sword Signed large integer Elf64_Word Field or unsigned large integer Elf64_Size Unsigned object size Elf64_Quarter Unsigned quarterword field .Ed .Pp All data structures that the file format defines follow the .Dq natural size and alignment guidelines for the relevant class. If necessary, data structures contain explicit padding to ensure 4-byte alignment for 4-byte objects, to force structure sizes to a multiple of 4, etc. .Pp The ELF header is described by the type Elf32_Ehdr or Elf64_Ehdr: .Bd -literal -offset indent typedef struct { unsigned char e_ident[EI_NIDENT]; Elf32_Half e_type; Elf32_Half e_machine; Elf32_Word e_version; Elf32_Addr e_entry; Elf32_Off e_phoff; Elf32_Off e_shoff; Elf32_Word e_flags; Elf32_Half e_ehsize; Elf32_Half e_phentsize; Elf32_Half e_phnum; Elf32_Half e_shentsize; Elf32_Half e_shnum; Elf32_Half e_shstrndx; } Elf32_Ehdr; .Ed .Pp .Bd -literal -offset indent typedef struct { unsigned char e_ident[EI_NIDENT]; Elf64_Quarter e_type; Elf64_Quarter e_machine; Elf64_Half e_version; Elf64_Addr e_entry; Elf64_Off e_phoff; Elf64_Off e_shoff; Elf64_Half e_flags; Elf64_Quarter e_ehsize; Elf64_Quarter e_phentsize; Elf64_Quarter e_phnum; Elf64_Quarter e_shentsize; Elf64_Quarter e_shnum; Elf64_Quarter e_shstrndx; } Elf64_Ehdr; .Ed .Pp The fields have the following meanings: .Pp .Bl -tag -width "e_phentsize" -compact -offset indent .It Dv e_ident This array of bytes specifies to interpret the file, independent of the processor or the file's remaining contents. Within this array everything is named by macros, which start with the prefix .Sy EI_ and may contain values which start with the prefix .Sy ELF . The following macros are defined: .Pp .Bl -tag -width "EI_ABIVERSION" -compact .It Dv EI_MAG0 The first byte of the magic number. It must be filled with .Sy ELFMAG0 . .It Dv EI_MAG1 The second byte of the magic number. It must be filled with .Sy ELFMAG1 . .It Dv EI_MAG2 The third byte of the magic number. It must be filled with .Sy ELFMAG2 . .It Dv EI_MAG3 The fourth byte of the magic number. It must be filled with .Sy ELFMAG3 . .It Dv EI_CLASS The fifth byte identifies the architecture for this binary: .Pp .Bl -tag -width "ELFCLASSNONE" -compact .It Dv ELFCLASSNONE This class is invalid. .It Dv ELFCLASS32 This defines the 32-bit architecture. It supports machines with files and virtual address spaces up to 4 Gigabytes. .It Dv ELFCLASS64 This defines the 64-bit architecture. .El .It Dv EI_DATA The sixth byte specifies the data encoding of the processor-specific data in the file. Currently these encodings are supported: .Pp .Bl -tag -width "ELFDATA2LSB" -compact .It Dv ELFDATANONE Unknown data format. .It Dv ELFDATA2LSB Two's complement, little-endian. .It Dv ELFDATA2MSB Two's complement, big-endian. .El .It Dv EI_VERSION The version number of the ELF specification: .Pp .Bl -tag -width "EV_CURRENT" -compact .It Dv EV_NONE Invalid version. .It Dv EV_CURRENT Current version. .El .It Dv EI_OSABI This byte identifies the operating system and ABI to which the object is targeted. Some fields in other ELF structures have flags and values that have platform specific meanings; the interpretation of those fields is determined by the value of this byte. The following values are currently defined: .Pp .Bl -tag -width "ELFOSABI_STANDALONE" -compact .It Dv ELFOSABI_SYSV UNIX System V ABI. .It Dv ELFOSABI_HPUX HP-UX operating system ABI. .It Dv ELFOSABI_NETBSD .Nx operating system ABI. .It Dv ELFOSABI_LINUX GNU/Linux operating system ABI. .It Dv ELFOSABI_HURD GNU/Hurd operating system ABI. .It Dv ELFOSABI_86OPEN 86Open Common IA32 ABI. .It Dv ELFOSABI_SOLARIS Solaris operating system ABI. .It Dv ELFOSABI_MONTEREY Monterey project ABI. .It Dv ELFOSABI_IRIX IRIX operating system ABI. .It Dv ELFOSABI_FREEBSD .Fx operating system ABI. .It Dv ELFOSABI_TRU64 TRU64 UNIX operating system ABI. .It Dv ELFOSABI_ARM ARM architecture ABI. .It Dv ELFOSABI_STANDALONE Standalone (embedded) ABI. .El .It Dv EI_ABIVERSION This byte identifies the version of the ABI to which the object is targeted. This field is used to distinguish among incompatible versions of an ABI. The interpretation of this version number is dependent on the ABI identified by the EI_OSABI field. Applications conforming to this specification use the value 0. .It Dv EI_PAD Start of padding. These bytes are reserved and set to zero. Programs which read them should ignore them. The value for EI_PAD will change in the future if currently unused bytes are given meanings. .It Dv EI_BRAND Start of architecture identification. .It Dv EI_NIDENT The size of the e_ident array. .El .Pp .It Dv e_type This member of the structure identifies the object file type: .Pp .Bl -tag -width "ET_NONE" -compact .It Dv ET_NONE An unknown type. .It Dv ET_REL A relocatable file. .It Dv ET_EXEC An executable file. .It Dv ET_DYN A shared object. .It Dv ET_CORE A core file. .El .Pp .It Dv e_machine This member specifies the required architecture for an individual file: .Pp .Bl -tag -width "EM_MIPS_RS4_BE" -compact .It Dv EM_NONE An unknown machine. .It Dv EM_M32 AT&T WE 32100. .It Dv EM_SPARC Sun Microsystems SPARC. .It Dv EM_386 Intel 80386. .It Dv EM_68K Motorola 68000. .It Dv EM_88K Motorola 88000. .It Dv EM_486 Intel 80486. .It Dv EM_860 Intel 80860. .It Dv EM_MIPS MIPS RS3000 (big-endian only). .It Dv EM_MIPS_RS4_BE MIPS RS4000 (big-endian only). .It Dv EM_SPARC64 SPARC v9 64-bit unofficial. .It Dv EM_PARISC HPPA. .It Dv EM_PPC PowerPC. .It Dv EM_ALPHA Compaq [DEC] Alpha. .El .Pp .It Dv e_version This member identifies the file version: .Pp .Bl -tag -width "EV_CURRENT" -compact .It Dv EV_NONE Invalid version .It Dv EV_CURRENT Current version .El .It Dv e_entry This member gives the virtual address to which the system first transfers control, thus starting the process. If the file has no associated entry point, this member holds zero. .It Dv e_phoff This member holds the program header table's file offset in bytes. If the file has no program header table, this member holds zero. .It Dv e_shoff This member holds the section header table's file offset in bytes. If the file has no section header table this member holds zero. .It Dv e_flags This member holds processor-specific flags associated with the file. Flag names take the form EF_`machine_flag'. Currently no flags have been defined. .It Dv e_ehsize This member holds the ELF header's size in bytes. .It Dv e_phentsize This member holds the size in bytes of one entry in the file's program header table; all entries are the same size. .It Dv e_phnum This member holds the number of entries in the program header table. Thus the product of .Sy e_phentsize and .Sy e_phnum gives the table's size in bytes. If a file has no program header, .Sy e_phnum holds the value zero. .It Dv e_shentsize This member holds a sections header's size in bytes. A section header is one entry in the section header table; all entries are the same size. .It Dv e_shnum This member holds the number of entries in the section header table. Thus the product of .Sy e_shentsize and .Sy e_shnum gives the section header table's size in bytes. If a file has no section header table, .Sy e_shnum holds the value of zero. .It Dv e_shstrndx This member holds the section header table index of the entry associated with the section name string table. If the file has no section name string table, this member holds the value .Sy SHN_UNDEF . .El .Pp An executable or shared object file's program header table is an array of structures, each describing a segment or other information the system needs to prepare the program for execution. An object file .Em segment contains one or more .Em sections . Program headers are meaningful only for executable and shared object files. A file specifies its own program header size with the ELF header's .Sy e_phentsize and .Sy e_phnum members. As with the Elf executable header, the program header also has different versions depending on the architecture: .Pp .Bd -literal -offset indent typedef struct { Elf32_Word p_type; Elf32_Off p_offset; Elf32_Addr p_vaddr; Elf32_Addr p_paddr; Elf32_Size p_filesz; Elf32_Size p_memsz; Elf32_Word p_flags; Elf32_Size p_align; } Elf32_Phdr; .Ed .Pp .Bd -literal -offset indent typedef struct { Elf64_Half p_type; Elf64_Half p_flags; Elf64_Off p_offset; Elf64_Addr p_vaddr; Elf64_Addr p_paddr; Elf64_Size p_filesz; Elf64_Size p_memsz; Elf64_Size p_align; } Elf64_Phdr; .Ed .Pp The main difference between the 32-bit and the 64-bit program header lies only in the location of a .Sy p_flags member in the total struct. .Pp .Bl -tag -width "p_offset" -compact -offset indent .It Dv p_type This member of the Phdr struct tells what kind of segment this array element describes or how to interpret the array element's information. .Bl -tag -width "PT_DYNAMIC" -compact .Pp .It Dv PT_NULL The array element is unused and the other members' values are undefined. This lets the program header have ignored entries. .It Dv PT_LOAD The array element specifies a loadable segment, described by .Sy p_filesz and .Sy p_memsz . The bytes from the file are mapped to the beginning of the memory segment. If the segment's memory size .Pq Sy p_memsz is larger than the file size .Pq Sy p_filesz , the .Dq extra bytes are defined to hold the value 0 and to follow the segment's initialized area. The file size may not be larger than the memory size. Loadable segment entries in the program header table appear in ascending order, sorted on the .Sy p_vaddr member. .It Dv PT_DYNAMIC The array element specifies dynamic linking information. .It Dv PT_INTERP The array element specifies the location and size of a null-terminated path name to invoke as an interpreter. This segment type is meaningful only for executable files (though it may occur for shared objects). However it may not occur more than once in a file. If it is present it must precede any loadable segment entry. .It Dv PT_NOTE The array element specifies the location and size for auxiliary information. .It Dv PT_SHLIB This segment type is reserved but has unspecified semantics. Programs that contain an array element of this type do not conform to the ABI. .It Dv PT_PHDR The array element, if present, specifies the location and size of the program header table itself, both in the file and in the memory image of the program. This segment type may not occur more than once in a file. Moreover, it may only occur if the program header table is part of the memory image of the program. If it is present it must precede any loadable segment entry. .It Dv PT_LOPROC This value up to and including .Sy PT_HIPROC are reserved for processor-specific semantics. .It Dv PT_HIPROC This value down to and including .Sy PT_LOPROC are reserved for processor-specific semantics. .El .Pp .It Dv p_offset This member holds the offset from the beginning of the file at which the first byte of the segment resides. .It Dv p_vaddr This member holds the virtual address at which the first byte of the segment resides in memory. .It Dv p_paddr On systems for which physical addressing is relevant, this member is reserved for the segment's physical address. Under .Bx this member is not used and must be zero. .It Dv p_filesz This member holds the number of bytes in the file image of the segment. It may be zero. .It Dv p_memsz This member holds the number of bytes in the memory image of the segment. It may be zero. .It Dv p_flags This member holds flags relevant to the segment: .Pp .Bl -tag -width "PF_X" -compact .It Dv PF_X An executable segment. .It Dv PF_W A writable segment. .It Dv PF_R A readable segment. .El .Pp A text segment commonly has the flags .Sy PF_X and .Sy PF_R . A data segment commonly has .Sy PF_X , .Sy PF_W and .Sy PF_R . .It Dv p_align This member holds the value to which the segments are aligned in memory and in the file. Loadable process segments must have congruent values for .Sy p_vaddr and .Sy p_offset , modulo the page size. Values of zero and one mean no alignment is required. Otherwise, .Sy p_align should be a positive, integral power of two, and .Sy p_vaddr should equal .Sy p_offset , modulo .Sy p_align . .El .Pp An file's section header table lets one locate all the file's sections. The section header table is an array of Elf32_Shdr or Elf64_Shdr structures. The ELF header's .Sy e_shoff member gives the byte offset from the beginning of the file to the section header table. .Sy e_shnum holds the number of entries the section header table contains. .Sy e_shentsize holds the size in bytes of each entry. .Pp A section header table index is a subscript into this array. Some section header table indices are reserved. An object file does not have sections for these special indices: .Pp .Bl -tag -width "SHN_LORESERVE" -compact .It Dv SHN_UNDEF This value marks an undefined, missing, irrelevant, or otherwise meaningless section reference. For example, a symbol .Dq defined relative to section number .Sy SHN_UNDEF is an undefined symbol. .It Dv SHN_LORESERVE This value specifies the lower bound of the range of reserved indices. .It Dv SHN_LOPROC This value up to and including .Sy SHN_HIPROC are reserved for processor-specific semantics. .It Dv SHN_HIPROC This value down to and including .Sy SHN_LOPROC are reserved for processor-specific semantics. .It Dv SHN_ABS This value specifies absolute values for the corresponding reference. For example, symbols defined relative to section number .Sy SHN_ABS have absolute values and are not affected by relocation. .It Dv SHN_COMMON Symbols defined relative to this section are common symbols, such as FORTRAN COMMON or unallocated C external variables. .It Dv SHN_HIRESERVE This value specifies the upper bound of the range of reserved indices. The system reserves indices between .Sy SHN_LORESERVE and .Sy SHN_HIRESERVE , inclusive. The section header table does not contain entries for the reserved indices. .El .Pp The section header has the following structure: .Bd -literal -offset indent typedef struct { Elf32_Word sh_name; Elf32_Word sh_type; Elf32_Word sh_flags; Elf32_Addr sh_addr; Elf32_Off sh_offset; Elf32_Size sh_size; Elf32_Word sh_link; Elf32_Word sh_info; Elf32_Size sh_addralign; Elf32_Size sh_entsize; } Elf32_Shdr; .Ed .Pp .Bd -literal -offset indent typedef struct { Elf64_Half sh_name; Elf64_Half sh_type; Elf64_Size sh_flags; Elf64_Addr sh_addr; Elf64_Off sh_offset; Elf64_Size sh_size; Elf64_Half sh_link; Elf64_Half sh_info; Elf64_Size sh_addralign; Elf64_Size sh_entsize; } Elf64_Shdr; .Ed .Pp .Bl -tag -width "sh_addralign" -compact .It Dv sh_name This member specifies the name of the section. Its value is an index into the section header string table section, giving the location of a null-terminated string. .It Dv sh_type This member categorizes the section's contents and semantics. .Pp .Bl -tag -width "SHT_PROGBITS" -compact .It Dv SHT_NULL This value marks the section header as inactive. It does not have an associated section. Other members of the section header have undefined values. .It Dv SHT_PROGBITS The section holds information defined by the program, whose format and meaning are determined solely by the program. .It Dv SHT_SYMTAB This section holds a symbol table. Typically, .Sy SHT_SYMTAB provides symbols for link editing, though it may also be used for dynamic linking. As a complete symbol table, it may contain many symbols unnecessary for dynamic linking. An object file can also contain a .Sy SHN_DYNSYM section. .It Dv SHT_STRTAB This section holds a string table. An object file may have multiple string table sections. .It Dv SHT_RELA This section holds relocation entries with explicit addends, such as type .Sy Elf32_Rela for the 32-bit class of object files. An object may have multiple relocation sections. .It Dv SHT_HASH This section holds a symbol hash table. All object participating in dynamic linking must contain a symbol hash table. An object file may have only one hash table. .It Dv SHT_DYNAMIC This section holds information for dynamic linking. An object file may have only one dynamic section. .It Dv SHT_NOTE This section holds information that marks the file in some way. .It Dv SHT_NOBITS A section of this type occupies no space in the file but otherwise resembles .Sy SHN_PROGBITS . Although this section contains no bytes, the .Sy sh_offset member contains the conceptual file offset. .It Dv SHT_REL This section holds relocation offsets without explicit addends, such as type .Sy Elf32_Rel for the 32-bit class of object files. An object file may have multiple relocation sections. .It Dv SHT_SHLIB This section is reserved but has unspecified semantics. .It Dv SHT_DYNSYM This section holds a minimal set of dynamic linking symbols. An object file can also contain a .Sy SHN_SYMTAB section. .It Dv SHT_LOPROC This value up to and including .Sy SHT_HIPROC are reserved for processor-specific semantics. .It Dv SHT_HIPROC This value down to and including .Sy SHT_LOPROC are reserved for processor-specific semantics. .It Dv SHT_LOUSER This value specifies the lower bound of the range of indices reserved for application programs. .It Dv SHT_HIUSER This value specifies the upper bound of the range of indices reserved for application programs. Section types between .Sy SHT_LOUSER and .Sy SHT_HIUSER may be used by the application, without conflicting with current or future system-defined section types. .El .Pp .It Dv sh_flags Sections support one-bit flags that describe miscellaneous attributes. If a flag bit is set in .Sy sh_flags , the attribute is .Dq on for the section. Otherwise, the attribute is .Dq off or does not apply. Undefined attributes are set to zero. .Pp .Bl -tag -width "SHF_EXECINSTR" -compact .It Dv SHF_WRITE This section contains data that should be writable during process execution. .It Dv SHF_ALLOC The section occupies memory during process execution. Some control sections do not reside in the memory image of an object file. This attribute is off for those sections. .It Dv SHF_EXECINSTR The section contains executable machine instructions. .It Dv SHF_MASKPROC All bits included in this mask are reserved for processor-specific semantics. .El .Pp .It Dv sh_addr If the section will appear in the memory image of a process, this member holds the address at which the section's first byte should reside. Otherwise, the member contains zero. .It Dv sh_offset This member's value holds the byte offset from the beginning of the file to the first byte in the section. One section type, .Sy SHT_NOBITS , occupies no space in the file, and its .Sy sh_offset member locates the conceptual placement in the file. .It Dv sh_size This member holds the section's size in bytes. Unless the section type is .Sy SHT_NOBITS , the section occupies .Sy sh_size bytes in the file. A section of type .Sy SHT_NOBITS may have a non-zero size, but it occupies no space in the file. .It Dv sh_link This member holds a section header table index link, whose interpretation depends on the section type. .It Dv sh_info This member holds extra information, whose interpretation depends on the section type. .It Dv sh_addralign Some sections have address alignment constraints. If a section holds a doubleword, the system must ensure doubleword alignment for the entire section. That is, the value of .Sy sh_addr must be congruent to zero, modulo the value of .Sy sh_addralign . Only zero and positive integral powers of two are allowed. Values of zero or one mean the section has no alignment constraints. .It Dv sh_entsize Some sections hold a table of fixed-sized entries, such as a symbol table. For such a section, this member gives the size in bytes for each entry. This member contains zero if the section does not hold a table of fixed-size entries. .El .Pp Various sections hold program and control information: .Bl -tag -width ".shstrtab" -compact .It .bss -Block Started by Symbol - +(Block Started by Symbol) This section holds uninitialized data that contributes to the program's memory image. By definition, the system initializes the data with zeros when the program begins to run. This section is of type .Sy SHT_NOBITS . The attributes types are .Sy SHF_ALLOC and .Sy SHF_WRITE . .It .comment This section holds version control information. This section is of type .Sy SHT_PROGBITS . No attribute types are used. .It .data This section holds initialized data that contribute to the program's memory image. This section is of type .Sy SHT_PROGBITS . The attribute types are .Sy SHF_ALLOC and .Sy SHF_WRITE . .It .data1 This section holds initialized data that contribute to the program's memory image. This section is of type .Sy SHT_PROGBITS . The attribute types are .Sy SHF_ALLOC and .Sy SHF_WRITE . .It .debug This section holds information for symbolic debugging. The contents are unspecified. This section is of type .Sy SHT_PROGBITS . No attribute types are used. .It .dynamic This section holds dynamic linking information. The section's attributes will include the .Sy SHF_ALLOC bit. Whether the .Sy SHF_WRITE bit is set is processor-specific. This section is of type .Sy SHT_DYNAMIC . See the attributes above. .It .dynstr This section holds strings needed for dynamic linking, most commonly the strings that represent the names associated with symbol table entries. This section is of type .Sy SHT_STRTAB . The attribute type used is .Sy SHF_ALLOC . .It .dynsym This section holds the dynamic linking symbol table. This section is of type .Sy SHT_DYNSYM . The attribute used is .Sy SHF_ALLOC . .It .fini This section holds executable instructions that contribute to the process termination code. When a program exits normally the system arranges to execute the code in this section. This section is of type .Sy SHT_PROGBITS . The attributes used are .Sy SHF_ALLOC and .Sy SHF_EXECINSTR . .It .got This section holds the global offset table. This section is of type .Sy SHT_PROGBITS . The attributes are processor-specific. .It .hash This section holds a symbol hash table. This section is of type .Sy SHT_HASH . The attribute used is .Sy SHF_ALLOC . .It .init This section holds executable instructions that contribute to the process initialization code. When a program starts to run the system arranges to execute the code in this section before calling the main program entry point. This section is of type .Sy SHT_PROGBITS . The attributes used are .Sy SHF_ALLOC and .Sy SHF_EXECINSTR . .It .interp This section holds the pathname of a program interpreter. If the file has a loadable segment that includes the section, the section's attributes will include the .Sy SHF_ALLOC bit. Otherwise, that bit will be off. This section is of type .Sy SHT_PROGBITS . .It .line This section holds line number information for symbolic debugging, which describes the correspondence between the program source and the machine code. The contents are unspecified. This section is of type .Sy SHT_PROGBITS . No attribute types are used. .It .note This section holds information in the .Dq Note Section format described below. This section is of type .Sy SHT_NOTE . No attribute types are used. .It .plt This section holds the procedure linkage table. This section is of type .Sy SHT_PROGBITS . The attributes are processor-specific. .It .relNAME This section holds relocation information as described below. If the file has a loadable segment that includes relocation, the section's attributes will include the .Sy SHF_ALLOC bit. Otherwise the bit will be off. By convention, .Dq NAME is supplied by the section to which the relocations apply. Thus a relocation section for .Sy .text normally would have the name .Sy .rel.text . This section is of type .Sy SHT_REL . .It .relaNAME This section holds relocation information as described below. If the file has a loadable segment that includes relocation, the section's attributes will include the .Sy SHF_ALLOC bit. Otherwise the bit will be off. By convention, .Dq NAME is supplied by the section to which the relocations apply. Thus a relocation section for .Sy .text normally would have the name .Sy .rela.text . This section is of type .Sy SHT_RELA . .It .rodata This section holds read-only data that typically contributes to a non-writable segment in the process image. This section is of type .Sy SHT_PROGBITS . The attribute used is .Sy SHF_ALLOC . .It .rodata1 This section hold read-only data that typically contributes to a non-writable segment in the process image. This section is of type .Sy SHT_PROGBITS . The attribute used is .Sy SHF_ALLOC . .It .shstrtab This section holds section names. This section is of type .Sy SHT_STRTAB . No attribute types are used. .It .strtab This section holds strings, most commonly the strings that represent the names associated with symbol table entries. If the file has a loadable segment that includes the symbol string table, the section's attributes will include the .Sy SHF_ALLOC bit. Otherwise the bit will be off. This section is of type .Sy SHT_STRTAB . .It .symtab This section holds a symbol table. If the file has a loadable segment that includes the symbol table, the section's attributes will include the .Sy SHF_ALLOC bit. Otherwise the bit will be off. This section is of type .Sy SHT_SYMTAB . .It .text This section holds the .Dq text , or executable instructions, of a program. This section is of type .Sy SHT_PROGBITS . The attributes used are .Sy SHF_ALLOC and .Sy SHF_EXECINSTR . .It .jcr This section holds information about Java classes that must be registered. .It .eh_frame This section holds information used for C++ exception-handling. .El .Pp String table sections hold null-terminated character sequences, commonly called strings. The object file uses these strings to represent symbol and section names. One references a string as an index into the string table section. The first byte, which is index zero, is defined to hold a null character. Similarly, a string table's last byte is defined to hold a null character, ensuring null termination for all strings. .Pp An object file's symbol table holds information needed to locate and relocate a program's symbolic definitions and references. A symbol table index is a subscript into this array. .Pp .Bd -literal -offset indent typedef struct { Elf32_Word st_name; Elf32_Addr st_value; Elf32_Size st_size; unsigned char st_info; unsigned char st_other; Elf32_Half st_shndx; } Elf32_Sym; .Ed .Pp .Bd -literal -offset indent typedef struct { Elf64_Half st_name; unsigned char st_info; unsigned char st_other; Elf64_Quarter st_shndx; Elf64_Addr st_value; Elf64_Size st_size; } Elf64_Sym; .Ed .Pp .Bl -tag -width "st_value" -compact .It Dv st_name This member holds an index into the object file's symbol string table, which holds character representations of the symbol names. If the value is non-zero, it represents a string table index that gives the symbol name. Otherwise, the symbol table has no name. .It Dv st_value This member gives the value of the associated symbol. .It Dv st_size Many symbols have associated sizes. This member holds zero if the symbol has no size or an unknown size. .It Dv st_info This member specifies the symbol's type and binding attributes: .Pp .Bl -tag -width "STT_SECTION" -compact .It Dv STT_NOTYPE The symbol's type is not defined. .It Dv STT_OBJECT The symbol is associated with a data object. .It Dv STT_FUNC The symbol is associated with a function or other executable code. .It Dv STT_SECTION The symbol is associated with a section. Symbol table entries of this type exist primarily for relocation and normally have .Sy STB_LOCAL bindings. .It Dv STT_FILE By convention the symbol's name gives the name of the source file associated with the object file. A file symbol has .Sy STB_LOCAL bindings, its section index is .Sy SHN_ABS , and it precedes the other .Sy STB_LOCAL symbols of the file, if it is present. .It Dv STT_LOPROC This value up to and including .Sy STT_HIPROC are reserved for processor-specific semantics. .It Dv STT_HIPROC This value down to and including .Sy STT_LOPROC are reserved for processor-specific semantics. .El .Pp .Bl -tag -width "STB_GLOBAL" -compact .It Dv STB_LOCAL Local symbols are not visible outside the object file containing their definition. Local symbols of the same name may exist in multiple file without interfering with each other. .It Dv STB_GLOBAL Global symbols are visible to all object files being combined. One file's definition of a global symbol will satisfy another file's undefined reference to the same symbol. .It Dv STB_WEAK Weak symbols resemble global symbols, but their definitions have lower precedence. .It Dv STB_LOPROC This value up to and including .Sy STB_HIPROC are reserved for processor-specific semantics. .It Dv STB_HIPROC This value down to and including .Sy STB_LOPROC are reserved for processor-specific semantics. .Pp There are macros for packing and unpacking the binding and type fields: .Pp .Bl -tag -width "ELF32_ST_INFO(bind, type)" -compact .It Xo .Fn ELF32_ST_BIND info .Xc or .Fn ELF64_ST_BIND info extract a binding from an st_info value. .It Xo .Fn ELF64_ST_TYPE info .Xc or .Fn ELF32_ST_TYPE info extract a type from an st_info value. .It Xo .Fn ELF32_ST_INFO bind type .Xc or .Fn ELF64_ST_INFO bind type convert a binding and a type into an st_info value. .El .El .Pp .It Dv st_other This member currently holds zero and has no defined meaning. .It Dv st_shndx Every symbol table entry is .Dq defined in relation to some section. This member holds the relevant section header table index. .El .Pp Relocation is the process of connecting symbolic references with symbolic definitions. Relocatable files must have information that describes how to modify their section contents, thus allowing executable and shared object files to hold the right information for a process' program image. Relocation entries are these data. .Pp Relocation structures that do not need an addend: .Pp .Bd -literal -offset indent typedef struct { Elf32_Addr r_offset; Elf32_Word r_info; } Elf32_Rel; .Ed .Bd -literal -offset indent typedef struct { Elf64_Addr r_offset; Elf64_Size r_info; } Elf64_Rel; .Ed .Pp Relocation structures that need an addend: .Pp .Bd -literal -offset indent typedef struct { Elf32_Addr r_offset; Elf32_Word r_info; Elf32_Sword r_addend; } Elf32_Rela; .Ed .Bd -literal -offset indent typedef struct { Elf64_Addr r_offset; Elf64_Size r_info; Elf64_Off r_addend; } Elf64_Rela; .Ed .Pp .Bl -tag -width "r_offset" -compact .It Dv r_offset This member gives the location at which to apply the relocation action. For a relocatable file, the value is the byte offset from the beginning of the section to the storage unit affected by the relocation. For an executable file or shared object, the value is the virtual address of the storage unit affected by the relocation. .It Dv r_info This member gives both the symbol table index with respect to which the relocation must be made and the type of relocation to apply. Relocation types are processor-specific. When the text refers to a relocation entry's relocation type or symbol table index, it means the result of applying .Sy ELF_[32|64]_R_TYPE or .Sy ELF[32|64]_R_SYM , respectively to the entry's .Sy r_info member. .It Dv r_addend This member specifies a constant addend used to compute the value to be stored into the relocatable field. .El .Sh SEE ALSO .Xr as 1 , .Xr gdb 1 , .Xr ld 1 , .Xr objdump 1 , .Xr execve 2 , .Xr core 5 .Rs .%A Hewlett Packard .%B Elf-64 Object File Format .Re .Rs .%A Santa Cruz Operation .%B System V Application Binary Interface .Re .Rs .%A Unix System Laboratories .%T Object Files .%B "Executable and Linking Format (ELF)" .Re .Sh HISTORY The ELF header files made their appearance in .Fx 2.2.6 . ELF in itself first appeared in .At V . The ELF format is an adopted standard. .Sh AUTHORS This manual page was written by .An Jeroen Ruigrok van der Werven .Aq asmodai@FreeBSD.org with inspiration from BSDi's .Bsx .Xr elf 5 manpage. Index: head/share/man/man7/release.7 =================================================================== --- head/share/man/man7/release.7 (revision 147397) +++ head/share/man/man7/release.7 (revision 147398) @@ -1,526 +1,526 @@ .\" Copyright (c) 2002 Murray Stokely .\" 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 ``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 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 September 6, 2004 +.Dd May 17, 2005 .Dt RELEASE 7 .Os .Sh NAME .Nm release .Nd "release building infrastructure" .Sh DESCRIPTION .Fx provides a complete build environment suitable for users to make full releases of the .Fx operating system. All of the tools necessary to build a release are available from the CVS repository in .Pa src/release . A complete release can actually be built with only a single command, including the creation of ISO images suitable for burning to CD-ROM, installation floppies, and an FTP install directory. This command is aptly named .Dq Li "make release" . .Pp Before attempting to build a release, the user is expected to be familiar with the contents of .Xr build 7 , and should have experience upgrading systems from source. The release build process requires that .Pa /usr/obj be populated with the output of a native .Dq Li "make buildworld" compiled from sources matching the currently running kernel. This is necessary so that the object files for a complete system can be installed into a clean .Xr chroot 8 environment. The release procedure also requires that the .Xr md 4 (memory disk) device driver be present in the kernel (either by being compiled in or available as a module). .Pp This document does not cover source code management, quality assurance, or other aspects of the release engineering process. .Sh TARGETS The release makefile .Pq Pa src/release/Makefile is fairly abstruse. Most developers will only be concerned with the .Cm release target. .\" XXX: Some sort of introduction to this list? All the others have one. .Bl -tag -width ".Cm package-split" .It Cm release Uses .Dq Li "make installworld" to install a clean system into a .Xr chroot 8 environment on the file system. Checks out the specified version of the source code and then rebuilds the entire system in the clean environment with .Dq Li "make buildworld" . The detailed steps that follow are then executed to package up the different distributions, build the installation floppy disks, build release documentation, and so on. .Pp This target must be built as root with the .Va kern.securelevel sysctl set to \-1 (the default). .It Cm rerelease Assumes that the output of a release build has been manually modified, and performs the minimal number of steps to rebuild the release using the intermediate output of the previous .Dq Li "make release" . .It Cm floppies Generate a new set of boot and fixit floppies. This will call the .Cm release.4 , .Cm release.8 , .Cm floppies.1 , .Cm floppies.2 , and .Cm floppies.3 targets to re-generate the floppy images of a previous .Dq Li "make release" . This is most often used to build custom boot floppies. .It Cm package-split Generates the portions of the disc 1 and disc 2 images related to packages. It uses the list of desired packages from the .Pa src/release/scripts/package-split.py script to pull packages out of a package build provided by the ports team and organize them appropriately. The resulting directory can then be passed to .Dq Li "make release" via the .Va CD_PACKAGE_TREE variable to populate the ISO images built by the .Cm iso.1 target with the correct package related bits. .El .Pp Targets called by .Dq Li "make release" : .Bl -tag -width ".Cm fetch-distfiles" .It Cm release.1 Cleans out the .Pa ${CHROOTDIR}/R directory and uses .Xr mtree 8 to build the directory hierarchy for the system. .It Cm release.2 Installs the system into the distribution directories. .It Cm release.3 Makes and installs the .Pa GENERIC kernel as well as any other kernels listed in .Va KERNELS . .It Cm release.4 Uses .Xr crunchgen 1 to build .Dq crunched binaries to live on the installation floppies. .It Cm release.5 Builds synthetic distributions, and cleans up the previously built distribution trees. .It Cm release.6 Creates tarballs of the assembled distribution trees. .It Cm release.7 Makes source distributions. .It Cm release.8 Creates the MFS root file systems. .It Cm floppies.1 Creates the boot and kernel floppies. .It Cm floppies.2 Creates the fixit floppy. .It Cm floppies.3 Finalizes the .Pa ${CHROOTDIR}/R/ftp/stage/floppies staging directory. .It Cm ftp.1 Sets up a suitable area for FTP installations in .Pa ${CHROOTDIR}/R/ftp . .It Cm cdrom.1 -Create the layout for the live filesystem CD-ROM image in +Create the layout for the live file system CD-ROM image in .Pa ${CHROOTDIR}/R/cdrom . .It Cm cdrom.2 Create the layout for the first and second CD-ROM images. .It Cm cdrom.3 -Create the layout for the boot only CD-ROM image and the boot only UFS +Create the layout for the boot-only CD-ROM image and the boot-only UFS miniroot image. .It Cm iso.1 Builds ISO images (installation and .Dq live file system) from the CD-ROM release area (disabled by default, see .Va MAKE_ISOS below). .It Cm fetch-distfiles Fetches distfiles needed during the release build that are not already in .Va RELEASEDISTFILES . .It Cm doc.1 Builds all of the necessary tools to turn the .Fx Documentation Project source documents (SGML, XML) into HTML and text documents that will accompany the release. Also, builds and installs the actual user documentation. This includes the Handbook, FAQ, articles, and so on. .It Cm doc.2 Builds the release documentation. This includes the release notes, hardware guide, and installation instructions. .El .Sh ENVIRONMENT Variables that must be specified: .Bl -tag -width ".Va BUILDNAME" .It Va BUILDNAME The name of the release to be built. This is used to set the .Va RELEASE value in .Pa sys/conf/newvers.sh , which affects the output of .Xr uname 1 . .It Va CHROOTDIR The directory to be used as the .Xr chroot 8 environment for the entire release build. .\" XXX: I recommend against hardcoding specific numbers like "2.3" here; .\" XXX: perhaps it should be replaced with something to the effect of .\" XXX: "we do not know how much space you'll need, but make sure you have .\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number, .\" XXX: but at least it looks less like a decree and more like an estimate. This file system should have at least 3.2 gigabytes of free space on the i386 architecture. .It Va CVSROOT The location of the .Fx CVS repository. This path name is in reference to the real system root, .Em not the root of the .Xr chroot 8 directory tree. .El .Pp Optional variables: .Bl -tag -width ".Va NO_PREFETCHDISTFILES" .It Va CD_PACKAGE_TREE A directory containing extra bits for the first and second CD-ROM images. The extra files for the first disc should be in .Pa ${CD_PACKAGE_TREE}/disc1 and the extra files for the second disc should be in .Pa ${CD_PACKAGE_TREE}/disc2 . Typically, this variable will be set to the output directory of an earlier invocation of the .Cm package-split target. .It Va CVSARGS Additional arguments for .Xr cvs 1 that come before the subcommands such as .Dq Li "-qR" . .It Va CVSCMDARGS Additional arguments for .Xr cvs 1 .Ic checkout and .Ic update commands. For example, setting this variable to .Dq Li "-D '01/01/2002 00:00:00 GMT'" for .Dq Li "make release" or .Dq Li "make rerelease" will ask .Xr cvs 1 to check out or update sources as of 00:00:00 GMT, January 1 2002, respectively. .It Va DOC_LANG The list of languages and encodings the SGML-based documentation should be built for. If not set, the documentation is built for all available languages. .It Va DOCRELEASETAG The CVS tag to use when checking out the documentation tree. Usually, the head of the documentation tree is used by default. If .Va RELEASETAG specifies a release tag, then the associated release version is used as the default instead. .It Va EXTLOCALDIR The directory that will be copied to .Pa ${CHROOTDIR}/usr/local . .It Va EXTSRCDIR The directory specified by this variable will be copied into .Pa ${CHROOTDIR}/usr/src instead of that directory being populated by a CVS checkout. For .Dq Li "rerelease" , this will NOT be copied; cvs update will be used instead. .It Va KERNEL_FLAGS The contents of this variable are passed to .Xr make 1 when building kernels during the release build. For example, setting this variable to .Dq Li "-j 4" will instruct .Xr make 1 to execute up to four processes at a time. .It Va KERNELS Specifies a list of additional kernel configurations to compile and install into the .Dq base distribution. Each kernel is installed into .Pa /boot/ so that it can be booted from the loader via .Dq Li "boot " . .It Va LOCAL_PATCHES Patch files against .Pa /usr/src that will be applied in the .Xr chroot 8 environment before the release build begins. .It Va PATCH_FLAGS Arguments for the .Xr patch 1 command used to apply .Va LOCAL_PATCHES patch file. .It Va LOCAL_SCRIPT A script that will be run in the .Xr chroot 8 environment immediately after any local patches are applied. .It Va MAKE_ISOS If defined, bootable ISO CD-ROM images will be created from the contents of the CD-ROM stage directory. .It Va NOCDROM If defined, the CD-ROM stage directories will not be created. .It Va NODOC If defined, the SGML-based documentation from the .Fx Documentation Project will not be built. However, the .Dq doc distribution will still be created with the minimal documentation set provided in .Pa src/share/doc . .It Va NO_FLOPPIES If defined, no boot and fixit floppy disk images will be created (for those platforms supporting them). .It Va NOPORTS If defined, the Ports Collection will be omitted from the release. .It Va PORTSRELEASETAG The CVS tag to use when checking out the ports tree. Usually, the head of the ports tree is used by default. If .Va RELEASETAG specifies a release tag, then the associated release version is used as the default instead. .It Va NO_PREFETCHDISTFILES If this variable is defined, then distfiles needed during the release build will not be downloaded prior to entering the .Xr chroot 8 environment. Note that if .Va NO_PREFETCHDISTFILES is not set, the fetching is done after any distfiles are obtained via .Va RELEASEDISTFILES . .It Va RELEASEDISTFILES The directory where the distribution files for ports required by the release build can be found. This may save a significant amount of time over downloading the distfiles through a slow link. .It Va RELEASENOUPDATE If this variable is defined for .Dq Li "make rerelease" , the source code will not be updated with .Dq Li "cvs update" . .It Va RELEASETAG The CVS tag corresponding to the release that is to be built. If undefined, the release will be built from the .Dv HEAD of the CVS tree (a .Dq "-CURRENT snapshot" ) . .It Va SEPARATE_LIVEFS -Store the live filesystem on its own CD-ROM image rather than placing it on +Store the live file system on its own CD-ROM image rather than placing it on the first disc. .It Va TARGET_ARCH The target machine processor architecture. This is analogous to the .Dq Nm uname Fl p output. Set this to cross-build for a different architecture. .It Va TARGET The target hardware platform. This is analogous to the .Dq Nm uname Fl m output. This is necessary to cross-build some target architectures. For example, cross-building for PC98 machines requires .Va TARGET_ARCH Ns = Ns Li i386 and .Va TARGET Ns = Ns Li pc98 . .It Va WORLDDIR The directory where .Dq Li "make buildworld" was run; defaults to .Pa ${.CURDIR}/.. which usually points to .Pa /usr/src . .It Va WORLD_FLAGS The contents of this variable are passed to .Xr make 1 when building world during the release build. For example, setting this variable to .Dq Li "-j 4" will instruct .Xr make 1 to execute up to four processes at a time. .El .Sh FILES .Bl -tag -compact .It Pa /etc/make.conf .It Pa /usr/doc/Makefile .It Pa /usr/doc/share/mk/doc.project.mk .It Pa /usr/ports/Mk/bsd.port.mk .It Pa /usr/ports/Mk/bsd.sites.mk .It Pa /usr/share/examples/etc/make.conf .It Pa /usr/src/Makefile .It Pa /usr/src/Makefile.inc1 .It Pa /usr/src/release/Makefile .It Pa /usr/src/release/${arch}/boot_crunch.conf .It Pa /usr/src/release/${arch}/fixit_crunch.conf .El .Sh EXAMPLES The following sequence of commands was used to build the .Fx 4.9 release: .Bd -literal -offset indent cd /usr cvs co -rRELENG_4_9_0_RELEASE src cd src make buildworld cd release make release CHROOTDIR=/local3/release BUILDNAME=4.9-RELEASE \\ CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_9_0_RELEASE .Ed .Pp After running these commands, a complete system suitable for FTP or CD-ROM distribution is available in the .Pa /local3/release/R directory. .Pp The following sequence of commands can be used to build a .Dq "-CURRENT snapshot" of a locally modified source tree: .Bd -literal -offset indent cd /usr/src cvs diff -u > /path/to/local.patch make buildworld cd release make release CHROOTDIR=/local3/release BUILDNAME=6.0-CURRENT \\ CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch .Ed .Sh SEE ALSO .Xr cc 1 , .Xr crunchgen 1 , .Xr cvs 1 , .Xr install 1 , .Xr make 1 , .Xr patch 1 , .Xr uname 1 , .Xr md 4 , .Xr make.conf 5 , .Xr build 7 , .Xr ports 7 , .Xr chroot 8 , .Xr mtree 8 , .Xr sysctl 8 .Rs .%T "FreeBSD Release Engineering" .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ .Re .Rs .%T "FreeBSD Release Engineering of Third Party Packages" .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ .Re .Rs .%T "FreeBSD Developers' Handbook" .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ .Re .Sh HISTORY .Fx 1.x used a manual checklist, compiled by .An Rod Grimes , to produce a release. Apart from being incomplete, the list put a lot of specific demands on available file systems and was quite torturous to execute. .Pp As part of the .Fx 2.0 release engineering effort, significant effort was spent getting .Pa src/release/Makefile into a shape where it could at least automate most of the tediousness of building a release in a sterile environment. .Pp With its almost 1000 revisions spread over multiple branches, the .Xr cvs 1 log of .Pa src/release/Makefile contains a vivid historical record of some of the hardships release engineers go through. .Sh AUTHORS .Pa src/release/Makefile was originally written by .An -nosplit .An Rod Grimes , .An Jordan Hubbard , and .An Poul-Henning Kamp . This manual page was written by .An Murray Stokely Aq murray@FreeBSD.org . .Sh BUGS Infrastructure changes are occasionally made to the .Fx documentation set in such a way that release builds on security branches can fail. To work around this, release builds can be made to checkout the documentation from the last fully supported release of .Fx . For example: .Pp .Dl "make release RELEASETAG=RELENG_4_9 DOCRELEASETAG=RELEASE_4_9_0 ..." Index: head/share/man/man9/MUTEX_PROFILING.9 =================================================================== --- head/share/man/man9/MUTEX_PROFILING.9 (revision 147397) +++ head/share/man/man9/MUTEX_PROFILING.9 (revision 147398) @@ -1,190 +1,189 @@ .\"- .\" Copyright (c) 2004 Dag-Erling Coïdan Smørgrav .\" Copyright (c) 2005 Robert N. M. Watson .\" 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. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" 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 January 7, 2005 .Dt MUTEX_PROFILING 9 .Os .Sh NAME .Nm MUTEX_PROFILING .Nd kernel mutex profiling support .Sh SYNOPSIS .Cd "options MUTEX_PROFILING" .Sh DESCRIPTION The .Dv MUTEX_PROFILING kernel option adds support for measuring and reporting mutex use and contention statistics. These statistics are collated by .Dq acquisition point . Acquisition points are distinct places in the kernel source code (identified by source file name and line number) where a mutex is acquired. .Pp For each acquisition point, the following statistics are accumulated: .Bl -bullet .It The total number of non-recursive acquisitions. .It The total time the mutex was held after being acquired at this point. .It The longest time the mutex was ever continuously held after being acquired at this point. .It The total number of times the mutex was already held by another thread when this point was reached, requiring a spin or a sleep. .It The total number of time another thread tried to acquire the mutex while it was held after having been acquired at this point. .El .Pp In addition, the average hold time is derived from the total hold time and the number of acquisitions. .Pp The .Dv MUTEX_PROFILING kernel option also adds the following .Xr sysctl 8 variables to control and monitor the profiling code: .Bl -tag -width indent .It Va debug.mutex.prof.enable Enable or disable the mutex profiling code. This defaults to 0 (off). .It Va debug.mutex.prof.reset Reset the current mutex profiling buffers. .It Va debug.mutex.prof.acquisitions The total number of mutex acquisitions recorded. .It Va debug.mutex.prof.records The total number of acquisition points recorded. Note that only active acquisition points (i.e., points that have been reached at least once) are counted. .It Va debug.mutex.prof.maxrecords The maximum number of acquisition points the profiling code is capable of monitoring. Since it would not be possible to call .Xr malloc 9 from within the mutex profiling code, this is a static limit. The number of records can be changed with the .Dv MPROF_BUFFERS kernel option. .It Va debug.mutex.prof.rejected The number of acquisition points that were ignored after the table filled up. .It Va debug.mutex.prof.hashsize The size of the hash table used to map acquisition points to statistics records. The hash size can be changed with the .Dv MPROF_HASH_SIZE kernel option. .It Va debug.mutex.prof.collisions The number of hash collisions in the acquisition point hash table. .It Va debug.mutex.prof.stats The actual profiling statistics in plain text. The columns are as follows, from left to right: .Bl -tag -width ".Va cnt_hold" .It Va max The longest continuous hold time in microseconds. .It Va total The total (accumulated) hold time in microseconds. .It Va count The total number of acquisitions. .It Va avg The average hold time in microseconds, derived from the total hold time and the number of acquisitions. .It Va cnt_hold The number of times the mutex was held and another thread attempted to lock the mutex. .It Va cnt_lock The number of times the mutex was already locked when this point was reached. .It Va name The name of the acquisition point, derived from the source file name and line number, followed by the name of the mutex in parentheses. .El .El .Sh SEE ALSO .Xr sysctl 8 , .Xr mutex 9 .Sh HISTORY Mutex profiling support appeared in .Fx 5.0 . .Sh AUTHORS .An -nosplit The .Nm code was written by .An Eivind Eklund Aq eivind@FreeBSD.org , .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org and .An Robert Watson Aq rwatson@FreeBSD.org . This manual page was written by .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org . .Sh NOTES The .Dv MUTEX_PROFILING option increases the size of .Vt "struct mtx" , so a kernel built with that option will not work with modules built without it. .Pp The .Dv MUTEX_PROFILING option also prevents inlining of the mutex code, which results in a fairly severe performance penalty. It should therefore only be enabled on systems where mutex profiling is actually needed. .Dv MUTEX_PROFILING will introduce a substantial performance overhead that is easily monitorable using other profiling tools, so combining profiling tools with .Dv MUTEX_PROFILING is not recommended. .Pp Measurements are made and stored in nanoseconds using .Xr nanotime 9 , but are presented in microseconds. This should still be sufficient for the locks one would be most interested in profiling (those that are held long and/or acquired often). .Pp .Dv MUTEX_PROFILING should generally not be used in combination with other debugging options, as the results may be strongly affected by interactions between the features. In particular, .Dv MUTEX_PROFILING will report higher than normal .Xr uma 9 lock contention when run with .Dv INVARIANTS due to extra locking that occurs when .Dv INVARIANTS is present; likewise, using it in combination with .Dv WITNESS -with will lead to much higher lock hold times and contention in profiling output. Index: head/share/man/man9/VFS_SYNC.9 =================================================================== --- head/share/man/man9/VFS_SYNC.9 (revision 147397) +++ head/share/man/man9/VFS_SYNC.9 (revision 147398) @@ -1,85 +1,85 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 1996 Doug Rabson .\" .\" All rights reserved. .\" .\" This program is free software. .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 January 7, 2005 .Os .Dt VFS_SYNC 9 .Sh NAME .Nm VFS_SYNC .Nd flush unwritten data .Sh SYNOPSIS .In sys/param.h .In sys/mount.h .In sys/vnode.h .Ft int .Fn VFS_SYNC "struct mount *mp" "int waitfor" "struct ucred *cred" "struct thread *td" .Sh DESCRIPTION The .Fn VFS_SYNC macro writes out all unwritten data in the file system mounted as .Fa mp . .Pp The arguments it expects are: .Bl -tag -width ".Fa waitfor" .It Fa mp The file system. .It Fa waitfor Whether the function should wait for I/O to complete. Possible values are: .Bl -tag -width MNT_NOWAIT .It Dv MNT_WAIT synchronously wait for I/O to complete .It Dv MNT_NOWAIT start all I/O, but do not wait for it .It Dv MNT_LAZY push data not written by file system syncer .El .It Fa cred The caller's credentials. .It Fa td The calling thread. .El .Pp The .Fn VFS_SYNC macro calls the .Va vfs_sync -method of the filesystem, which normally calls +method of the file system, which normally calls .Xr VOP_FSYNC 9 for all the vnodes in the file system. .Sh SEE ALSO .Xr fsync 2 , .Xr sync 2 , .Xr VFS 9 , .Xr vnode 9 , .Xr VOP_FSYNC 9 .Sh AUTHORS This manual page was written by .An Doug Rabson . Index: head/share/man/man9/VFS_VGET.9 =================================================================== --- head/share/man/man9/VFS_VGET.9 (revision 147397) +++ head/share/man/man9/VFS_VGET.9 (revision 147398) @@ -1,79 +1,83 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 1996 Doug Rabson .\" .\" All rights reserved. .\" .\" This program is free software. .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 January 7, 2005 .Os .Dt VFS_VGET 9 .Sh NAME .Nm VFS_VGET .Nd convert an inode number to a vnode .Sh SYNOPSIS .In sys/param.h .In sys/mount.h .In sys/vnode.h .Ft int .Fn VFS_VGET "struct mount *mp" "ino_t ino" "int flags" "struct vnode **vpp" .Sh DESCRIPTION The .Fn VFS_VGET looks up or creates a vnode from a (mount, inode#) tupple. .Pp Its arguments are: .Bl -tag -width ".Fa flags" .It Fa mp -The mountpoint. +The mount point. .It Fa ino The inode representing the file. -This is a unique number assigned by the filesystem when vnodes are first +This is a unique number assigned by the file system when vnodes are first created. .It Fa flags Additional locking flags to pass through to -.Xr vget 9 +.Xr vget 9 . .It Fa vpp Return parameter for the vnode. .El .Pp This is an optional file system entry-point for file systems mainly -intended for NFS server use, but many filesystems +intended for NFS server use, but many file systems use it internally in .Xr VOP_LOOKUP 9 and similar. .Pp If the file system does not support this call, then it should return .Er EOPNOTSUPP . .Pp -Please see sys/ufs/ffs/ffs_vfsops.c::ffs_vget() for the canonical example. +Please see +.Fn ffs_vget +in +.Pa sys/ufs/ffs/ffs_vfsops.c +for the canonical example. .Sh SEE ALSO .Xr VFS 9 , .Xr vget 9 , .Xr vnode 9 .Sh AUTHORS This manual page was written by .An Doug Rabson . Index: head/share/man/man9/VOP_GETPAGES.9 =================================================================== --- head/share/man/man9/VOP_GETPAGES.9 (revision 147397) +++ head/share/man/man9/VOP_GETPAGES.9 (revision 147398) @@ -1,162 +1,162 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 1996 Doug Rabson .\" Copyright 2003, Garrett A. Wollman .\" .\" All rights reserved. .\" .\" This program is free software. .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 September 27, 2003 .Os .Dt VOP_GETPAGES 9 .Sh NAME .Nm VOP_GETPAGES , .Nm VOP_PUTPAGES .Nd read or write VM pages from a file .Sh SYNOPSIS .In sys/param.h .In sys/vnode.h .In vm/vm.h .Ft int .Fn VOP_GETPAGES "struct vnode *vp" "vm_page_t *m" "int count" "int reqpage" "vm_ooffset_t offset" .Ft int .Fn VOP_PUTPAGES "struct vnode *vp" "vm_page_t *m" "int count" "int sync" "int *rtvals" "vm_ooffset_t offset" .Sh DESCRIPTION The .Fn VOP_GETPAGES method is called to read in pages of virtual memory which are backed by ordinary files. If other adjacent pages are backed by adjacent regions of the same file, .Fn VOP_GETPAGES is requested to read those pages as well, although it is not required to do so. The .Fn VOP_PUTPAGES method does the converse; that is to say, it writes out adjacent dirty pages of virtual memory. .Pp On entry, the vnode lock is held but neither the page queue nor VM object locks are held. Both methods return in the same state on both success and error returns. .Pp The arguments are: .Bl -tag -width reqpage .It Fa vp The file to access. .It Fa m Pointer to the first element of an array of contiguous pages representing a contiguous region of the file to be read or written. .It Fa count The number of pages in the array. .It Fa sync .Dv VM_PAGER_PUT_SYNC if the write should be synchronous. .It Fa rtvals An array of VM system result codes indicating the status of each page written by .Fn VOP_PUTPAGES . .It Fa reqpage The index in the page array of the requested page; i.e., the one page which the implementation of this method must handle. .It Fa offset Offset in the file at which the mapped pages begin. .El .Pp The status of the .Fn VOP_PUTPAGES method is returned on a page-by-page basis in the array .Fa rtvals[] . The possible status values are as follows: .Bl -tag -width VM_PAGER_ERROR .It Dv VM_PAGER_OK The page was successfully written. The implementation must call .Xr vm_page_undirty 9 to mark the page as clean. .It Dv VM_PAGER_PEND The page was scheduled to be written asynchronously. When the write completes, the completion callback should call .Xr vm_object_pip_wakeup 9 and .Xr vm_page_io_finish 9 to clear the busy flag and awaken any other threads waiting for this page, in addition to calling .Xr vm_page_undirty 9 . .It Dv VM_PAGER_BAD The page was entirely beyond the end of the backing file. -This condition should not be possible if the vnode's filesystem +This condition should not be possible if the vnode's file system is correctly implemented. .It Dv VM_PAGER_ERROR The page could not be written because of an error on the underlying storage medium or protocol. .It Dv VM_PAGER_FAIL Treated identically to .Dv VM_PAGER_ERROR .It Dv VM_PAGER_AGAIN The page was not handled by this request. .El .Pp The .Fn VOP_GETPAGES method is expected to release any pages in .Fa m that it does not successfully handle, by calling .Xr vm_page_free 9 . When it succeeds, .Fn VOP_GETPAGES must set the valid bits appropriately, clear the dirty bit (using .Xr vm_page_undirty 9 ) , either activate the page (if its wanted bit is set) or deactivate it (otherwise), and finally call .Xr vm_page_wakeup 9 to arouse any threads currently waiting for the page to be faulted in, for each page read. .Sh RETURN VALUES If it successfully reads .Fa m[reqpage] , .Fn VOP_GETPAGES returns .Dv VM_PAGER_OK ; otherwise, .Dv VM_PAGER_ERROR . By convention, the return value of .Fn VOP_PUTPAGES is .Fa rtvals[0] . .Sh SEE ALSO .Xr vm_object_pip_wakeup 9 , .Xr vm_page_free 9 , .Xr vm_page_io_finish 9 , .Xr vm_page_undirty 9 , .Xr vm_page_wakeup 9 , .Xr vnode 9 .Sh AUTHORS This manual page was written by .An Doug Rabson and then substantially rewritten by .An Garrett Wollman . Index: head/share/man/man9/bus_dma.9 =================================================================== --- head/share/man/man9/bus_dma.9 (revision 147397) +++ head/share/man/man9/bus_dma.9 (revision 147398) @@ -1,816 +1,816 @@ .\" Copyright (c) 2002, 2003 Hiten M. Pandya. .\" 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, .\" without modification, immediately at the beginning of the file. .\" 2. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" 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, CONTRIBUTORS OR THE .\" VOICES IN HITEN PANDYA'S HEAD 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. .\" .\" Copyright (c) 1996, 1997, 1998, 2001 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility, .\" NASA Ames Research Center. .\" .\" 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. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgment: .\" This product includes software developed by the NetBSD .\" Foundation, Inc. and its contributors. .\" 4. Neither the name of The NetBSD Foundation nor the names of its .\" contributors may be used to endorse or promote products derived .\" from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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$ .\" $NetBSD: bus_dma.9,v 1.25 2002/10/14 13:43:16 wiz Exp $ .\" .Dd May 28, 2003 .Dt BUS_DMA 9 .Os .Sh NAME .Nm bus_dma , .Nm bus_dma_tag_create , .Nm bus_dma_tag_destroy , .Nm bus_dmamap_create , .Nm bus_dmamap_destroy , .Nm bus_dmamap_load , .Nm bus_dmamap_load_mbuf , .Nm bus_dmamap_load_mbuf_sg , .Nm bus_dmamap_load_uio , .Nm bus_dmamap_unload , .Nm bus_dmamap_sync , .Nm bus_dmamem_alloc , .Nm bus_dmamem_free .Nd Bus and Machine Independent DMA Mapping Interface .Sh SYNOPSIS .In machine/bus.h .Ft int .Fn bus_dma_tag_create "bus_dma_tag_t parent" "bus_size_t alignment" \ "bus_size_t boundary" "bus_addr_t lowaddr" "bus_addr_t highaddr" \ "bus_dma_filter_t *filtfunc" "void *filtfuncarg" "bus_size_t maxsize" \ "int nsegments" "bus_size_t maxsegsz" "int flags" "bus_dma_lock_t *lockfunc" \ "void *lockfuncarg" "bus_dma_tag_t *dmat" .Ft int .Fn bus_dma_tag_destroy "bus_dma_tag_t dmat" .Ft int .Fn bus_dmamap_create "bus_dma_tag_t dmat" "int flags" "bus_dmamap_t *mapp" .Ft int .Fn bus_dmamap_destroy "bus_dma_tag_t dmat" "bus_dmamap_t map" .Ft int .Fn bus_dmamap_load "bus_dma_tag_t dmat" "bus_dmamap_t map" "void *buf" \ "bus_size_t buflen" "bus_dmamap_callback_t *callback" "void *callback_arg" \ "int flags" .Ft int .Fn bus_dmamap_load_mbuf "bus_dma_tag_t dmat" "bus_dmamap_t map" \ "struct mbuf *mbuf" "bus_dmamap_callback2_t *callback" "void *callback_arg" \ "int flags" .Ft int .Fn bus_dmamap_load_mbuf_sg "bus_dma_tag_t dmat" "bus_dmamap_t map" \ "struct mbuf *mbuf" "bus_dma_segment_t *segs" "int *nsegs" "int flags" .Ft int .Fn bus_dmamap_load_uio "bus_dma_tag_t dmat" "bus_dmamap_t map" \ "struct uio *uio" "bus_dmamap_callback2_t *callback" "void *callback_arg" \ "int flags" .Ft void .Fn bus_dmamap_unload "bus_dma_tag_t dmat" "bus_dmamap_t map" .Ft void .Fn bus_dmamap_sync "bus_dma_tag_t dmat" "bus_dmamap_t map" \ "op" .Ft int .Fn bus_dmamem_alloc "bus_dma_tag_t dmat" "void **vaddr" \ "int flags" "bus_dmamap_t *mapp" .Ft void .Fn bus_dmamem_free "bus_dma_tag_t dmat" "void *vaddr" \ "bus_dmamap_t map" .Sh DESCRIPTION Direct Memory Access (DMA) is a method of transferring data without involving the CPU, thus providing higher performance. A DMA transaction can be achieved between device to memory, device to device, or memory to memory. .Pp The .Nm API is a bus, device, and machine-independent (MI) interface to DMA mechanisms. It provides the client with flexibility and simplicity by abstracting machine dependent issues like setting up DMA mappings, handling cache issues, bus specific features and limitations. .Sh STRUCTURES AND TYPES .Bl -tag -width compact .It Vt bus_dma_tag_t A machine-dependent (MD) opaque type that describes the characteristics of DMA transactions. DMA tags are organized into a hierarchy, with each child tag inheriting the restrictions of its parent. This allows all devices along the path of DMA transactions to contribute to the constraints of those transactions. .It Vt bus_dma_filter_t Client specified address filter having the format: .Bl -tag -width compact .It Ft int .Fn "client_filter" "void *filtarg" "bus_addr_t testaddr" .El .sp Address filters can be specified during tag creation to allow for devices whose DMA address restrictions cannot be specified by a single window. The .Fa filtarg is client specified during tag creation to be passed to all invocations of the callback. The .Fa testaddr argument contains a potential starting address of a DMA mapping. The filter function operates on the set of addresses from .Fa testaddr to .Ql trunc_page(testaddr) + PAGE_SIZE - 1 , inclusive. The filter function should return zero for any mapping in this range that can be accommodated by the device and non-zero otherwise. .It Vt bus_dma_segment_t A machine-dependent type that describes individual DMA segments. .Bd -literal bus_addr_t ds_addr; bus_size_t ds_len; .Ed .sp The .Fa ds_addr field contains the device visible address of the DMA segment, and .Fa ds_len contains the length of the DMA segment. Although the DMA segments returned by a mapping call will adhere to all restrictions necessary for a successful DMA operation, some conversion (e.g.\& a conversion from host byte order to the device's byte order) is almost always required when presenting segment information to the device. .It Vt bus_dmamap_t A machine-dependent opaque type describing an individual mapping. Multiple DMA maps can be associated with one DMA tag. .It Vt bus_dmamap_callback_t Client specified callback for receiving mapping information resulting from the load of a .Vt bus_dmamap_t via .Fn bus_dmamap_load . Callbacks are of the format: .Bl -tag -width compact .It Ft void .Fn "client_callback" "void *callback_arg" "bus_dma_segment_t *segs" \ "int nseg" "int error" .El .sp The .Fa callback_arg is the callback argument passed to dmamap load functions. The .Fa segs and .Fa nseg parameters describe an array of .Vt bus_dma_segment_t structures that represent the mapping. This array is only valid within the scope of the callback function. The success or failure of the mapping is indicated by the .Fa error parameter. More information on the use of callbacks can be found in the description of the individual dmamap load functions. .It Vt bus_dmamap_callback2_t Client specified callback for receiving mapping information resulting from the load of a .Vt bus_dmamap_t via .Fn bus_dmamap_load_uio or .Fn bus_dmamap_load_mbuf . .sp Callback2s are of the format: .Bl -tag -width compact .It Ft void .Fn "client_callback2" "void *callback_arg" "bus_dma_segment_t *segs" \ "int nseg" "bus_size_t mapsize" "int error" .El .sp Callback2's behavior is the same as .Vt bus_dmamap_callback_t with the addition that the length of the data mapped is provided via .Fa mapsize . .It Vt bus_dmasync_op_t Memory synchronization operation specifier. Bus DMA requires explicit synchronization of memory with its device visible mapping in order to guarantee memory coherency. The .Vt bus_dmasync_op_t allows the type of DMA operation that will be or has been performed to be communicated to the system so that the correct coherency measures are taken. All operations specified below are performed from the CPU's point of view (for a complete description, see the .Fn bus_dmamap_sync description below): .Bl -tag -width BUS_DMASYNC_POSTWRITE .It Dv BUS_DMASYNC_PREREAD Perform any synchronization required after an update of memory by the CPU but prior to DMA read operations. .It Dv BUS_DMASYNC_PREWRITE Perform any synchronization required after an update of memory by the CPU but prior to DMA write operations. .It Dv BUS_DMASYNC_PREREAD|BUS_DMASYNC_PREWRITE Perform any synchronization required prior to a combination of DMA read and write operations. .It Dv BUS_DMASYNC_POSTREAD Perform any synchronization required after DMA read operations, but prior to CPU access of the memory. .It Dv BUS_DMASYNC_POSTWRITE Perform any synchronization required after DMA write operations, but prior to CPU access of the memory. .It Dv BUS_DMASYNC_POSTREAD|BUS_DMASYNC_POSTWRITE Perform any synchronization required after a combination of DMA read and write operations. .El .It Vt bus_dma_lock_t Client specified lock/mutex manipulation method. This will be called from within busdma whenever a client lock needs to be manipulated. In its current form, the function will be called immediately before the callback for a dma load operation that has been deferred with .Dv BUS_DMA_LOCK and immediately after with .Dv BUS_DMA_UNLOCK . If the load operation does not need to be deferred, then it will not be called since the function loading the map should be holding the appropriate locks. This method is of the format: .Bl -tag -width compact .It Ft void .Fn "lockfunc" "void *lockfunc_arg" "bus_dma_lock_op_t op" .El .sp Two .Vt lockfunc implementations are provided for convenience. .Fn busdma_lock_mutex performs standard mutex operations on the sleep mutex provided via the .Fa lockfuncarg . passed into .Fn bus_dma_tag_create . .Fn dflt_lock will generate a system panic if it is called. It is substituted into the tag when .Fa lockfunc is passed as NULL to .Fn bus_dma_tag_create . .It Vt bus_dma_lock_op_t Operations to be performed by the client-specified .Fn lockfunc . .Bl -tag -width BUS_DMA_UNLOCK .It Dv BUS_DMA_LOCK Acquires and/or locks the client locking primitive. .It Dv BUS_DMA_UNLOCK Releases and/or unlocks the client locking primitive. .El .El .sp .Sh FUNCTIONS .Bl -tag -width compact .It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \ "highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \ "flags" "lockfunc" "lockfuncarg" "*dmat" Allocates a device specific DMA tag, and initializes it according to the arguments provided: .Bl -tag -width *filtfuncarg -compact .It Fa parent Indicates restrictions between the parent bridge, CPU memory, and the device. May be NULL, if no DMA restrictions are to be inherited. .It Fa alignment Alignment constraint, in bytes, of any mappings created using this tag. The alignment must be a power of 2. Hardware that can DMA starting at any address would specify .Em 1 for byte alignment. Hardware requiring DMA transfers to start on a multiple of 4K would specify .Em 4096. .It Fa boundary Boundary constraint, in bytes, of the target DMA memory region. The boundary indicates the set of addresses, all multiples of the boundary argument, that cannot be crossed by a single .Vt bus_dma_segment_t . The boundary must be a power of 2 and must be no smaller than the maximum segment size. .Ql 0 indicates that there are no boundary restrictions. .It Fa lowaddr .It Fa highaddr Bounds of the window of bus address space that .Em cannot be directly accessed by the device. The window contains all addresses greater than lowaddr and less than or equal to highaddr. For example, a device incapable of DMA above 4GB, would specify a highaddr of .Dv BUS_SPACE_MAXADDR and a lowaddr of .Dv BUS_SPACE_MAXADDR_32BIT . Similarly a device that can only dma to addresses bellow 16MB would specify a highaddr of .Dv BUS_SPACE_MAXADDR and a lowaddr of .Dv BUS_SPACE_MAXADDR_24BIT . Some implementations requires that some region of device visible address space, overlapping available host memory, be outside the window. This area of .Ql safe memory is used to bounce requests that would otherwise conflict with the exclusion window. .It Fa filtfunc Optional filter function (may be NULL) to be called for any attempt to map memory into the window described by .Fa lowaddr and .Fa highaddr. A filter function is only required when the single window described by .Fa lowaddr and .Fa highaddr cannot adequately describe the constraints of the device. The filter function will be called for every machine page that overlaps the exclusion window. .It Fa filtfuncarg Argument passed to all calls to the filter function for this tag. May be NULL. .It Fa maxsize Maximum size, in bytes, of the sum of all segment lengths in a given DMA mapping associated with this tag. .It Fa nsegments Number of discontinuities (scatter/gather segments) allowed in a DMA mapped region. If there is no restriction, .Dv BUS_SPACE_UNRESTRICTED may be specified. .It Fa maxsegsz Maximum size, in bytes, of a segment in any DMA mapped region associated with .Fa dmat . .It Fa flags Are as follows: .Bl -tag -width "BUS_DMA_ALLOCNOW" -compact .It Dv BUS_DMA_ALLOCNOW Pre-allocate enough resources to handle at least one map load operation on this tag without blocking. If sufficient resources are not available, .Er ENOMEM is returned. This should not be used for tags that will not be directly associated with a map. .El .It Fa lockfunc Optional lock manipulation function (may be NULL) to be called when busdma needs to manipulate a lock on behalf of the client. If NULL is specified, .Fn dflt_lock is used. .It Fa lockfuncarg Optional argument to be passed to the function specified by .Fa lockfunc . .It Fa dmat Pointer to a bus_dma_tag_t where the resulting DMA tag will be stored. .El .Pp Returns .Er ENOMEM if sufficient memory is not available for tag creation or allocating mapping resources. .It Fn bus_dma_tag_destroy "dmat" Deallocate the DMA tag .Fa dmat that was created by .Fn bus_dma_tag_create . .Pp Returns .Er EBUSY if any DMA maps remain associated with .Fa dmat or .Ql 0 on success. .It Fn bus_dmamap_create "dmat" "flags" "*mapp" Allocates and initializes a DMA map. Arguments are as follows: .Bl -tag -width nsegments -compact .It Fa dmat DMA tag. .It Fa flags The value of this argument is currently undefined and should be specified as .Ql 0 . .It Fa mapp Pointer to a .Vt bus_dmamap_t where the resulting DMA map will be stored. .El .Pp Returns .Er ENOMEM if sufficient memory is not available for creating the map or allocating mapping resources. .It Fn bus_dmamap_destroy "dmat" "map" Frees all resources associated with a given DMA map. Arguments are as follows: .Bl -tag -width dmat -compact .It Fa dmat DMA tag used to allocate .Fa map . .It Fa map The DMA map to destroy. .El .Pp Returns .Er EBUSY if a mapping is still active for .Fa map . .It Fn bus_dmamap_load "dmat" "map" "buf" "buflen" "*callback" \ "callback_arg" "flags" Creates a mapping in device visible address space of .Fa buflen bytes of .Fa buf , associated with the DMA map .Fa map. Arguments are as follows: .Bl -tag -width buflen -compact .It Fa dmat DMA tag used to allocate .Fa map. .It Fa map A DMA map without a currently active mapping. .It Fa buf A kernel virtual address pointer to a contiguous (in KVA) buffer, to be mapped into device visible address space. .It Fa buflen The size of the buffer. .It Fa callback Fa callback_arg The callback function, and its argument. .It Fa flags The value of this argument is currently undefined, and should be specified as .Ql 0 . .El .Pp Return values to the caller are as follows: .Bl -tag -width EINPROGRESS -compact .It 0 The callback has been called and completed. The status of the mapping has been delivered to the callback. .It Er EINPROGRESS The mapping has been deferred for lack of resources. The callback will be called as soon as resources are available. Callbacks are serviced in FIFO order. To ensure that ordering is guaranteed, all subsequent load requests will also be deferred until all callbacks have been processed. .It Er EINVAL The load request was invalid. The callback has not, and will not be called. This error value may indicate that .Fa dmat , .Fa map , .Fa buf , or .Fa callback were invalid, or .Fa buslen was larger than the .Fa maxsize argument used to create the dma tag .Fa dmat . .El .Pp When the callback is called, it is presented with an error value indicating the disposition of the mapping. Error may be one of the following: .Bl -tag -width EINPROGRESS -compact .It 0 The mapping was successful and the .Fa dm_segs callback argument contains an array of .Vt bus_dma_segment_t elements describing the mapping. This array is only valid during the scope of the callback function. .It Er EFBIG A mapping could not be achieved within the segment constraints provided in the tag even though the requested allocation size was less than maxsize. .El .It Fn bus_dmamap_load_mbuf "dmat" "map" "mbuf" "callback2" "callback_arg" \ "flags" This is a variation of .Fn bus_dmamap_load which maps mbuf chains for DMA transfers. A .Vt bus_size_t argument is also passed to the callback routine, which contains the mbuf chain's packet header length. .Pp Mbuf chains are assumed to be in kernel virtual address space. .Pp Returns .Er EINVAL if the size of the mbuf chain exceeds the maximum limit of the DMA tag. .It Fn bus_dmamap_load_mbuf_sg "dmat" "map" "mbuf" "segs" "nsegs" "flags" This is just like .Fn bus_dmamap_load_mbuf -except that it returns immediately without calling a callback function. It is -provided for efficiency. +except that it returns immediately without calling a callback function. +It is provided for efficiency. The scatter/gather segment array .Va segs is provided by the caller and filled in directly by the function. The .Va nsegs argument is returned with the number of segments filled in. Returns the same errors as .Fn bus_dmamap_load_mbuf . .It Fn bus_dmamap_load_uio "dmat" "map" "uio" "callback2" "callback_arg" "flags" This is a variation of .Fn bus_dmamap_load which maps buffers pointed to by .Fa uio for DMA transfers. A .Vt bus_size_t argument is also passed to the callback routine, which contains the size of .Fa uio , i.e. .Fa uio->uio_resid . .Pp If .Fa uio->uio_segflg is .Dv UIO_USERSPACE , then it is assumed that the buffer, .Fa uio is in .Fa "uio->uio_td->td_proc" Ns 's address space. User space memory must be in-core and wired prior to attempting a map load operation. Pages may be locked using .Xr vslock 9 . .It Fn bus_dmamap_unload "dmat" "map" Unloads a DMA map. Arguments are as follows: .Bl -tag -width dmam -compact .It Fa dmat DMA tag used to allocate .Fa map . .It Fa map The DMA map that is to be unloaded. .El .Pp .Fn bus_dmamap_unload will not perform any implicit synchronization of DMA buffers. This must be done explicitly by a call to .Fn bus_dmamap_sync prior to unloading the map. .It Fn bus_dmamap_sync "dmat" "map" "op" Performs synchronization of a device visible mapping with the CPU visible memory referenced by that mapping. Arguments are as follows: .Bl -tag -width dmat -compact .It Fa dmat DMA tag used to allocate .Fa map . .It Fa map The DMA mapping to be synchronized. .It Fa op Type of synchronization operation to perform. See the definition of .Vt bus_dmasync_op_t for a description of the acceptable values for .Fa op . .El .Pp .Fn bus_dmamap_sync is the method used to ensure that CPU and device DMA access to shared memory is coherent. For example, the CPU might be used to setup the contents of a buffer that is to be DMA'ed into a device. To ensure that the data are visible via the device's mapping of that memory, the buffer must be loaded and a dma sync operation of .Dv BUS_DMASYNC_PREREAD must be performed. Additional sync operations must be performed after every CPU write to this memory if additional DMA reads are to be performed. Conversely, for the DMA write case, the buffer must be loaded, and a dma sync operation of .Dv BUS_DMASYNC_PREWRITE must be performed. The CPU will only be able to see the results of this DMA write once the DMA has completed and a .Dv BUS_DMASYNC_POSTWRITE operation has been performed. .Pp If DMA read and write operations are not preceded and followed by the appropriate synchronization operations, behavior is undefined. .It Fn bus_dmamem_alloc "dmat" "**vaddr" "flags" "mapp" Allocates memory that is mapped into KVA at the address returned in .Fa vaddr that is permanently loaded into the newly created .Vt bus_dmamap_t returned via .Fa mapp . Arguments are as follows: .Bl -tag -width alignment -compact .It Fa dmat DMA tag describing the constraints of the DMA mapping. .It Fa vaddr Pointer to a pointer that will hold the returned KVA mapping of the allocated region. .It Fa flags Flags are defined as follows: .Bl -tag -width BUS_DMA_NOWAIT -compact .It Dv BUS_DMA_WAITOK The routine can safely wait (sleep) for resources. .It Dv BUS_DMA_NOWAIT The routine is not allowed to wait for resources. If resources are not available, .Dv ENOMEM is returned. .It Dv BUS_DMA_COHERENT Attempt to map this memory such that cache sync operations are as cheap as possible. This flag is typically set on memory that will be accessed by both a CPU and a DMA engine, frequently. Use of this flag does not remove the requirement of using bus_dmamap_sync, but it may reduce the cost of performing these operations. .It Dv BUS_DMA_ZERO Causes the allocated memory to be set to all zeros. .El .It Fa mapp Pointer to storage for the returned DMA map. .El .Pp The size of memory to be allocated is .Fa maxsize as specified in .Fa dmat . .Pp The current implementation of .Fn bus_dmamem_alloc will allocate all requests as a single segment. .Pp Although no explicit loading is required to access the memory referenced by the returned map, the synchronization requirements as described in the .Fn bus_dmamap_sync section still apply. .Pp Returns .Er ENOMEM if sufficient memory is not available for completing the operation. .It Fn bus_dmamem_free "dmat" "*vaddr" "map" Frees memory previously allocated by .Fn bus_dmamem_alloc . Any mappings will be invalidated. Arguments are as follows: .Bl -tag -width vaddr -compact .It Fa dmat DMA tag. .It Fa vaddr Kernel virtual address of the memory. .It Fa map DMA map to be invalidated. .El .El .Sh RETURN VALUES Behavior is undefined if invalid arguments are passed to any of the above functions. If sufficient resources cannot be allocated for a given transaction, .Er ENOMEM is returned. All routines that are not of type, .Vt void , will return 0 on success or an error code, as discussed above. .Pp All .Vt void routines will succeed if provided with valid arguments. .Sh SEE ALSO .Xr devclass 9 , .Xr device 9 , .Xr driver 9 , .Xr rman 9 , .Xr vslock 9 .Pp .Rs .%A "Jason R. Thorpe" .%T "A Machine-Independent DMA Framework for NetBSD" .%J "Proceedings of the Summer 1998 USENIX Technical Conference" .%Q "USENIX Association" .%D "June 1998" .Re .Sh HISTORY The .Nm interface first appeared in .Nx 1.3 . .Pp The .Nm API was adopted from .Nx for use in the CAM SCSI subsystem. The alterations to the original API were aimed to remove the need for a .Vt bus_dma_segment_t array stored in each .Vt bus_dmamap_t while allowing callers to queue up on scarce resources. .Sh AUTHORS The .Nm interface was designed and implemented by .An Jason R. Thorpe of the Numerical Aerospace Simulation Facility, NASA Ames Research Center. Additional input on the .Nm design was provided by .An -nosplit .An Chris Demetriou , .An Charles Hannum , .An Ross Harvey , .An Matthew Jacob , .An Jonathan Stone , and .An Matt Thomas . .Pp The .Nm interface in .Fx benefits from the contributions of .An Justin T. Gibbs , .An Peter Wemm , .An Doug Rabson , .An Matthew N. Dodd , .An Sam Leffler , .An Maxime Henrion , .An Jake Burkholder , .An Takahashi Yoshihiro , .An Scott Long and many others. .Pp This manual page was written by .An Hiten M. Pandya and .An Justin T. Gibbs . Index: head/share/man/man9/device_find_child.9 =================================================================== --- head/share/man/man9/device_find_child.9 (revision 147397) +++ head/share/man/man9/device_find_child.9 (revision 147398) @@ -1,62 +1,62 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 1998 Doug Rabson .\" .\" All rights reserved. .\" .\" This program is free software. .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 February 8, 2005 .Dt DEVICE_FIND_CHILD 9 .Os .Sh NAME .Nm device_find_child .Nd search for a child of a device .Sh SYNOPSIS .In sys/param.h .In sys/bus.h .Ft device_t .Fn device_find_child "device_t dev" "const char *classname" "int unit" .Sh DESCRIPTION This function looks for a specific child of .Dv dev . with the given .Fa classname and .Fa unit . If .Fa unit -is -1, it returns the first child of -.Dv dev +is \-1, it returns the first child of +.Fa dev with a matching .Fa classname -(that is, the one with the lowest unit.) +(that is, the one with the lowest unit). .Sh RETURN VALUES If it exists, the child device is returned, otherwise NULL. .Sh SEE ALSO .Xr device_add_child 9 .Sh AUTHORS This manual page was written by .An Doug Rabson . Index: head/share/man/man9/ifnet.9 =================================================================== --- head/share/man/man9/ifnet.9 (revision 147397) +++ head/share/man/man9/ifnet.9 (revision 147398) @@ -1,1354 +1,1354 @@ .\" -*- Nroff -*- .\" Copyright 1996, 1997 Massachusetts Institute of Technology .\" .\" Permission to use, copy, modify, and distribute this software and .\" its documentation for any purpose and without fee is hereby .\" granted, provided that both the above copyright notice and this .\" permission notice appear in all copies, that both the above .\" copyright notice and this permission notice appear in all .\" supporting documentation, and that the name of M.I.T. not be used .\" in advertising or publicity pertaining to distribution of the .\" software without specific, written prior permission. M.I.T. makes .\" no representations about the suitability of this software for any .\" purpose. It is provided "as is" without express or implied .\" warranty. .\" .\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS .\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT .\" SHALL M.I.T. 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 June 8, 2004 +.Dd June 10, 2005 .Os .Dt IFNET 9 .Sh NAME .Nm ifnet , .Nm ifaddr , .Nm ifqueue , .Nm if_data .Nd kernel interfaces for manipulating network interfaces .Sh SYNOPSIS .In sys/param.h .In sys/time.h .In sys/socket.h .In net/if.h .In net/if_var.h .In net/if_types.h .\" .Ss "Interface Manipulation Functions" .Ft "struct ifnet *" .Fn if_alloc "u_char type" .Ft void .Fn if_attach "struct ifnet *ifp" .Ft void .Fn if_detach "struct ifnet *ifp" .Ft void .Fn if_free "struct ifnet *ifp" .Ft void .Fn if_free_type "struct ifnet *ifp" "u_char type" .Ft void .Fn if_down "struct ifnet *ifp" .Ft int .Fn ifioctl "struct socket *so" "u_long cmd" "caddr_t data" "struct thread *td" .Ft int .Fn ifpromisc "struct ifnet *ifp" "int pswitch" .Ft int .Fn if_allmulti "struct ifnet *ifp" "int amswitch" .Ft "struct ifnet *" .Fn ifunit "const char *name" .Ft void .Fn if_up "struct ifnet *ifp" .\" .Ss "Interface Address Functions" .Ft "struct ifaddr *" .Fn ifa_ifwithaddr "struct sockaddr *addr" .Ft "struct ifaddr *" .Fn ifa_ifwithdstaddr "struct sockaddr *addr" .Ft "struct ifaddr *" .Fn ifa_ifwithnet "struct sockaddr *addr" .Ft "struct ifaddr *" .Fn ifaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp" .Ft void .Fn ifafree "struct ifaddr *ifa" .Fn IFAFREE "struct ifaddr *ifa" .\" .Ss "Interface Multicast Address Functions" .Ft int .Fn if_addmulti "struct ifnet *ifp" "struct sockaddr *sa" "struct ifmultiaddr **ifmap" .Ft int .Fn if_delmulti "struct ifnet *ifp" "struct sockaddr *sa" .Ft "struct ifmultiaddr *" .Fn ifmaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp" .Ss "Output queue macros" .Fn IF_DEQUEUE "struct ifqueue *ifq" "struct mbuf *m" .\" .Ss "struct ifnet Member Functions" .Ft void .Fn \*(lp*if_input\*(rp "struct ifnet *ifp" "struct mbuf *m" .Ft int .Fo \*(lp*if_output\*(rp .Fa "struct ifnet *ifp" "struct mbuf *m" .Fa "struct sockaddr *dst" "struct rtentry *rt" .Fc .Ft void .Fn \*(lp*if_start\*(rp "struct ifnet *ifp" .Ft int .Fn \*(lp*if_done\*(rp "struct ifnet *ifp" .Ft int .Fn \*(lp*if_ioctl\*(rp "struct ifnet *ifp" "int cmd" "caddr_t data" .Ft void .Fn \*(lp*if_watchdog\*(rp "struct ifnet *ifp" .Ft int .Fn \*(lp*if_poll_recv\*(rp "struct ifnet *ifp" "int *quotap" .Ft int .Fn \*(lp*if_poll_xmit\*(rp "struct ifnet *ifp" "int *quotap" .Ft void .Fn \*(lp*if_poll_inttrn\*(rp "struct ifnet *ifp" .Ft void .Fn \*(lp*if_poll_slowinput\*(rp "struct ifnet *ifp" "struct mbuf *m" .Ft void .Fn \*(lp*if_init\*(rp "void *if_softc" .Ft int .Fo \*(lp*if_resolvemulti\*(rp .Fa "struct ifnet *ifp" "struct sockaddr **retsa" "struct sockaddr *addr" .Fc .Ss "struct ifaddr member function" .Ft void .Fo \*(lp*ifa_rtrequest\*(rp .Fa "int cmd" "struct rtentry *rt" "struct sockaddr *dst" .Fc .\" .Ss "Global Variables" .Vt extern struct ifnethead ifnet ; .Vt extern struct ifaddr **ifnet_addrs ; .Vt extern int if_index ; .Vt extern int ifqmaxlen ; .Sh DATA STRUCTURES The kernel mechanisms for handling network interfaces reside primarily in the .Vt ifnet , if_data , ifaddr , and .Vt ifmultiaddr structures in .In net/if.h and .In net/if_var.h and the functions named above and defined in .Pa /sys/net/if.c . Those interfaces which are intended to be used by user programs are defined in .In net/if.h ; these include the interface flags, the .Vt if_data structure, and the structures defining the appearance of interface-related messages on the .Xr route 4 routing socket and in .Xr sysctl 3 . The header file .In net/if_var.h defines the kernel-internal interfaces, including the .Vt ifnet , ifaddr , and .Vt ifmultiaddr structures and the functions which manipulate them. (A few user programs will need .In net/if_var.h because it is the prerequisite of some other header file like .In netinet/if_ether.h . Most references to those two files in particular can be replaced by .In net/ethernet.h . ) .Pp The system keeps a linked list of interfaces using the .Li TAILQ macros defined in .Xr queue 3 ; this list is headed by a .Vt "struct ifnethead" called .Va ifnet . The elements of this list are of type .Vt "struct ifnet" , and most kernel routines which manipulate interface as such accept or return pointers to these structures. Each interface structure contains an .Vt if_data structure, which contains statistics and identifying information used by management programs, and which is exported to user programs by way of the .Xr ifmib 4 branch of the .Xr sysctl 3 MIB. Each interface also has a .Li TAILQ of interface addresses, described by .Vt ifaddr structures; the head of the queue is always an .Dv AF_LINK address (see .Xr link_addr 3 ) describing the link layer implemented by the interface (if any). (Some trivial interfaces do not provide any link layer addresses; this structure, while still present, serves only to identify the interface name and index.) .Pp Finally, those interfaces supporting reception of multicast datagrams have a .Li TAILQ of multicast group memberships, described by .Vt ifmultiaddr structures. These memberships are reference-counted. .Pp Interfaces are also associated with an output queue, defined as a .Vt "struct ifqueue" ; this structure is used to hold packets while the interface is in the process of sending another. .Pp .Ss The Vt ifnet Ss structure The fields of .Vt "struct ifnet" are as follows: .Bl -tag -width ".Va if_capabilities" -offset indent .It Va if_softc .Pq Vt "void *" A pointer to the driver's private state block. (Initialized by driver.) .It Va if_l2com .Pq Vt "void *" A pointer to the common data for the interface's layer 2 protocol. (Initialized by .Fn if_alloc . ) .It Va if_link .Pq Fn TAILQ_ENTRY ifnet .Xr queue 3 macro glue. .It Va if_xname .Pq Vt "char *" The name of the interface, (e.g., .Dq Li fxp0 or .Dq Li lo0 ) . (Initialized by driver.) .It Va if_dname .Pq Vt "const char *" The name of the driver. (Initialized by driver.) .It Va if_dunit .Pq Vt int A unique number assigned to each interface managed by a particular driver. Drivers may choose to set this to .Dv IF_DUNIT_NONE if a unit number is not associated with the device. (Initialized by driver.) .It Va if_addrhead .Pq Vt "struct ifaddrhead" The head of the .Xr queue 3 .Li TAILQ containing the list of addresses assigned to this interface. .It Va if_pcount .Pq Vt int A count of promiscuous listeners on this interface, used to reference-count the .Dv IFF_PROMISC flag. .It Va if_bpf .Pq Vt "struct bpf_if *" Opaque per-interface data for the packet filter, .Xr bpf 4 . (Initialized by .Fn bpf_attach . ) .It Va if_index .Pq Vt u_short A unique number assigned to each interface in sequence as it is attached. This number can be used in a .Vt "struct sockaddr_dl" to refer to a particular interface by index (see .Xr link_addr 3 ) . (Initialized by .Fn if_alloc . ) .It Va if_timer .Pq Vt short Number of seconds until the watchdog timer .Fn if_watchdog is called, or zero if the timer is disabled. (Set by driver, decremented by generic watchdog code.) .It Va if_flags .Pq Vt int Flags describing operational parameters of this interface (see below). (Manipulated by both driver and generic code.) .It Va if_capabilities .Pq Vt int Flags describing the capabilities the interface supports (see below). .It Va if_capenable .Pq Vt int Flags describing the enabled capabilities of the interface (see below). .\" .It Va if_ipending .\" Interrupt-pending bits for polled operation: .\" .Dv IFI_XMIT .\" (transmit complete interrupt) .\" and .\" .Dv IFI_RECV .\" (received packet ready interrupt). .\" See the .\" .Sx Polling .\" section, below. .\" (Manipulated by driver.) .It Va if_linkmib .Pq Vt "void *" A pointer to an interface-specific MIB structure exported by .Xr ifmib 4 . (Initialized by driver.) .It Va if_linkmiblen .Pq Vt size_t The size of said structure. (Initialized by driver.) .It Va if_data .Pq Vt "struct if_data" More statistics and information; see .Sx "The if_data structure" , below. (Initialized by driver, manipulated by both driver and generic code.) .It Va if_snd .Pq Vt "struct ifqueue" The output queue. (Manipulated by driver.) .\".It Va if_poll_slowq .\".Pq Vt "struct ifqueue *" .\"A pointer to the input queue for devices which do not support polling .\"well. .\"See the .\".Sx Polling .\"section, below. .\"(Initialized by driver.) .El .Pp There are in addition a number of function pointers which the driver must initialize to complete its interface with the generic interface layer: .Bl -ohang -offset indent .It Fn if_input Pass a packet to an appropriate upper layer as determined from the link-layer header of the packet. This routine is to be called from an interrupt handler or used to emulate reception of a packet on this interface. A single function implementing .Fn if_input can be shared among multiple drivers utilizing the same link-layer framing, e.g., Ethernet. .It Fn if_output Output a packet on interface .Fa ifp , or queue it on the output queue if the interface is already active. .It Fn if_start Start queued output on an interface. This function is exposed in order to provide for some interface classes to share a .Fn if_output among all drivers. .Fn if_start may only be called when the .Dv IFF_OACTIVE flag is not set. (Thus, .Dv IFF_OACTIVE does not literally mean that output is active, but rather that the device's internal output queue is full.) .It Fn if_done Not used. We are not even sure what it was ever for. The prototype is faked. .It Fn if_ioctl Process interface-related .Xr ioctl 2 requests (defined in .In sys/sockio.h ) . Preliminary processing is done by the generic routine .Fn ifioctl to check for appropriate privileges, locate the interface being manipulated, and perform certain generic operations like twiddling flags and flushing queues. See the description of .Fn ifioctl below for more information. .It Fn if_watchdog Routine called by the generic code when the watchdog timer, .Va if_timer , expires. Usually this will reset the interface. .\" .It Fn if_poll_recv .\" .It Fn if_poll_xmit .\" .It Fn if_poll_slowinput .\" .It Fn if_poll_intren .\" See the .\" .Sx Polling .\" section, below. .It Fn if_init Initialize and bring up the hardware, e.g., reset the chip and the watchdog timer and enable the receiver unit. Should mark the interface running, but not active .Dv ( IFF_RUNNING , ~IIF_OACTIVE ) . .It Fn if_resolvemulti Check the requested multicast group membership, .Fa addr , for validity, and if necessary compute a link-layer group which corresponds to that address which is returned in .Fa *retsa . Returns zero on success, or an error code on failure. .El .Ss "Interface Flags" Interface flags are used for a number of different purposes. Some flags simply indicate information about the type of interface and its capabilities; others are dynamically manipulated to reflect the current state of the interface. Flags of the former kind are marked .Aq S in this table; the latter are marked .Aq D . .Pp The macro .Dv IFF_CANTCHANGE defines the bits which cannot be set by a user program using the .Dv SIOCSIFFLAGS command to .Xr ioctl 2 ; these are indicated by an asterisk .Pq Ql * in the following listing. .Pp .Bl -tag -width ".Dv IFF_POINTOPOINT" -offset indent -compact .It Dv IFF_UP .Aq D The interface has been configured up by the user-level code. .It Dv IFF_BROADCAST .Aq S* The interface supports broadcast. .It Dv IFF_DEBUG .Aq D Used to enable/disable driver debugging code. .It Dv IFF_LOOPBACK .Aq S The interface is a loopback device. .It Dv IFF_POINTOPOINT .Aq S* The interface is point-to-point; .Dq broadcast address is actually the address of the other end. .It Dv IFF_RUNNING .Aq D* The interface has been configured and dynamic resources were successfully allocated. Probably only useful internal to the interface. .It Dv IFF_NOARP .Aq D Disable network address resolution on this interface. .It Dv IFF_PROMISC .Aq D* This interface is in promiscuous mode. .It Dv IFF_PPROMISC .Aq D This interface is in the permanently promiscuous mode (implies .Dv IFF_PROMISC ) . .It Dv IFF_ALLMULTI .Aq D* This interface is in all-multicasts mode (used by multicast routers). .It Dv IFF_OACTIVE .Aq D* The interface's hardware output queue (if any) is full; output packets are to be queued. .It Dv IFF_SIMPLEX .Aq S* The interface cannot hear its own transmissions. .It Dv IFF_LINK0 .It Dv IFF_LINK1 .It Dv IFF_LINK2 .Aq D Control flags for the link layer. (Currently abused to select among multiple physical layers on some devices.) .It Dv IFF_MULTICAST .Aq S* This interface supports multicast. .It Dv IFF_POLLING .Aq D* The interface is in .Xr polling 4 mode. See .Sx Interface Capabilities Flags for details. .El .Ss "Interface Capabilities Flags" Interface capabilities are specialized features an interface may or may not support. These capabilities are very hardware-specific and allow, when enabled, to offload specific network processing to the interface or to offer a particular feature for use by other kernel parts. .Pp It should be stressed that a capability can be completely uncontrolled (i.e., stay always enabled with no way to disable it) or allow limited control over itself (e.g., depend on another capability's state.) Such peculiarities are determined solely by the hardware and driver of a particular interface. Only the driver possesses the knowledge on whether and how the interface capabilities can be controlled. Consequently, capabilities flags in .Va if_capenable should never be modified directly by kernel code other than the interface driver. The command .Dv SIOCSIFCAP to .Fn ifioctl is the dedicated means to attempt altering .Va if_capenable on an interface. Userland code shall use .Xr ioctl 2 . .Pp The following capabilities are currently supported by the system: .Bl -tag -width ".Dv IFCAP_VLAN_HWTAGGING" -offset indent .It Dv IFCAP_NETCONS This interface can be a network console. .It Dv IFCAP_POLLING This interface supports .Xr polling 4 . See below for details. .It Dv IFCAP_RXCSUM This interface can do checksum validation on receiving data. Some interfaces do not have sufficient buffer storage to store frames above a certain MTU-size completely. The driver for the interface might disable hardware checksum validation if the MTU is set above the hardcoded limit. .It Dv IFCAP_TXCSUM This interface can do checksum calculation on transmitting data. .It Dv IFCAP_HWCSUM A shorthand for .Pq Dv IFCAP_RXCSUM | IFCAP_TXCSUM . .It Dv IFCAP_VLAN_HWTAGGING This interface can do VLAN tagging on output and demultiplex frames by their VLAN tag on input. .It Dv IFCAP_VLAN_MTU The .Xr vlan 4 driver can operate over this interface in software tagging mode without having to decrease MTU on .Xr vlan 4 interfaces below 1500 bytes. This implies the ability of this interface to cope with frames somewhat longer than permitted by the Ethernet specification. .It Dv IFCAP_JUMBO_MTU This Ethernet interface can transmit and receive frames up to 9000 bytes long. .El .Pp The ability of advanced network interfaces to offload certain computational tasks from the host CPU to the board is limited mostly to TCP/IP. Therefore a separate field associated with an interface (see .Va ifnet.if_data.ifi_hwassist below) keeps a detailed description of its enabled capabilities specific to TCP/IP processing. The TCP/IP module consults the field to see which tasks can be done on an .Em outgoing packet by the interface. The flags defined for that field are a superset of those for .Va mbuf.m_pkthdr.csum_flags , namely: .Bl -tag -width ".Dv CSUM_FRAGMENT" -offset indent .It Dv CSUM_IP The interface will compute IP checksums. .It Dv CSUM_TCP The interface will compute TCP checksums. .It Dv CSUM_UDP The interface will compute UDP checksums. .It Dv CSUM_IP_FRAGS The interface can compute a TCP or UDP checksum for a packet fragmented by the host CPU. Makes sense only along with .Dv CSUM_TCP or .Dv CSUM_UDP . .It Dv CSUM_FRAGMENT The interface will do the fragmentation of IP packets if necessary. The host CPU does not need to care about MTU on this interface as long as a packet to transmit through it is an IP one and it does not exceed the size of the hardware buffer. .El .Pp An interface notifies the TCP/IP module about the tasks the former has performed on an .Em incoming packet by setting the corresponding flags in the field .Va mbuf.m_pkthdr.csum_flags of the .Vt mbuf chain containing the packet. See .Xr mbuf 9 for details. .Pp The capability of a network interface to operate in .Xr polling 4 mode involves several flags in different global variables and per-interface fields. First, there is a system-wide .Xr sysctl 8 master switch named .Va kern.polling.enable , which can toggle .Xr polling 4 globally. If that variable is set to non-zero, .Xr polling 4 will be used on those devices where it is enabled individually. Otherwise, .Xr polling 4 will not be used in the system. Second, the capability flag .Dv IFCAP_POLLING set in interface's .Va if_capabilities indicates support for .Xr polling 4 on the particular interface. If set in .Va if_capabilities , the same flag can be marked or cleared in the interface's .Va if_capenable , thus initiating switch of the interface to .Xr polling 4 mode or interrupt mode, respectively. The actual mode change will occur at an implementation-specific moment in the future, e.g., during the next interrupt or .Xr polling 4 cycle. And finally, if the mode transition has been successful, the flag .Dv IFF_POLLING is marked or cleared in the interface's .Va if_flags to indicate the current mode of the interface. .Ss The Vt if_data Ss Structure In .Bx 4.4 , a subset of the interface information believed to be of interest to management stations was segregated from the .Vt ifnet structure and moved into its own .Vt if_data structure to facilitate its use by user programs. The following elements of the .Vt if_data structure are initialized by the interface and are not expected to change significantly over the course of normal operation: .Bl -tag -width ".Va ifi_lastchange" -offset indent .It Va ifi_type .Pq Vt u_char The type of the interface, as defined in .In net/if_types.h and described below in the .Sx "Interface Types" section. .It Va ifi_physical .Pq Vt u_char Intended to represent a selection of physical layers on devices which support more than one; never implemented. .It Va ifi_addrlen .Pq Vt u_char Length of a link-layer address on this device, or zero if there are none. Used to initialized the address length field in .Vt sockaddr_dl structures referring to this interface. .It Va ifi_hdrlen .Pq Vt u_char Maximum length of any link-layer header which might be prepended by the driver to a packet before transmission. The generic code computes the maximum over all interfaces and uses that value to influence the placement of data in .Vt mbuf Ns s to attempt to ensure that there is always sufficient space to prepend a link-layer header without allocating an additional .Vt mbuf . .\" (See .\" .Xr mbuf 9 . ) .\" .It Va ifi_recvquota .\" .Pq Vt u_char .\" Number of packets the interface is permitted to receive at one time .\" when in polled mode. .\" .It Va ifi_xmitquota .\" .Pq Vt u_char .\" Number of packets the interface is permitted to queue for transmission .\" at one time when in polled mode. .\" There is some controversy over .\" whether such a restriction makes any sense at all. .It Va ifi_datalen .Pq Vt u_char Length of the .Vt if_data structure. Allows some stabilization of the routing socket ABI in the face of increases in the length of .Vt struct ifdata . .It Va ifi_mtu .Pq Vt u_long The maximum transmission unit of the medium, exclusive of any link-layer overhead. .It Va ifi_metric .Pq Vt u_long A dimensionless metric interpreted by a user-mode routing process. .It Va ifi_baudrate .Pq Vt u_long The line rate of the interface, in bits per second. .It Va ifi_hwassist .Pq Vt u_long A detailed interpretation of the capabilities to offload computational tasks for .Em outgoing packets. The interface driver must keep this field in accord with the current value of .Va if_capenable . .It Va ifi_epoch .Pq Vt time_t The system uptime when interface was attached or the statistics below were reset. This is intended to be used to set the SNMP variable .Va ifCounterDiscontinuityTime . It may also be used to determine if two successive queries for an interface of the same index have returned results for the same interface. .El .Pp The structure additionally contains generic statistics applicable to a variety of different interface types (except as noted, all members are of type .Vt u_long ) : .Bl -tag -width ".Va ifi_lastchange" -offset indent .It Va ifi_link_state .Pq Vt u_char The current link state of Ethernet interfaces. See the .Sx Interface Link States section for possible values. .It Va ifi_ipackets Number of packets received. .It Va ifi_ierrors Number of receive errors detected (e.g., FCS errors, DMA overruns, etc.). More detailed breakdowns can often be had by way of a link-specific MIB. .It Va ifi_opackets Number of packets transmitted. .It Va ifi_oerrors Number of output errors detected (e.g., late collisions, DMA overruns, etc.). More detailed breakdowns can often be had by way of a link-specific MIB. .It Va ifi_collisions Total number of collisions detected on output for CSMA interfaces. (This member is sometimes [ab]used by other types of interfaces for other output error counts.) .It Va ifi_ibytes Total traffic received, in bytes. .It Va ifi_obytes Total traffic transmitted, in bytes. .It Va ifi_imcasts Number of packets received which were sent by link-layer multicast. .It Va ifi_omcasts Number of packets sent by link-layer multicast. .It Va ifi_iqdrops Number of packets dropped on input. Rarely implemented. .It Va ifi_noproto Number of packets received for unknown network-layer protocol. .\" .It Va ifi_recvtiming .\" Amount of time, in microseconds, spent to receive an average packet on .\" this interface. .\" See the .\" .Sx Polling .\" section, below. .\" .It Va ifi_xmittiming .\" Amount of time, in microseconds, spent to service a transmit-complete .\" interrupt on this interface. .\" See the .\" .Sx Polling .\" section, below. .It Va ifi_lastchange .Pq Vt "struct timeval" The time of the last administrative change to the interface (as required for .Tn SNMP ) . .El .Ss Interface Types The header file .In net/if_types.h defines symbolic constants for a number of different types of interfaces. The most common are: .Pp .Bl -tag -offset indent -width ".Dv IFT_PROPVIRTUAL" -compact .It Dv IFT_OTHER none of the following .It Dv IFT_ETHER Ethernet .It Dv IFT_ISO88023 ISO 8802-3 CSMA/CD .It Dv IFT_ISO88024 ISO 8802-4 Token Bus .It Dv IFT_ISO88025 ISO 8802-5 Token Ring .It Dv IFT_ISO88026 ISO 8802-6 DQDB MAN .It Dv IFT_FDDI FDDI .It Dv IFT_PPP Internet Point-to-Point Protocol .Pq Xr ppp 8 .It Dv IFT_LOOP The loopback .Pq Xr lo 4 interface .It Dv IFT_SLIP Serial Line IP .It Dv IFT_PARA Parallel-port IP .Pq Dq Tn PLIP .It Dv IFT_ATM Asynchronous Transfer Mode .El .Ss Interface Link States The following link states are currently defined: .Pp .Bl -tag -offset indent -width ".Dv LINK_STATE_UNKNOWN" -compact .It Dv LINK_STATE_UNKNOWN The link is in an invalid or unknown state. .It Dv LINK_STATE_DOWN The link is down. .It Dv LINK_STATE_UP The link is up. .El .Ss The Vt ifaddr Ss Structure Every interface is associated with a list (or, rather, a .Li TAILQ ) of addresses, rooted at the interface structure's .Va if_addrlist member. The first element in this list is always an .Dv AF_LINK address representing the interface itself; multi-access network drivers should complete this structure by filling in their link-layer addresses after calling .Fn if_attach . Other members of the structure represent network-layer addresses which have been configured by means of the .Dv SIOCAIFADDR command to .Xr ioctl 2 , called on a socket of the appropriate protocol family. The elements of this list consist of .Vt ifaddr structures. Most protocols will declare their own protocol-specific interface address structures, but all begin with a .Vt "struct ifaddr" which provides the most-commonly-needed functionality across all protocols. Interface addresses are reference-counted. .Pp The members of .Vt "struct ifaddr" are as follows: .Bl -tag -width ".Va ifa_rtrequest" -offset indent .It Va ifa_addr .Pq Vt "struct sockaddr *" The local address of the interface. .It Va ifa_dstaddr .Pq Vt "struct sockaddr *" The remote address of point-to-point interfaces, and the broadcast address of broadcast interfaces. .Va ( ifa_broadaddr is a macro for .Va ifa_dstaddr . ) .It Va ifa_netmask .Pq Vt "struct sockaddr *" The network mask for multi-access interfaces, and the confusion generator for point-to-point interfaces. .It Va ifa_ifp .Pq Vt "struct ifnet *" A link back to the interface structure. .It Va ifa_link .Pq Fn TAILQ_ENTRY ifaddr .Xr queue 3 glue for list of addresses on each interface. .It Va ifa_rtrequest See below. .It Va ifa_flags .Pq Vt u_short Some of the flags which would be used for a route representing this address in the route table. .It Va ifa_refcnt .Pq Vt short The reference count. .It Va ifa_metric .Pq Vt int A metric associated with this interface address, for the use of some external routing protocol. .El .Pp References to .Vt ifaddr structures are gained manually, by incrementing the .Va ifa_refcnt member. References are released by calling either the .Fn ifafree function or the .Fn IFAFREE macro. .Pp .Fn ifa_rtrequest is a pointer to a function which receives callouts from the routing code .Pq Fn rtrequest to perform link-layer-specific actions upon requests to add, resolve, or delete routes. The .Fa cmd argument indicates the request in question: .Dv RTM_ADD , RTM_RESOLVE , or .Dv RTM_DELETE . The .Fa rt argument is the route in question; the .Fa dst argument is the specific destination being manipulated for .Dv RTM_RESOLVE , or a null pointer otherwise. .Sh FUNCTIONS The functions provided by the generic interface code can be divided into two groups: those which manipulate interfaces, and those which manipulate interface addresses. In addition to these functions, there may also be link-layer support routines which are used by a number of drivers implementing a specific link layer over different hardware; see the documentation for that link layer for more details. .Ss The Vt ifmultiaddr Ss Structure Every multicast-capable interface is associated with a list of multicast group memberships, which indicate at a low level which link-layer multicast addresses (if any) should be accepted, and at a high level, in which network-layer multicast groups a user process has expressed interest. .Pp The elements of the structure are as follows: .Bl -tag -width ".Va ifma_refcount" -offset indent .It Va ifma_link .Pq Fn LIST_ENTRY ifmultiaddr .Xr queue 3 macro glue. .It Va ifma_addr .Pq Vt "struct sockaddr *" A pointer to the address which this record represents. The memberships for various address families are stored in arbitrary order. .It Va ifma_lladdr .Pq Vt "struct sockaddr *" A pointer to the link-layer multicast address, if any, to which the network-layer multicast address in .Va ifma_addr is mapped, else a null pointer. If this element is non-nil, this membership also holds an invisible reference to another membership for that link-layer address. .It Va ifma_refcount .Pq Vt u_int A reference count of requests for this particular membership. .El .Ss Interface Manipulation Functions .Bl -ohang -offset indent .It Fn if_alloc -Allocate and initialize an -.Fa ifp . +Allocate and initialize +.Vt "struct ifnet" . Initalization includes the allocation of an interface index and may include the allocation of a .Fa type specific structure in .Va if_l2com . .It Fn if_attach Link the specified interface .Fa ifp into the list of network interfaces. Also initialize the list of addresses on that interface, and create a link-layer .Vt ifaddr structure to be the first element in that list. (A pointer to this address structure is saved in the global array .Va ifnet_addrs . ) The .Fa ifp must have been allocted by .Fn if_alloc . .It Fn if_detach Shut down and unlink the specified .Fa ifp from the interface list. .It Fn if_free Free the given .Fa ifp back to the system. The interface must have been previously detached if it was ever attached. .It Fn if_free_type Identical to .Fn if_free except that the given .Fa type -is used to free +is used to free .Va if_l2com instead of the type in .Va if_type . This is intended for use with drivers that change their interface type. .It Fn if_down Mark the interface .Fa ifp as down (i.e., .Dv IFF_UP is not set), flush its output queue, notify protocols of the transition, and generate a message from the .Xr route 4 routing socket. .It Fn if_up Mark the interface .Fa ifp as up, notify protocols of the transition, and generate a message from the .Xr route 4 routing socket. .It Fn ifpromisc Add or remove a promiscuous reference to .Fa ifp . If .Fa pswitch is true, add a reference; if it is false, remove a reference. On reference count transitions from zero to one and one to zero, set the .Dv IFF_PROMISC flag appropriately and call .Fn if_ioctl to set up the interface in the desired mode. .It Fn if_allmulti As .Fn ifpromisc , but for the all-multicasts .Pq Dv IFF_ALLMULTI flag instead of the promiscuous flag. .It Fn ifunit Return an .Vt ifnet pointer for the interface named .Fa name . .It Fn ifioctl Process the ioctl request .Fa cmd , issued on socket .Fa so by thread .Fa td , with data parameter .Fa data . This is the main routine for handling all interface configuration requests from user mode. It is ordinarily only called from the socket-layer .Xr ioctl 2 handler, and only for commands with class .Sq Li i . Any unrecognized commands will be passed down to socket .Fa so Ns 's protocol for further interpretation. The following commands are handled by .Fn ifioctl : .Pp .Bl -tag -width ".Dv OSIOCGIFNETMASK" -offset indent -compact .It Dv SIOCGIFCONF .It Dv OSIOCGIFCONF Get interface configuration. (No call-down to driver.) .Pp .It Dv SIOCSIFNAME Set the interface name. .Dv RTM_IFANNOUNCE departure and arrival messages are sent so that routing code that relies on the interface name will update its interface list. Caller must have appropriate privilege. (No call-down to driver.) .It Dv SIOCGIFCAP .It Dv SIOCGIFFLAGS .It Dv SIOCGIFMETRIC .It Dv SIOCGIFMTU .It Dv SIOCGIFPHYS Get interface capabilities, flags, metric, MTU, medium selection. (No call-down to driver.) .Pp .It Dv SIOCSIFCAP Enable or disable interface capabilities. Caller must have appropriate privilege. Before a call to the driver-specific .Fn if_ioctl routine, the requested mask for enabled capabilities is checked against the mask of capabilities supported by the interface, .Va if_capabilities . Requesting to enable an unsupported capability is invalid. The rest is supposed to be done by the driver, which includes updating .Va if_capenable and .Va if_data.ifi_hwassist appropriately. .Pp .It Dv SIOCSIFFLAGS Change interface flags. Caller must have appropriate privilege. If a change to the .Dv IFF_UP flag is requested, .Fn if_up or .Fn if_down is called as appropriate. Flags listed in .Dv IFF_CANTCHANGE are masked off, and the field .Va if_flags in the interface structure is updated. Finally, the driver .Fn if_ioctl routine is called to perform any setup requested. .Pp .It Dv SIOCSIFMETRIC .It Dv SIOCSIFPHYS Change interface metric or medium. Caller must have appropriate privilege. .Pp .It Dv SIOCSIFMTU Change interface MTU. Caller must have appropriate privilege. MTU values less than 72 or greater than 65535 are considered invalid. The driver .Fn if_ioctl routine is called to implement the change; it is responsible for any additional sanity checking and for actually modifying the MTU in the interface structure. .Pp .It Dv SIOCADDMULTI .It Dv SIOCDELMULTI Add or delete permanent multicast group memberships on the interface. Caller must have appropriate privilege. The .Fn if_addmulti or .Fn if_delmulti function is called to perform the operation; qq.v. .Pp .It Dv SIOCSIFDSTADDR .It Dv SIOCSIFADDR .It Dv SIOCSIFBRDADDR .It Dv SIOCSIFNETMASK The socket's protocol control routine is called to implement the requested action. .Pp .It Dv OSIOGIFADDR .It Dv OSIOCGIFDSTADDR .It Dv OSIOCGIFBRDADDR .It Dv OSIOCGIFNETMASK The socket's protocol control routine is called to implement the requested action. On return, .Vt sockaddr structures are converted into old-style (no .Va sa_len member). .El .El .Pp .Fn if_down , .Fn ifioctl , .Fn ifpromisc , and .Fn if_up must be called at .Fn splnet or higher. .Ss "Interface Address Functions" Several functions exist to look up an interface address structure given an address. .Fn ifa_ifwithaddr returns an interface address with either a local address or a broadcast address precisely matching the parameter .Fa addr . .Fn ifa_ifwithdstaddr returns an interface address for a point-to-point interface whose remote .Pq Dq destination address is .Fa addr . .Pp .Fn ifa_ifwithnet returns the most specific interface address which matches the specified address, .Fa addr , subject to its configured netmask, or a point-to-point interface address whose remote address is .Fa addr if one is found. .Pp .Fn ifaof_ifpforaddr returns the most specific address configured on interface .Fa ifp which matches address .Fa addr , subject to its configured netmask. If the interface is point-to-point, only an interface address whose remote address is precisely .Fa addr will be returned. .Pp All of these functions return a null pointer if no such address can be found. .Ss "Interface Multicast Address Functions" The .Fn if_addmulti , .Fn if_delmulti , and .Fn ifmaof_ifpforaddr functions provide support for requesting and relinquishing multicast group memberships, and for querying an interface's membership list, respectively. The .Fn if_addmulti function takes a pointer to an interface, .Fa ifp , and a generic address, .Fa sa . It also takes a pointer to a .Vt "struct ifmultiaddr *" which is filled in on successful return with the address of the group membership control block. The .Fn if_addmulti function performs the following four-step process: .Bl -enum -offset indent .It Call the interface's .Fn if_resolvemulti entry point to determine the link-layer address, if any, corresponding to this membership request, and also to give the link layer an opportunity to veto this membership request should it so desire. .It Check the interface's group membership list for a pre-existing membership for this group. If one is not found, allocate a new one; if one is, increment its reference count. .It If the .Fn if_resolvemulti routine returned a link-layer address corresponding to the group, repeat the previous step for that address as well. .It If the interface's multicast address filter needs to be changed because a new membership was added, call the interface's .Fn if_ioctl routine (with a .Fa cmd argument of .Dv SIOCADDMULTI ) to request that it do so. .El .Pp The .Fn if_delmulti function, given an interface .Fa ifp and an address, .Fa sa , reverses this process. Both functions return zero on success, or a standard error number on failure. .Pp The .Fn ifmaof_ifpforaddr function examines the membership list of interface .Fa ifp for an address matching .Fa addr , and returns a pointer to that .Vt "struct ifmultiaddr" if one is found, else it returns a null pointer. .Sh SEE ALSO .Xr ioctl 2 , .Xr link_addr 3 , .Xr queue 3 , .Xr sysctl 3 , .Xr bpf 4 , .Xr ifmib 4 , .Xr lo 4 , .Xr netintro 4 , .Xr polling 4 , .Xr config 8 , .Xr ppp 8 , .Xr mbuf 9 , .Xr rtentry 9 .Rs .%A Gary R. Wright .%A W. Richard Stevens .%B TCP/IP Illustrated .%V Vol. 2 .%O Addison-Wesley, ISBN 0-201-63354-X .Re .Sh AUTHORS This manual page was written by .An Garrett A. Wollman . Index: head/share/man/man9/kthread.9 =================================================================== --- head/share/man/man9/kthread.9 (revision 147397) +++ head/share/man/man9/kthread.9 (revision 147398) @@ -1,299 +1,299 @@ .\" Copyright (c) 2000-2001 .\" The Regents of the University of California. All rights reserved. .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 September 24, 2004 .Dt KTHREAD 9 .Os .Sh NAME .Nm kproc_start , .Nm kproc_shutdown , .Nm kthread_create , .Nm kthread_exit , .Nm kthread_resume , .Nm kthread_suspend , .Nm kthread_suspend_check .Nd kernel threads .Sh SYNOPSIS .In sys/kthread.h .Ft void .Fn kproc_start "const void *udata" .Ft void .Fn kproc_shutdown "void *arg" "int howto" .Ft int .Fn kthread_create "void (*func)(void *)" "void *arg" "struct proc **newpp" "int flags" "int pages" "const char *fmt" "..." .Ft void .Fn kthread_exit "int ecode" .Ft int .Fn kthread_resume "struct proc *p" .Ft int .Fn kthread_suspend "struct proc *p" "int timo" .Ft void .Fn kthread_suspend_check "struct proc *p" .Sh DESCRIPTION The function .Fn kproc_start is used to start .Dq internal daemons such as bufdaemon, pagedaemon, vmdaemon, and the syncer and is intended to be called from .Xr SYSINIT 9 . The .Fa udata argument is actually a pointer to a .Li struct kproc_desc which describes the kernel thread that should be created: .Bd -literal -offset indent struct kproc_desc { char *arg0; void (*func)(void); struct proc **global_procpp; }; .Ed .Pp The structure members are used by .Fn kproc_start as follows: .Bl -tag -width "global_procpp" -offset indent .It Va arg0 String to be used for the name of the process. This string will be copied into the .Va p_comm member of the new process' .Li struct proc . .It Va func The main function for this kernel process to run. .It Va global_procpp A pointer to a .Li struct proc pointer that should be updated to point to the newly created process' process structure. If this variable is .Dv NULL , then it is ignored. .El .Pp The .Fn kthread_create function is used to create a kernel thread. The new thread shares its address space with process 0, the swapper process, and runs in kernel mode only. The .Fa func argument specifies the function that the thread should execute. The .Fa arg argument is an arbitrary pointer that is passed in as the only argument to .Fa func when it is called by the new process. The .Fa newpp pointer points to a .Li struct proc pointer that is to be updated to point to the newly created process. If this argument is .Dv NULL , then it is ignored. The .Fa flags argument specifies a set of flags as described in .Xr rfork 2 . The .Fa pages argument specifies the size of the new kernel thread's stack in pages. If 0 is used, the default kernel stack size is allocated. The rest of the arguments form a .Xr printf 9 argument list that is used to build the name of the new thread and is stored in the .Va p_comm member of the new thread's .Li struct proc . .Pp The .Fn kthread_exit function is used to terminate kernel threads. It should be called by the main function of the kernel thread rather than letting the main function return to its caller. The .Fa ecode argument specifies the exit status of the thread. While exiting, the function .Xr exit1 9 will initiate a call to .Xr wakeup 9 on the thread handle. .Pp The .Fn kthread_resume , .Fn kthread_suspend , and .Fn kthread_suspend_check functions are used to suspend and resume a kernel thread. During the main loop of its execution, a kernel thread that wishes to allow itself to be suspended should call .Fn kthread_suspend_check passing in .Va curproc as the only argument. This function checks to see if the kernel thread has been asked to suspend. If it has, it will .Xr tsleep 9 until it is told to resume. Once it has been told to resume it will return allowing execution of the kernel thread to continue. The other two functions are used to notify a kernel thread of a suspend or resume request. The .Fa p argument points to the .Li struct proc of the kernel thread to suspend or resume. For .Fn kthread_suspend , the .Fa timo argument specifies a timeout to wait for the kernel thread to acknowledge the suspend request and suspend itself. .Pp The .Fn kproc_shutdown function is meant to be registered as a shutdown event for kernel threads that need to be suspended voluntarily during system shutdown so as not to interfere with system shutdown activities. The actual suspension of the kernel thread is done with .Fn kthread_suspend . .Sh RETURN VALUES The .Fn kthread_create , .Fn kthread_resume , and .Fn kthread_suspend functions return zero on success and non-zero on failure. .Sh EXAMPLES This example demonstrates the use of a .Li struct kproc_desc and the functions .Fn kproc_start , .Fn kproc_shutdown , and .Fn kthread_suspend_check to run the .Dq bufdaemon process. .Bd -literal -offset indent static struct proc *bufdaemonproc; static struct kproc_desc buf_kp = { "bufdaemon", buf_daemon, &bufdaemonproc }; SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kproc_start, &buf_kp) static void buf_daemon() { ... /* * This process needs to be suspended prior to shutdown sync. */ EVENTHANDLER_REGISTER(shutdown_pre_sync, kproc_shutdown, bufdaemonproc, SHUTDOWN_PRI_LAST); ... for (;;) { kthread_suspend_check(bufdaemonproc); ... } } .Ed .Sh ERRORS The .Fn kthread_resume and .Fn kthread_suspend functions will fail if: .Bl -tag -width Er .It Bq Er EINVAL The .Fa p argument does not reference a kernel thread. .El .Pp The .Fn kthread_create function will fail if: .Bl -tag -width Er .It Bq Er EAGAIN The system-imposed limit on the total number of processes under execution would be exceeded. The limit is given by the .Xr sysctl 3 MIB variable .Dv KERN_MAXPROC . .It Bq Er EINVAL The .Dv RFCFDG flag was specified in the .Fa flags parameter. .El .Sh SEE ALSO -.Xr exit1 9 , .Xr rfork 2 , +.Xr exit1 9 , .Xr SYSINIT 9 , .Xr wakeup 9 .Sh HISTORY The .Fn kproc_start function first appeared in .Fx 2.2 . The .Fn kproc_shutdown , .Fn kthread_create , .Fn kthread_exit , .Fn kthread_resume , .Fn kthread_suspend , and .Fn kthread_suspend_check functions were introduced in .Fx 4.0 . Prior to .Fx 5.0 , the .Fn kproc_shutdown , .Fn kthread_resume , .Fn kthread_suspend , and .Fn kthread_suspend_check functions were named .Fn shutdown_kproc , .Fn resume_kproc , .Fn shutdown_kproc , and .Fn kproc_suspend_loop , respectively. Index: head/share/man/man9/ktr.9 =================================================================== --- head/share/man/man9/ktr.9 (revision 147397) +++ head/share/man/man9/ktr.9 (revision 147398) @@ -1,145 +1,145 @@ .\" Copyright (c) 2001 John H. Baldwin .\" 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 February 15, 2001 .Dt KTR 9 .Os .Sh NAME .Nm CTR0 , CTR1 , CTR2 , CTR3 , CTR4 , CTR5 .Nd kernel tracing facility .Sh SYNOPSIS .In sys/param.h .In sys/ktr.h .Vt "extern int ktr_cpumask" ; .Vt "extern int ktr_entries" ; .Vt "extern int ktr_extend" ; .Vt "extern int ktr_mask" ; .Vt "extern int ktr_verbose" ; .Vt "extern struct ktr_entry ktr_buf[]" ; .Ft void .Fn CTR0 "u_int mask" "char *format" .Ft void .Fn CTR1 "u_int mask" "char *format" "arg1" .Ft void .Fn CTR2 "u_int mask" "char *format" "arg1" "arg2" .Ft void .Fn CTR3 "u_int mask" "char *format" "arg1" "arg2" "arg3" .Ft void .Fn CTR4 "u_int mask" "char *format" "arg1" "arg2" "arg3" "arg4" .Ft void .Fn CTR5 "u_int mask" "char *format" "arg1" "arg2" "arg3" "arg4" "arg5" .Sh DESCRIPTION KTR provides a circular buffer of events that can be logged in a .Xr printf 9 style fashion. These events can then be dumped with .Xr ddb 4 , .Xr gdb 1 or .Xr ktrdump 8 . .Pp Events are created and logged in the kernel via the .Dv CTR Ns Ar x macros. The first parameter is a mask of event types .Pq Dv KTR_* defined in .In sys/ktr.h . The event will be logged only if any of the event types specified in .Fa mask are enabled in the global event mask stored in .Va ktr_mask . The .Fa format argument is a .Xr printf 9 style format string used to build the text of the event log message. Following the .Fa format string are zero to five arguments referenced by .Fa format . Note that the different macros differ only in the number of arguments each one takes, as indicated by its name. Each event is logged with a timestamp in addition to the log message. .Pp The .Va ktr_entries variable contains the number of entries in the .Va ktr_buf array. These variables are mostly useful for post-mortem crash dump tools to locate the base of the circular trace buffer and its length. .Pp The .Va ktr_mask variable contains the run time mask of events to log. .Pp The CPU event mask is stored in the .Va ktr_cpumask variable. .Pp The .Va ktr_verbose variable stores the verbose flag that controls whether events are logged to the console in addition to the event buffer. .Sh EXAMPLES This example demonstrates the use of tracepoints at the .Dv KTR_PROC logging level. -.Bd -literal -compact +.Bd -literal void mi_switch() { ... /* * Pick a new current process and record its start time. */ ... CTR3(KTR_PROC, "mi_switch: old proc %p (pid %d, %s)", p, p->p_pid, p->p_comm); ... cpu_switch(); ... CTR3(KTR_PROC, "mi_switch: new proc %p (pid %d, %s)", p, p->p_pid, p->p_comm); ... } .Ed .Sh SEE ALSO .Xr ktr 4 , .Xr ktrdump 8 .Sh HISTORY The KTR kernel tracing facility first appeared in .Bsx 3.0 and was imported into .Fx 5.0 . .Sh BUGS Currently there is one global buffer shared among all CPUs. It might be profitable at some point in time to use per-CPU buffers instead so that if one CPU halts or starts spinning, then the log messages it emitted just prior to halting or spinning will not be drowned out by events from the other CPUs. Index: head/share/man/man9/mbuf.9 =================================================================== --- head/share/man/man9/mbuf.9 (revision 147397) +++ head/share/man/man9/mbuf.9 (revision 147398) @@ -1,1113 +1,1113 @@ .\" Copyright (c) 2000 FreeBSD Inc. .\" 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 [your name] 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 August 27, 2004 .Dt MBUF 9 .Os .\" .Sh NAME .Nm mbuf .Nd "memory management in the kernel IPC subsystem" .\" .Sh SYNOPSIS .In sys/param.h .In sys/systm.h .In sys/mbuf.h .\" .Ss Mbuf allocation macros .Fn MGET "struct mbuf *mbuf" "int how" "short type" .Fn MGETHDR "struct mbuf *mbuf" "int how" "short type" .Fn MCLGET "struct mbuf *mbuf" "int how" .Fo MEXTADD .Fa "struct mbuf *mbuf" .Fa "caddr_t buf" .Fa "u_int size" .Fa "void (*free)(void *opt_args)" .Fa "void *opt_args" .Fa "short flags" .Fa "int type" .Fc .Fn MEXTFREE "struct mbuf *mbuf" .Fn MEXT_ADD_REF "struct mbuf *mbuf" .Fn MEXT_REM_REF "struct mbuf *mbuf" .Fn MFREE "struct mbuf *mbuf" "struct mbuf *successor" .\" .Ss Mbuf utility macros .Fn mtod "struct mbuf *mbuf" "type" .Ft int .Fn MEXT_IS_REF "struct mbuf *mbuf" .Fn M_ALIGN "struct mbuf *mbuf" "u_int len" .Fn MH_ALIGN "struct mbuf *mbuf" "u_int len" .Ft int .Fn M_LEADINGSPACE "struct mbuf *mbuf" .Ft int .Fn M_TRAILINGSPACE "struct mbuf *mbuf" .Fn M_MOVE_PKTHDR "struct mbuf *to" "struct mbuf *from" .Fn M_PREPEND "struct mbuf *mbuf" "int len" "int how" .Fn MCHTYPE "struct mbuf *mbuf" "u_int type" .Ft int .Fn M_WRITABLE "struct mbuf *mbuf" .\" .Ss Mbuf allocation functions .Ft struct mbuf * .Fn m_get "int how" "int type" .Ft struct mbuf * .Fn m_getm "struct mbuf *orig" "int len" "int how" "int type" .Ft struct mbuf * .Fn m_getcl "int how" "short type" "int flags" .Ft struct mbuf * .Fn m_getclr "int how" "int type" .Ft struct mbuf * .Fn m_gethdr "int how" "int type" .Ft struct mbuf * .Fn m_free "struct mbuf *mbuf" .Ft void .Fn m_freem "struct mbuf *mbuf" .\" .Ss Mbuf utility functions .Ft void .Fn m_adj "struct mbuf *mbuf" "int len" .Ft int .Fn m_append "struct mbuf *mbuf" "int len" "c_caddr_t cp" .Ft struct mbuf * .Fn m_prepend "struct mbuf *mbuf" "int len" "int how" .Ft struct mbuf * .Fn m_copyup "struct mbuf *mbuf" "int len" "int dstoff" .Ft struct mbuf * .Fn m_pullup "struct mbuf *mbuf" "int len" .Ft struct mbuf * .Fn m_copym "struct mbuf *mbuf" "int offset" "int len" "int how" .Ft struct mbuf * .Fn m_copypacket "struct mbuf *mbuf" "int how" .Ft struct mbuf * .Fn m_dup "struct mbuf *mbuf" "int how" .Ft void .Fn m_copydata "const struct mbuf *mbuf" "int offset" "int len" "caddr_t buf" .Ft void .Fn m_copyback "struct mbuf *mbuf" "int offset" "int len" "caddr_t buf" .Ft struct mbuf * .Fo m_devget .Fa "char *buf" .Fa "int len" .Fa "int offset" .Fa "struct ifnet *ifp" .Fa "void (*copy)(char *from, caddr_t to, u_int len)" .Fc .Ft void .Fn m_cat "struct mbuf *m" "struct mbuf *n" .Ft u_int .Fn m_fixhdr "struct mbuf *mbuf" .Ft void .Fn m_dup_pkthdr "struct mbuf *to" "struct mbuf *from" .Ft void .Fn m_move_pkthdr "struct mbuf *to" "struct mbuf *from" .Ft u_int .Fn m_length "struct mbuf *mbuf" "struct mbuf **last" .Ft struct mbuf * .Fn m_split "struct mbuf *mbuf" "int len" "int how" .Ft int .Fn m_apply "struct mbuf *mbuf" "int off" "int len" "int (*f)(void *arg, void *data, u_int len)" "void *arg" .Ft struct mbuf * .Fn m_getptr "struct mbuf *mbuf" "int loc" "int *off" .Ft struct mbuf * .Fn m_defrag "struct mbuf *m0" "int how" .\" .Sh DESCRIPTION An .Vt mbuf is a basic unit of memory management in the kernel IPC subsystem. Network packets and socket buffers are stored in .Vt mbufs . A network packet may span multiple .Vt mbufs arranged into a .Vt mbuf chain (linked list), which allows adding or trimming network headers with little overhead. .Pp While a developer should not bother with .Vt mbuf internals without serious reason in order to avoid incompatibilities with future changes, it is useful to understand the general structure of an .Vt mbuf . .Pp An .Vt mbuf consists of a variable-sized header and a small internal buffer for data. The total size of an .Vt mbuf , .Dv MSIZE , is a constant defined in .In sys/param.h . The .Vt mbuf header includes: .Pp .Bl -tag -width "m_nextpkt" -offset indent .It Va m_next .Pq Vt struct mbuf * A pointer to the next .Vt mbuf in the .Vt mbuf chain . .It Va m_nextpkt .Pq Vt struct mbuf * A pointer to the next .Vt mbuf chain in the queue. .It Va m_data .Pq Vt caddr_t A pointer to data attached to this .Vt mbuf . .It Va m_len .Pq Vt int The length of the data. .It Va m_type .Pq Vt short The type of the data. .It Va m_flags .Pq Vt int The .Vt mbuf flags. .El .Pp The .Vt mbuf flag bits are defined as follows: .Bd -literal /* mbuf flags */ #define M_EXT 0x0001 /* has associated external storage */ #define M_PKTHDR 0x0002 /* start of record */ #define M_EOR 0x0004 /* end of record */ #define M_RDONLY 0x0008 /* associated data marked read-only */ #define M_PROTO1 0x0010 /* protocol-specific */ #define M_PROTO2 0x0020 /* protocol-specific */ #define M_PROTO3 0x0040 /* protocol-specific */ #define M_PROTO4 0x0080 /* protocol-specific */ #define M_PROTO5 0x0100 /* protocol-specific */ #define M_PROTO6 0x4000 /* protocol-specific (avoid M_BCAST conflict) */ #define M_FREELIST 0x8000 /* mbuf is on the free list */ /* mbuf pkthdr flags (also stored in m_flags) */ #define M_BCAST 0x0200 /* send/received as link-level broadcast */ #define M_MCAST 0x0400 /* send/received as link-level multicast */ #define M_FRAG 0x0800 /* packet is fragment of larger packet */ #define M_FIRSTFRAG 0x1000 /* packet is first fragment */ #define M_LASTFRAG 0x2000 /* packet is last fragment */ .Ed .Pp The available .Vt mbuf types are defined as follows: .Bd -literal /* mbuf types */ #define MT_DATA 1 /* dynamic (data) allocation */ #define MT_HEADER 2 /* packet header */ #define MT_SONAME 8 /* socket name */ #define MT_FTABLE 11 /* fragment reassembly header */ #define MT_CONTROL 14 /* extra-data protocol message */ #define MT_OOBDATA 15 /* expedited data */ .Ed .Pp If the .Dv M_PKTHDR flag is set, a .Vt struct pkthdr Va m_pkthdr is added to the .Vt mbuf header. It contains a pointer to the interface the packet has been received from .Pq Vt struct ifnet Va *rcvif , and the total packet length .Pq Vt int Va len . Optionally, it may also contain an attached list of packet tags .Pq Vt "struct m_tag" . See .Xr mbuf_tags 9 for details. Fields used in offloading checksum calculation to the hardware are kept in .Va m_pkthdr as well. See .Sx HARDWARE-ASSISTED CHECKSUM CALCULATION for details. .Pp If small enough, data is stored in the internal data buffer of an .Vt mbuf . If the data is sufficiently large, another .Vt mbuf may be added to the .Vt mbuf chain , or external storage may be associated with the .Vt mbuf . .Dv MHLEN bytes of data can fit into an .Vt mbuf with the .Dv M_PKTHDR flag set, .Dv MLEN bytes can otherwise. .Pp If external storage is being associated with an .Vt mbuf , the .Va m_ext header is added at the cost of losing the internal data buffer. It includes a pointer to external storage, the size of the storage, a pointer to a function used for freeing the storage, a pointer to an optional argument that can be passed to the function, and a pointer to a reference counter. An .Vt mbuf using external storage has the .Dv M_EXT flag set. .Pp The system supplies a macro for allocating the desired external storage buffer, .Dv MEXTADD . .Pp The allocation and management of the reference counter is handled by the subsystem. The developer can check whether the reference count for the external storage of a given .Vt mbuf is greater than 1 with the .Dv MEXT_IS_REF macro. Similarly, the developer can directly add and remove references, if absolutely necessary, with the use of the .Dv MEXT_ADD_REF and .Dv MEXT_REM_REF macros. .Pp The system also supplies a default type of external storage buffer called an .Vt mbuf cluster . .Vt Mbuf clusters can be allocated and configured with the use of the .Dv MCLGET macro. Each .Vt mbuf cluster is .Dv MCLBYTES in size, where MCLBYTES is a machine-dependent constant. The system defines an advisory macro .Dv MINCLSIZE , which is the smallest amount of data to put into an .Vt mbuf cluster . It is equal to the sum of .Dv MLEN and .Dv MHLEN . It is typically preferable to store data into the data region of an .Vt mbuf , if size permits, as opposed to allocating a separate .Vt mbuf cluster to hold the same data. .\" .Ss Macros and Functions There are numerous predefined macros and functions that provide the developer with common utilities. .\" .Bl -ohang -offset indent .It Fn mtod mbuf type Convert an .Fa mbuf pointer to a data pointer. The macro expands to the data pointer cast to the pointer of the specified .Fa type . .Sy Note : It is advisable to ensure that there is enough contiguous data in .Fa mbuf . See .Fn m_pullup for details. .It Fn MGET mbuf how type Allocate an .Vt mbuf and initialize it to contain internal data. .Fa mbuf will point to the allocated .Vt mbuf on success, or be set to .Dv NULL on failure. The .Fa how argument is to be set to .Dv M_TRYWAIT or .Dv M_DONTWAIT . It specifies whether the caller is willing to block if necessary. If .Fa how is set to .Dv M_TRYWAIT , a failed allocation will result in the caller being put to sleep for a designated kern.ipc.mbuf_wait .Xr ( sysctl 8 tunable) number of ticks. A number of other functions and macros related to .Vt mbufs have the same argument because they may at some point need to allocate new .Vt mbufs . .Pp Programmers should be careful not to confuse the .Vt mbuf allocation flag .Dv M_DONTWAIT with the .Xr malloc 9 allocation flag, .Dv M_NOWAIT . They are not the same. .It Fn MGETHDR mbuf how type Allocate an .Vt mbuf and initialize it to contain a packet header and internal data. See .Fn MGET for details. .It Fn MCLGET mbuf how Allocate and attach an .Vt mbuf cluster to .Fa mbuf . If the macro fails, the .Dv M_EXT flag will not be set in .Fa mbuf . .It Fn M_ALIGN mbuf len Set the pointer .Fa mbuf->m_data to place an object of the size .Fa len at the end of the internal data area of .Fa mbuf , long word aligned. Applicable only if .Fa mbuf is newly allocated with .Fn MGET or .Fn m_get . .It Fn MH_ALIGN mbuf len Serves the same purpose as .Fn M_ALIGN does, but only for .Fa mbuf newly allocated with .Fn MGETHDR or .Fn m_gethdr , or initialized by .Fn m_dup_pkthdr or .Fn m_move_pkthdr . .It Fn M_LEADINGSPACE mbuf Returns the number of bytes available before the beginning of data in .Fa mbuf . .It Fn M_TRAILINGSPACE mbuf Returns the number of bytes available after the end of data in .Fa mbuf . .It Fn M_PREPEND mbuf len how This macro operates on an .Vt mbuf chain . It is an optimized wrapper for .Fn m_prepend that can make use of possible empty space before data (e.g.\& left after trimming of a link-layer header). The new .Vt mbuf chain pointer or .Dv NULL is in .Fa mbuf after the call. .It Fn M_MOVE_PKTHDR to from Using this macro is equivalent to calling .Fn m_move_pkthdr to from . .It Fn M_WRITABLE mbuf This macro will evaluate true if .Fa mbuf is not marked .Dv M_RDONLY and if either .Fa mbuf does not contain external storage or, if it does, then if the reference count of the storage is not greater than 1. The .Dv M_RDONLY flag can be set in .Fa mbuf->m_flags . This can be achieved during setup of the external storage, by passing the .Dv M_RDONLY bit as a .Fa flags argument to the .Fn MEXTADD macro, or can be directly set in individual .Vt mbufs . .It Fn MCHTYPE mbuf type Change the type of .Fa mbuf to .Fa type . This is a relatively expensive operation and should be avoided. .El .Pp The functions are: .Bl -ohang -offset indent .It Fn m_get how type A function version of .Fn MGET for non-critical paths. .It Fn m_getm orig len how type Allocate .Fa len bytes worth of .Vt mbufs and .Vt mbuf clusters if necessary and append the resulting allocated .Vt mbuf chain to the .Vt mbuf chain .Fa orig , if it is .No non- Ns Dv NULL . If the allocation fails at any point, free whatever was allocated and return .Dv NULL . If .Fa orig is .No non- Ns Dv NULL , it will not be freed. It is possible to use .Fn m_getm to either append .Fa len bytes to an existing .Vt mbuf or .Vt mbuf chain (for example, one which may be sitting in a pre-allocated ring) or to simply perform an all-or-nothing .Vt mbuf and .Vt mbuf cluster allocation. .It Fn m_gethdr how type A function version of .Fn MGETHDR for non-critical paths. .It Fn m_getcl how type flags Fetch an .Vt mbuf with a .Vt mbuf cluster attached to it. If one of the allocations fails, the entire allocation fails. This routine is the preferred way of fetching both the .Vt mbuf and .Vt mbuf cluster together, as it avoids having to unlock/relock between allocations. Returns .Dv NULL on failure. .It Fn m_getclr how type Allocate an .Vt mbuf and zero out the data region. .It Fn m_free mbuf Frees .Vt mbuf . Returns .Va m_next of the freed .Vt mbuf . .El .Pp The functions below operate on .Vt mbuf chains . .Bl -ohang -offset indent .It Fn m_freem mbuf Free an entire .Vt mbuf chain , including any external storage. .\" .It Fn m_adj mbuf len Trim .Fa len bytes from the head of an .Vt mbuf chain if .Fa len is positive, from the tail otherwise. .\" .It Fn m_append mbuf len cp Append .Vt len bytes of data .Vt cp to the .Vt mbuf chain . Extend the mbuf chain if the new data does not fit in existing space. .\" .It Fn m_prepend mbuf len how Allocate a new .Vt mbuf and prepend it to the .Vt mbuf chain , handle .Dv M_PKTHDR properly. .Sy Note : It does not allocate any .Vt mbuf clusters , so .Fa len must be less than .Dv MLEN or .Dv MHLEN , depending on the .Dv M_PKTHDR flag setting. .\" .It Fn m_copyup mbuf len dstoff Similar to .Fn m_pullup but copies .Fa len bytes of data into a new mbuf at .Fa dstoff bytes into the mbuf. The .Fa dstoff argument aligns the data and leaves room for a link layer header. -Return the new +Returns the new .Vt mbuf chain on success, and frees the .Vt mbuf chain and returns .Dv NULL on failure. .Sy Note : The function does not allocate .Vt mbuf clusters , so .Fa len + dstoff must be less than .Dv MHLEN . .\" .It Fn m_pullup mbuf len Arrange that the first .Fa len bytes of an .Vt mbuf chain are contiguous and lay in the data area of .Fa mbuf , so they are accessible with .Fn mtod mbuf type . Return the new .Vt mbuf chain on success, .Dv NULL on failure (the .Vt mbuf chain is freed in this case). .Sy Note : It does not allocate any .Vt mbuf clusters , so .Fa len must be less than .Dv MHLEN . .\" .It Fn m_copym mbuf offset len how Make a copy of an .Vt mbuf chain starting .Fa offset bytes from the beginning, continuing for .Fa len bytes. If .Fa len is .Dv M_COPYALL , copy to the end of the .Vt mbuf chain . .Sy Note : The copy is read-only, because the .Vt mbuf clusters are not copied, only their reference counts are incremented. .\" .It Fn m_copypacket mbuf how Copy an entire packet including header, which must be present. This is an optimized version of the common case .Fn m_copym mbuf 0 M_COPYALL how . .Sy Note : the copy is read-only, because the .Vt mbuf clusters are not copied, only their reference counts are incremented. .\" .It Fn m_dup mbuf how Copy a packet header .Vt mbuf chain into a completely new .Vt mbuf chain , including copying any .Vt mbuf clusters . Use this instead of .Fn m_copypacket when you need a writable copy of an .Vt mbuf chain . .\" .It Fn m_copydata mbuf offset len buf Copy data from an .Vt mbuf chain starting .Fa off bytes from the beginning, continuing for .Fa len bytes, into the indicated buffer .Fa buf . .\" .It Fn m_copyback mbuf offset len buf Copy .Fa len bytes from the buffer .Fa buf back into the indicated .Vt mbuf chain , starting at .Fa offset bytes from the beginning of the .Vt mbuf chain , extending the .Vt mbuf chain if necessary. .Sy Note : It does not allocate any .Vt mbuf clusters , just adds .Vt mbufs to the .Vt mbuf chain . It is safe to set .Fa offset beyond the current .Vt mbuf chain end: zeroed .Vt mbufs will be allocated to fill the space. .\" .It Fn m_length mbuf last Return the length of the .Vt mbuf chain , and optionally a pointer to the last .Vt mbuf . .\" .It Fn m_dup_pkthdr to from how Upon the function's completion, the .Vt mbuf .Fa to will contain an identical copy of .Fa from->m_pkthdr and the per-packet attributes found in the .Vt mbuf chain .Fa from . The .Vt mbuf .Fa from must have the flag .Dv M_PKTHDR initially set, and .Fa to must be empty on entry. .\" .It Fn m_move_pkthdr to from Move .Va m_pkthdr and the per-packet attributes from the .Vt mbuf chain .Fa from to the .Vt mbuf .Fa to . The .Vt mbuf .Fa from must have the flag .Dv M_PKTHDR initially set, and .Fa to must be empty on entry. Upon the function's completion, .Fa from will have the flag .Dv M_PKTHDR and the per-packet attributes cleared. .\" .It Fn m_fixhdr mbuf Set the packet-header length to the length of the .Vt mbuf chain . .\" .It Fn m_devget buf len offset ifp copy Copy data from a device local memory pointed to by .Fa buf to an .Vt mbuf chain . The copy is done using a specified copy routine .Fa copy , or .Fn bcopy if .Fa copy is .Dv NULL . .\" .It Fn m_cat m n Concatenate .Fa n to .Fa m . Both .Vt mbuf chains must be of the same type. .Fa N is still valid after the function returned. .Sy Note : It does not handle .Dv M_PKTHDR and friends. .\" .It Fn m_split mbuf len how Partition an .Vt mbuf chain in two pieces, returning the tail: all but the first .Fa len bytes. In case of failure, it returns .Dv NULL and attempts to restore the .Vt mbuf chain to its original state. .\" .It Fn m_apply mbuf off len f arg Apply a function to an .Vt mbuf chain , at offset .Fa off , for length .Fa len bytes. Typically used to avoid calls to .Fn m_pullup which would otherwise be unnecessary or undesirable. .Fa arg is a convenience argument which is passed to the callback function .Fa f . .Pp Each time .Fn f is called, it will be passed .Fa arg , a pointer to the .Fa data in the current mbuf, and the length .Fa len of the data in this mbuf to which the function should be applied. .Pp The function should return zero to indicate success; otherwise, if an error is indicated, then .Fn m_apply will return the error and stop iterating through the .Vt mbuf chain . .\" .It Fn m_getptr mbuf loc off Return a pointer to the mbuf containing the data located at .Fa loc bytes from the beginning of the .Vt mbuf chain . The corresponding offset into the mbuf will be stored in .Fa *off . .It Fn m_defrag m0 how Defragment an mbuf chain, returning the shortest possible chain of mbufs and clusters. If allocation fails and this can not be completed, .Dv NULL will be returned and the original chain will be unchanged. Upon success, the original chain will be freed and the new chain will be returned. .Fa how should be either .Dv M_TRYWAIT or .Dv M_DONTWAIT , depending on the caller's preference. .Pp This function is especially useful in network drivers, where certain long mbuf chains must be shortened before being added to TX descriptor lists. .El .Sh HARDWARE-ASSISTED CHECKSUM CALCULATION This section currently applies to TCP/IP only. In order to save the host CPU resources, computing checksums is offloaded to the network interface hardware if possible. The .Va m_pkthdr member of the leading .Vt mbuf of a packet contains two fields used for that purpose, .Vt int Va csum_flags and .Vt int Va csum_data . The meaning of those fields depends on the direction a packet flows in, and on whether the packet is fragmented. Henceforth, .Va csum_flags or .Va csum_data of a packet will denote the corresponding field of the .Va m_pkthdr member of the leading .Vt mbuf in the .Vt mbuf chain containing the packet. .Pp On output, checksum offloading is attempted after the outgoing interface has been determined for a packet. The interface-specific field .Va ifnet.if_data.ifi_hwassist (see .Xr ifnet 9 ) is consulted for the capabilities of the interface to assist in computing checksums. The .Va csum_flags field of the packet header is set to indicate which actions the interface is supposed to perform on it. The actions unsupported by the network interface are done in the software prior to passing the packet down to the interface driver; such actions will never be requested through .Va csum_flags . .Pp The flags demanding a particular action from an interface are as follows: .Bl -tag -width ".Dv CSUM_TCP" -offset indent .It Dv CSUM_IP The IP header checksum is to be computed and stored in the corresponding field of the packet. The hardware is expected to know the format of an IP header to determine the offset of the IP checksum field. .It Dv CSUM_TCP The TCP checksum is to be computed. (See below.) .It Dv CSUM_UDP The UDP checksum is to be computed. (See below.) .El .Pp Should a TCP or UDP checksum be offloaded to the hardware, the field .Va csum_data will contain the byte offset of the checksum field relative to the end of the IP header. In this case, the checksum field will be initially set by the TCP/IP module to the checksum of the pseudo header defined by the TCP and UDP specifications. .Pp For outbound packets which have been fragmented by the host CPU, the following will also be true, regardless of the checksum flag settings: .Bl -bullet -offset indent .It all fragments will have the flag .Dv M_FRAG set in their .Va m_flags field; .It the first and the last fragments in the chain will have .Dv M_FIRSTFRAG or .Dv M_LASTFRAG set in their .Va m_flags , correspondingly; .It the first fragment in the chain will have the total number of fragments contained in its .Va csum_data field. .El .Pp The last rule for fragmented packets takes precedence over the one for a TCP or UDP checksum. Nevertheless, offloading a TCP or UDP checksum is possible for a fragmented packet if the flag .Dv CSUM_IP_FRAGS is set in the field .Va ifnet.if_data.ifi_hwassist associated with the network interface. However, in this case the interface is expected to figure out the location of the checksum field within the sequence of fragments by itself because .Va csum_data contains a fragment count instead of a checksum offset value. .Pp On input, an interface indicates the actions it has performed on a packet by setting one or more of the following flags in .Va csum_flags associated with the packet: .Bl -tag -width ".Dv CSUM_IP_CHECKED" -offset indent .It Dv CSUM_IP_CHECKED The IP header checksum has been computed. .It Dv CSUM_IP_VALID The IP header has a valid checksum. This flag can appear only in combination with .Dv CSUM_IP_CHECKED . .It Dv CSUM_DATA_VALID The checksum of the data portion of the IP packet has been computed and stored in the field .Va csum_data in network byte order. .It Dv CSUM_PSEUDO_HDR Can be set only along with .Dv CSUM_DATA_VALID to indicate that the IP data checksum found in .Va csum_data allows for the pseudo header defined by the TCP and UDP specifications. Otherwise the checksum of the pseudo header must be calculated by the host CPU and added to .Va csum_data to obtain the final checksum to be used for TCP or UDP validation purposes. .El .Pp If a particular network interface just indicates success or failure of TCP or UDP checksum validation without returning the exact value of the checksum to the host CPU, its driver can mark .Dv CSUM_DATA_VALID and .Dv CSUM_PSEUDO_HDR in .Va csum_flags , and set .Va csum_data to .Li 0xFFFF hexadecimal to indicate a valid checksum. It is a peculiarity of the algorithm used that the Internet checksum calculated over any valid packet will be .Li 0xFFFF as long as the original checksum field is included. .Pp For inbound packets which are IP fragments, all .Va csum_data fields will be summed during reassembly to obtain the final checksum value passed to an upper layer in the .Va csum_data field of the reassembled packet. The .Va csum_flags fields of all fragments will be consolidated using logical AND to obtain the final value for .Va csum_flags . Thus, in order to successfully offload checksum computation for fragmented data, all fragments should have the same value of .Va csum_flags . .Sh STRESS TESTING When running a kernel compiled with the option .Dv MBUF_STRESS_TEST , the following .Xr sysctl 8 Ns -controlled options may be used to create various failure/extreme cases for testing of network drivers and other parts of the kernel that rely on .Vt mbufs . .Bl -tag -width ident .It Va net.inet.ip.mbuf_frag_size Causes .Fn ip_output to fragment outgoing .Vt mbuf chains into fragments of the specified size. Setting this variable to 1 is an excellent way to test the long .Vt mbuf chain handling ability of network drivers. .It Va kern.ipc.m_defragrandomfailures Causes the function .Fn m_defrag to randomly fail, returning .Dv NULL . Any piece of code which uses .Fn m_defrag should be tested with this feature. .El .Sh RETURN VALUES See above. .Sh SEE ALSO .Xr ifnet 9 , .Xr mbuf_tags 9 .Sh HISTORY .\" Please correct me if I'm wrong .Vt Mbufs appeared in an early version of .Bx . Besides being used for network packets, they were used to store various dynamic structures, such as routing table entries, interface addresses, protocol control blocks, etc. .Sh AUTHORS The original .Nm man page was written by Yar Tikhiy. Index: head/share/man/man9/pci.9 =================================================================== --- head/share/man/man9/pci.9 (revision 147397) +++ head/share/man/man9/pci.9 (revision 147398) @@ -1,252 +1,252 @@ .\" .\" Copyright (c) 2005 Bruce M Simpson .\" 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 January 22, 2005 .Dt PCI 9 .Os .Sh NAME .Nm pci , .Nm pci_read_config , .Nm pci_write_config , .Nm pci_enable_busmaster , .Nm pci_disable_busmaster , .Nm pci_enable_io , .Nm pci_disable_io , .Nm pci_set_powerstate , .Nm pci_get_powerstate , .Nm pci_find_bsf , .Nm pci_find_device .Nd PCI bus interface .Sh SYNOPSIS .In sys/bus.h .In dev/pci/pcivar.h .In dev/pci/pcireg.h .In machine/pci_cfgreg.h .Ft void .Fn pci_write_config "device_t dev" "int reg" "uint32_t val" "int width" .Ft int .Fn pci_enable_busmaster "device_t dev" .Ft int .Fn pci_disable_busmaster "device_t dev" .Ft int .Fn pci_enable_io "device_t dev" "int space" .Ft int .Fn pci_disable_io "device_t dev" "int space" .Ft int .Fn pci_set_powerstate "device_t dev" "int state" .Ft int .Fn pci_get_powerstate "device_t dev" .Ft uint32_t .Fn pci_read_config "device_t dev" "int reg" "int width" .Ft device_t .Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func" .Ft device_t .Fn pci_find_device "uint16_t vendor" "uint16_t device" .Sh DESCRIPTION The .Nm set of functions are used for managing PCI devices. .Pp The .Fn pci_read_config function is used to read data from the PCI configuration space of the device .Fa dev , at offset .Fa reg , with .Fa width specifying the size of the access. .Pp The .Fn pci_write_config function is used to write the value .Fa val to the PCI configuration space of the device .Fa dev , at offset .Fa reg , with .Fa width specifying the size of the access. .Pp The .Fn pci_enable_busmaster function enables PCI bus mastering for the device .Fa dev , by setting the .Dv PCIM_CMD_BUSMASTEREN bit in the .Dv PCIR_COMMAND register. The .Fn pci_disable_busmaster function clears this bit. .Pp The .Fn pci_enable_io function enables memory or I/O port address decoding for the device .Fa dev , by setting the .Dv PCIM_CMD_MEMEN or .Dv PCIM_CMD_PORTEN bit in the .Dv PCIR_COMMAND register appropriately. The .Fn pci_disable_io function clears the appropriate bit. The .Fa space argument specifies which resource is affected; this can be either .Dv SYS_RES_MEMORY or .Dv SYS_RES_IOPORT as appropriate. .Pp .Em NOTE : These functions should be used in preference to manually manipulating the configuration space. .Pp The .Fn pci_get_powerstate function returns the current ACPI power state of the device .Fa dev . If the device does not support power management capabilities, then the default state of .Dv PCI_POWERSTATE_D0 is returned. The following power states are defined by ACPI: .Bl -hang -width ".Dv PCI_POWERSTATE_UNKNOWN" .It Dv PCI_POWERSTATE_D0 State in which device is on and running. It is receiving full power from the system and delivering full functionality to the user. .It Dv PCI_POWERSTATE_D1 Class-specific low-power state in which device context may or may not be lot. Busses in this state cannot do anything to the bus, to force devices to lose context. .It Dv PCI_POWERSTATE_D2 Class-specific low-power state in which device context may or may not be lost. Attains greater power savings than .Dv PCI_POWERSTATE_D1 . Busses in this state can cause devices to lose some context. Devices .Em must be prepared for the bus to be in this state or higher. .It Dv PCI_POWERSTATE_D3 State in which the device is off and not running. Device context is lost, and power from the device can be removed. .It Dv PCI_POWERSTATE_UNKNOWN State of the device is unknown. .El .Pp The .Fn pci_set_powerstate function is used to transition the device .Fa dev to the ACPI power state .Fa state . It checks to see if the device is PCI 2.2 compliant. If so, it checks the capabilities pointer to determine which power states the device supports. If the device does not have power management capabilities, the default state of .Dv PCI_POWERSTATE_D0 is set. .Pp The .Fn pci_find_bsf function looks up the .Vt device_t of a PCI device, given its .Fa bus , .Fa slot , and .Fa func . The .Fa slot number actually refers to the number of the device on the bus, which does not necessarily indicate its geographic location in terms of a physical slot. .Pp The .Fn pci_find_device function looks up the .Vt device_t of a PCI device, given its .Fa vendor and .Fa device IDs. Note that there can be multiple matches for this search; this function only returns the first matching device. .Sh IMPLEMENTATION NOTES The .Vt pci_addr_t type varies according to the size of the PCI bus address space on the target architecture. .Sh SEE ALSO .Xr pci 4 , .Xr pciconf 8 , .Xr bus_alloc_resource 9 , .Xr bus_dma 9 , .Xr bus_release_resource 9 , .Xr bus_setup_intr 9 , .Xr bus_teardown_intr 9 , .Xr devclass 9 , .Xr device 9 , .Xr driver 9 , .Xr rman 9 .Rs .%B FreeBSD Developers' Handbook .%T NewBus .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ .Re .Rs .%A Shanley .%A Anderson .%B PCI System Architecture .%N 2nd Edition .%I Addison-Wesley .%O ISBN 0-201-30974-2 .Re .Sh AUTHORS This man page was written by .An Bruce M Simpson Aq bms@FreeBSD.org . .Sh BUGS -The kernel PCI code has a number of references to +The kernel PCI code has a number of references to .Dq "slot numbers" . These do not refer to the geographic location of PCI devices, but to the device number assigned by the combination of the PCI IDSEL mechanism and the platform firmware. This should be taken note of when working with the kernel PCI code. Index: head/share/man/man9/rman.9 =================================================================== --- head/share/man/man9/rman.9 (revision 147397) +++ head/share/man/man9/rman.9 (revision 147398) @@ -1,328 +1,328 @@ .\" .\" Copyright (c) 2003 Bruce M Simpson .\" 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 May 12, 2003 +.Dd March 15, 2005 .Dt RMAN 9 .Os .Sh NAME .Nm rman , .Nm rman_activate_resource , .Nm rman_await_resource , .Nm rman_deactivate_resource , .Nm rman_fini , .Nm rman_init , .Nm rman_manage_region , .Nm rman_release_resource , .Nm rman_reserve_resource , .Nm rman_reserve_resource_bound , .Nm rman_make_alignment_flags , .Nm rman_get_start , .Nm rman_get_end , .Nm rman_get_device , .Nm rman_get_size , .Nm rman_get_flags , .Nm rman_set_virtual , .Nm rman_get_virtual , .Nm rman_set_bustag , .Nm rman_get_bustag , .Nm rman_set_bushandle , .Nm rman_get_bushandle , .Nm rman_set_rid , .Nm rman_get_rid .Nd resource management functions .Sh SYNOPSIS .In sys/rman.h .Ft int .Fn rman_activate_resource "struct resource *r" .Ft int .Fn rman_await_resource "struct resource *r" "int pri2" "int timo" .Ft int .Fn rman_deactivate_resource "struct resource *r" .Ft int .Fn rman_fini "struct rman *rm" .Ft int .Fn rman_init "struct rman *rm" .Ft int .Fn rman_manage_region "struct rman *rm" "u_long start" "u_long end" .Ft int .Fn rman_release_resource "struct resource *r" .Ft "struct resource *" .Fo rman_reserve_resource .Fa "struct rman *rm" "u_long start" "u_long end" "u_long count" .Fa "u_int flags" "struct device *dev" .Fc .Ft "struct resource *" .Fo rman_reserve_resource_bound .Fa "struct rman *rm" "u_long start" "u_long end" "u_long count" .Fa "u_long bound" "u_int flags" "struct device *dev" .Fc .Ft uint32_t .Fn rman_make_alignment_flags "uint32_t size" .Ft u_long .Fn rman_get_start "struct resource *r" .Ft u_long .Fn rman_get_end "struct resource *r" .Ft "struct device *" .Fn rman_get_device "struct resource *r" .Ft u_long .Fn rman_get_size "struct resource *r" .Ft u_int .Fn rman_get_flags "struct resource *r" .Ft void .Fn rman_set_virtual "struct resource *r" "void *v" .Ft "void *" .Fn rman_get_virtual "struct resource *r" .Ft void .Fn rman_set_bustag "struct resource *r" "bus_space_tag_t t" .Ft bus_space_tag_t .Fn rman_get_bustag "struct resource *r" .Ft void .Fn rman_set_bushandle "struct resource *r" "bus_space_handle_t h" .Ft bus_space_handle_t .Fn rman_get_bushandle "struct resource *r" .Ft void .Fn rman_set_rid "struct resource *r" "int rid" .Ft int .Fn rman_get_rid "struct resource *r" .Sh DESCRIPTION The .Nm set of functions provides a flexible resource management abstraction. It is used extensively by the bus management code. It implements the abstractions of region and resource. A region descriptor is used to manage a region; this could be memory or some other form of bus space. .Pp Each region has a set of bounds. Within these bounds, allocated segments may reside. Each segment, termed a resource, has several properties which are represented by a 16-bit flag register, as follows. .Bd -literal #define RF_ALLOCATED 0x0001 /* resource has been reserved */ #define RF_ACTIVE 0x0002 /* resource allocation has been activated */ #define RF_SHAREABLE 0x0004 /* resource permits contemporaneous sharing */ #define RF_TIMESHARE 0x0008 /* resource permits time-division sharing */ #define RF_WANTED 0x0010 /* somebody is waiting for this resource */ #define RF_FIRSTSHARE 0x0020 /* first in sharing list */ #define RF_PREFETCHABLE 0x0040 /* resource is prefetchable */ .Ed .Pp The remainder of the flag bits are used to represent the desired alignment of the resource within the region. .Pp The .Fn rman_init function initializes the region descriptor, pointed to by the .Fa rm argument, for use with the resource management functions. It also initializes any mutexes associated with the structure. .Pp The .Fn rman_fini function frees any structures associated with the structure pointed to by the .Fa rm argument. If any of the resources within the managed region have the .Dv RF_ALLOCATED flag set, it will return .Er EBUSY ; otherwise, any mutexes associated with the structure will be released and destroyed, and the function will return 0. .Pp The .Fn rman_manage_region function establishes the concept of a region which is under .Nm control. The .Fa rman argument points to the region descriptor. The .Fa start and .Fa end arguments specify the bounds of the region. .Pp .Em NOTE : This interface is not robust against programming errors which add multiple copies of the same region. .Pp The .Fn rman_reserve_resource_bound function is where the bulk of the .Nm logic is located. It attempts to reserve a contiguous range in the specified region .Fa rm for the use of the device .Fa dev . The caller can specify the .Fa start and .Fa end of an acceptable range, as well as alignment, and the code will attempt to find a free segment which fits. -The +The .Fa start argument is the lowest acceptable starting value of the resource. The .Fa end argument is the highest acceptable ending value of the resource. Therefore, -.Fa start + count - 1 -must be <= +.Fa start No + Fa count No \- 1 +must be \[<=] .Fa end for any allocation to happen. The default behavior is to allocate an exclusive segment, unless the .Dv RF_SHAREABLE or .Dv RF_TIMESHARE flags are set, in which case a shared segment will be allocated. If this shared segment already exists, the caller has its device added to the list of consumers. .Pp The .Fn rman_reserve_resource function is used to reserve resources within a previously established region. It is a simplified interface to .Fn rman_reserve_resource_bound which passes 0 for the .Fa flags argument. .Pp The .Fn rman_make_alignment_flags function returns the flag mask corresponding to the desired alignment .Fa size . This should be used when calling .Fn rman_reserve_resource_bound . .Pp The .Fn rman_release_resource function releases the reserved resource .Fa r . It may attempt to merge adjacent free resources. .Pp The .Fn rman_activate_resource function marks a resource as active, by setting the .Dv RF_ACTIVE flag. If this is a time shared resource, and the caller has not yet acquired the resource, the function returns .Er EBUSY . .Pp The .Fn rman_deactivate_resource function marks a resource .Fa r as inactive, by clearing the .Dv RF_ACTIVE flag. If other consumers are waiting for this range, it will wakeup their threads. .Pp The .Fn rman_await_resource function performs an asynchronous wait for a resource .Fa r to become inactive, that is, for the .Dv RF_ACTIVE flag to be cleared. It is used to enable cooperative sharing of a resource which can only be safely used by one thread at a time. The arguments .Fa pri and .Fa timo are passed to the .Fn rman_await_resource function. .Pp The .Fn rman_get_start , .Fn rman_get_end , .Fn rman_get_size , and .Fn rman_get_flags functions return the bounds, size and flags of the previously reserved resource .Fa r . .Pp The .Fn rman_set_bustag function associates a .Vt bus_space_tag_t .Fa t with the resource .Fa r . The .Fn rman_get_bustag function is used to retrieve this tag once set. .Pp The .Fn rman_set_bushandle function associates a .Vt bus_space_handle_t .Fa h with the resource .Fa r . The .Fn rman_get_bushandle function is used to retrieve this handle once set. .Pp The .Fn rman_set_virtual function is used to associate a kernel virtual address with a resource .Fa r . The .Fn rman_get_virtual function can be used to retrieve the KVA once set. .Pp The .Fn rman_set_rid function associates a resource identifier with a resource .Fa r . The .Fn rman_get_rid function retrieves this RID. .Pp The .Fn rman_get_device function returns a pointer to the device which reserved the resource .Fa r . .Pp .Sh SEE ALSO .Xr bus_activate_resource 9 , .Xr bus_alloc_resource 9 , .Xr bus_release_resource 9 , .Xr bus_set_resource 9 , .Xr mutex 9 .Sh AUTHORS This man page was written by .An Bruce M Simpson Aq bms@spc.org . Index: head/share/man/man9/taskqueue.9 =================================================================== --- head/share/man/man9/taskqueue.9 (revision 147397) +++ head/share/man/man9/taskqueue.9 (revision 147398) @@ -1,297 +1,297 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 2000 Doug Rabson .\" .\" All rights reserved. .\" .\" This program is free software. .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 May 19, 2005 .Dt TASKQUEUE 9 .Os .Sh NAME .Nm taskqueue .Nd asynchronous task execution .Sh SYNOPSIS .In sys/param.h .In sys/kernel.h .In sys/malloc.h .In sys/queue.h .In sys/taskqueue.h .Bd -literal typedef void (*task_fn_t)(void *context, int pending); typedef void (*taskqueue_enqueue_fn)(void *context); struct task { STAILQ_ENTRY(task) ta_link; /* link for queue */ u_short ta_pending; /* count times queued */ u_short ta_priority; /* priority of task in queue */ task_fn_t ta_func; /* task handler */ void *ta_context; /* argument for handler */ }; .Ed .Ft struct taskqueue * .Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context" "struct proc **" .Ft void .Fn taskqueue_free "struct taskqueue *queue" .Ft struct taskqueue * .Fn taskqueue_find "const char *name" .Ft int .Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task" .Ft int .Fn taskqueue_enqueue_fast "struct taskqueue *queue" "struct task *task" .Ft void .Fn taskqueue_run "struct taskqueue *queue" .Ft void .Fn taskqueue_run_fast "struct taskqueue *queue" .Ft void .Fn taskqueue_drain "struct taskqueue *queue" "struct task *task" .Fn TASK_INIT "struct task *task" "int priority" "task_fn_t *func" "void *context" .Fn TASKQUEUE_DECLARE "name" .Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init" .Fn TASKQUEUE_DEFINE_THREAD "name" .Sh DESCRIPTION These functions provide a simple interface for asynchronous execution of code. .Pp The function .Fn taskqueue_create is used to create new queues. The arguments to .Fn taskqueue_create include a name that should be unique, a set of .Xr malloc 9 flags that specify whether the call to .Fn malloc is allowed to sleep, a function that is called from .Fn taskqueue_enqueue when a task is added to the queue, and a pointer to the memory location where the identity of the thread that services the queue is recorded. .\" XXX The rest of the sentence gets lots in relation to the first part. The function called from .Fn taskqueue_enqueue must arrange for the queue to be processed (for instance by scheduling a software interrupt or waking a kernel thread). The memory location where the thread identity is recorded is used to signal the service thread(s) to terminate--when this value is set to zero and the thread is signaled it will terminate. .Pp The function .Fn taskqueue_free should be used to remove the queue from the global list of queues and free the memory used by the queue. Any tasks that are on the queue will be executed at this time after which the thread servicing the queue will be signaled that it should exit. .Pp The system maintains a list of all queues which can be searched using .Fn taskqueue_find . The first queue whose name matches is returned, otherwise .Dv NULL . .Pp To add a task to the list of tasks queued on a taskqueue, call .Fn taskqueue_enqueue with pointers to the queue and task. If the task's .Va ta_pending field is non-zero, then it is simply incremented to reflect the number of times the task was enqueued. Otherwise, the task is added to the list before the first task which has a lower .Va ta_priority value or at the end of the list if no tasks have a lower priority. Enqueueing a task does not perform any memory allocation which makes it suitable for calling from an interrupt handler. This function will return .Er EPIPE if the queue is being freed. .Pp The function .Fn taskqueue_enqueue_fast should be used in place of .Fn taskqueue_enqueue when the enqueuing must happen from a fast interrupt handler. This method uses spin locks to avoid the possibility of sleeping in the fast interrupt context. .Pp To execute all the tasks on a queue, call .Fn taskqueue_run or .Fn taskqueue_run_fast depending on the flavour of the queue. When a task is executed, first it is removed from the queue, the value of .Va ta_pending is recorded and then the field is zeroed. The function .Va ta_func from the task structure is called with the value of the field .Va ta_context as its first argument and the value of .Va ta_pending as its second argument. .Pp -The +The .Fn taskqueue_drain function is used to wait for the task to finish. There is no guarantee that the task will not be enqueued after call to .Fn taskqueue_drain . .Pp A convenience macro, .Fn TASK_INIT "task" "priority" "func" "context" is provided to initialise a .Va task structure. The values of .Va priority , .Va func , and .Va context are simply copied into the task structure fields and the .Va ta_pending field is cleared. .Pp Three macros .Fn TASKQUEUE_DECLARE "name" , .Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" , and .Fn TASKQUEUE_DEFINE_THREAD "name" are used to declare a reference to a global queue, to define the implementation of the queue, and declare a queue that uses its own thread. The .Fn TASKQUEUE_DEFINE macro arranges to call .Fn taskqueue_create with the values of its .Va name , .Va enqueue and .Va context arguments during system initialisation. After calling .Fn taskqueue_create , the .Va init argument to the macro is executed as a C statement, allowing any further initialisation to be performed (such as registering an interrupt handler etc.) .Pp The .Fn TASKQUEUE_DEFINE_THREAD macro defines a new taskqueue with its own kernel thread to serve tasks. The variable .Vt struct proc *taskqueue_name_proc is defined which contains the kernel thread serving the tasks. The variable .Vt struct taskqueue *taskqueue_name is used to enqueue tasks onto the queue. .Ss Predefined Task Queues The system provides four global taskqueues, .Va taskqueue_fast , .Va taskqueue_swi , .Va taskqueue_swi_giant , and .Va taskqueue_thread . The .Va taskqueue_fast queue is for swi handlers dispatched from fast interrupt handlers, where sleep mutexes cannot be used. The swi taskqueues are run via a software interrupt mechanism. The .Va taskqueue_swi queue runs without the protection of the .Va Giant kernel lock, and the .Va taskqueue_swi_giant queue runs with the protection of the .Va Giant kernel lock. The thread taskqueue .Va taskqueue_thread runs in a kernel thread context, and tasks run from this thread do not run under the .Va Giant kernel lock. If the caller wants to run under .Va Giant , he should explicitly acquire and release .Va Giant in his taskqueue handler routine. .Pp To use these queues, call .Fn taskqueue_enqueue with the value of the global taskqueue variable for the queue you wish to use .Va ( taskqueue_swi , .Va taskqueue_swi_giant , or .Va taskqueue_thread ) . Use .Fn taskqueue_enqueue_fast for the global taskqueue variable .Va taskqueue_fast . .Pp The software interrupt queues can be used, for instance, for implementing interrupt handlers which must perform a significant amount of processing in the handler. The hardware interrupt handler would perform minimal processing of the interrupt and then enqueue a task to finish the work. This reduces to a minimum the amount of time spent with interrupts disabled. .Pp The thread queue can be used, for instance, by interrupt level routines that need to call kernel functions that do things that can only be done from a thread context. (e.g., call malloc with the M_WAITOK flag.) .Pp Note that tasks queued on shared taskqueues such as .Va taskqueue_swi may be delayed an indeterminate amount of time before execution. If queueing delays cannot be tolerated then a private taskqueue should be created with a dedicated processing thread. .Sh SEE ALSO .Xr ithread 9 , .Xr kthread 9 , .Xr swi 9 .Sh HISTORY This interface first appeared in .Fx 5.0 . There is a similar facility called tqueue in the Linux kernel. .Sh AUTHORS This man page was written by .An Doug Rabson . .Sh BUGS There is no .Fn taskqueue_create_fast . Index: head/share/man/man9/time.9 =================================================================== --- head/share/man/man9/time.9 (revision 147397) +++ head/share/man/man9/time.9 (revision 147398) @@ -1,116 +1,116 @@ .\" $NetBSD: time.9,v 1.1 1995/11/25 21:24:53 perry Exp $ .\" .\" Copyright (c) 1994 Christopher G. Demetriou .\" 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. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by Christopher G. Demetriou .\" for the NetBSD Project. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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 September 17, 2004 .Dt TIME 9 .Os .Sh NAME .Nm boottime , .Nm time_second , .Nm time_uptime .Nd system time variables .Sh SYNOPSIS .In sys/time.h .Pp .Vt extern struct timeval boottime ; .Vt extern struct time_t time_second ; .Vt extern struct timeval time_uptime ; .Sh DESCRIPTION The .Va boottime variable holds the system boot time. .Pp The .Va time_second variable is the system's .Dq wall time clock to the second. .Pp The .Va time_uptime variable is the number of seconds since boot. .Pp The .Xr bintime 9 , .Xr getbintime 9 , .Xr microtime 9 , .Xr getmicrotime 9 , .Xr nanotime 9 , and .Xr getnanotime 9 functions can be used to get the current time more accurately and in an atomic manner. Similarly, the The .Xr binuptime 9 , .Xr getbinuptime 9 , .Xr microuptime 9 , .Xr getmicrouptime 9 , .Xr nanouptime 9 , and .Xr getnanouptime 9 functions can be used to get the time elapse since boot more accurately and in an atomic manner. The .Va boottime variable may be read and written without special precautions. .Sh SEE ALSO .Xr clock_settime 2 , .Xr ntp_adjtime 2 , .Xr settimeofday 2 , +.Xr bintime 9 , +.Xr binuptime 9 , .Xr getbintime 9 , .Xr getbinuptime 9 , .Xr getmicrotime 9 , .Xr getmicrouptime 9 , .Xr getnanotime 9 , .Xr getnanouptime 9 , -.Xr bintime 9 , -.Xr binuptime 9 , .Xr microtime 9 , .Xr microuptime 9 , .Xr nanotime 9 , .Xr nanouptime 9 .Rs .%A "Poul-Henning Kamp" .%T "Timecounters: Efficient and precise timekeeping in SMP kernels" .%J "Proceedings of EuroBSDCon 2002, Amsterdam" .%O /usr/share/doc/papers/timecounter.ascii.gz .Re .Rs .%A "Marshall Kirk McKusick" .%A "George V. Neville-Neil" .%B "The Design and Implementation of the FreeBSD Operating System" .%D "July 2004" .%I "Addison-Wesley" .%P "57-61,65-66" .Re Index: head/share/man/man9/timeout.9 =================================================================== --- head/share/man/man9/timeout.9 (revision 147397) +++ head/share/man/man9/timeout.9 (revision 147398) @@ -1,524 +1,524 @@ .\" $NetBSD: timeout.9,v 1.2 1996/06/23 22:32:34 pk Exp $ .\" .\" Copyright (c) 1996 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Paul Kranenburg. .\" .\" 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. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the NetBSD .\" Foundation, Inc. and its contributors. .\" 4. Neither the name of The NetBSD Foundation nor the names of its .\" contributors may be used to endorse or promote products derived .\" from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 REGENTS 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 February 6, 2005 .Dt TIMEOUT 9 .Os .Sh NAME .Nm timeout , .Nm untimeout , .Nm callout_handle_init , .Nm callout_init , .Nm callout_init_mtx , .Nm callout_stop , .Nm callout_drain , .Nm callout_reset , .Nm callout_pending , .Nm callout_active , .Nm callout_deactivate .Nd execute a function after a specified length of time .Sh SYNOPSIS .In sys/types.h .In sys/systm.h .Pp .Bd -literal typedef void timeout_t (void *); .Ed .Ft struct callout_handle .Fn timeout "timeout_t *func" "void *arg" "int ticks" .Ft void .Fn callout_handle_init "struct callout_handle *handle" .Pp .Bd -literal struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle) .Ed .Ft void .Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle" .Ft void .Fn callout_init "struct callout *c" "int mpsafe" .Ft void .Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags" .Ft int .Fn callout_stop "struct callout *c" .Ft int .Fn callout_drain "struct callout *c" .Ft void .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg" .Ft int .Fn callout_pending "struct callout *c" .Ft int .Fn callout_active "struct callout *c" .Fn callout_deactivate "struct callout *c" .Sh DESCRIPTION The function .Fn timeout schedules a call to the function given by the argument .Fa func to take place after .Fa ticks Ns No /hz seconds. Non-positive values of .Fa ticks are silently converted to the value .Sq 1 . .Fa func should be a pointer to a function that takes a .Fa void * argument. Upon invocation, .Fa func will receive .Fa arg as its only argument. The return value from .Fn timeout is a .Ft struct callout_handle which can be used in conjunction with the .Fn untimeout function to request that a scheduled timeout be canceled. The .Fn timeout call is the old style and new code should use the .Fn callout_* functions. .Pp The function .Fn callout_handle_init can be used to initialize a handle to a state which will cause any calls to untimeout with that handle to return with no side effects. .Pp Assigning a callout handle the value of .Fn CALLOUT_HANDLE_INITIALIZER performs the same function as .Fn callout_handle_init and is provided for use on statically declared or global callout handles. .Pp The function .Fn untimeout cancels the timeout associated with .Fa handle using the .Fa func and .Fa arg arguments to validate the handle. If the handle does not correspond to a timeout with the function .Fa func taking the argument .Fa arg no action is taken. .Fa handle must be initialized by a previous call to .Fn timeout , .Fn callout_handle_init , or assigned the value of .Fn CALLOUT_HANDLE_INITIALIZER "&handle" before being passed to .Fn untimeout . The behavior of calling untimeout without a previously initialized handle is undefined. The .Fn untimeout call is the old style and new code should use the .Fn callout_* functions. .Pp As handles are recycled by the system, it is possible (although unlikely) that a handle from one invocation of .Fn timeout may match the handle of another invocation of .Fn timeout if both calls used the same function pointer and argument, and the first timeout is expired or canceled before the second call. The timeout facility offers O(1) running time for .Fn timeout and .Fn untimeout . Timeouts are executed from .Fn softclock with the .Va Giant lock held. Thus they are protected from re-entrancy. .Pp The functions .Fn callout_init , .Fn callout_init_mtx , .Fn callout_stop , .Fn callout_drain and .Fn callout_reset are low-level routines for clients who wish to allocate their own callout structures. .Pp The function .Fn callout_init initializes a callout so it can be passed to .Fn callout_stop , .Fn callout_drain or .Fn callout_reset without any side effects. If the .Fa mpsafe argument is zero, the callout structure is not considered to be .Dq multi-processor safe ; that is, the Giant lock will be acquired before calling the callout function, and released when the callout function returns. .Pp The .Fn callout_init_mtx function may be used as an alternative to .Fn callout_init . The parameter .Fa mtx specifies a mutex that is to be acquired by the callout subsystem before calling the callout function, and released when the callout function returns. The following .Fa flags may be specified: -.Bl -tag -width CALLOUT_RETURNUNLOCKED +.Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED" .It Dv CALLOUT_RETURNUNLOCKED The callout function will release .Fa mtx itself, so the callout subsystem should not attempt to unlock it after the callout function returns. .El .Pp The function .Fn callout_stop cancels a callout if it is currently pending. If the callout is pending, then .Fn callout_stop will return a non-zero value. If the callout is not set, has already been serviced or is currently being serviced, then zero will be returned. If the callout has an associated mutex, then that mutex must be held when this function is called. .Pp The function .Fn callout_drain is identical to .Fn callout_stop except that it will wait for the callout to be completed if it is already in progress. This function MUST NOT be called while holding any locks on which the callout might block, or deadlock will result. Note that if the callout subsystem has already begun processing this callout, then the callout function may be invoked during the execution of .Fn callout_drain . However, the callout subsystem does guarantee that the callout will be fully stopped before .Fn callout_drain returns. .Pp The function .Fn callout_reset first performs the equivalent of .Fn callout_stop to disestablish the callout, and then establishes a new callout in the same manner as .Fn timeout . If the callout has an associated mutex, then that mutex must be held when this function is called. .Pp The macros .Fn callout_pending , .Fn callout_active and .Fn callout_deactivate provide access to the current state of the callout. Careful use of these macros can avoid many of the race conditions that are inherent in asynchronous timer facilities; see .Sx "Avoiding Race Conditions" below for further details. The .Fn callout_pending macro checks whether a callout is .Em pending ; a callout is considered .Em pending when a timeout has been set but the time has not yet arrived. Note that once the timeout time arrives and the callout subsystem starts to process this callout, .Fn callout_pending will return .Dv FALSE even though the callout function may not have finished (or even begun) executing. The .Fn callout_active macro checks whether a callout is marked as .Em active , and the .Fn callout_deactivate macro clears the callout's .Em active flag. The callout subsystem marks a callout as .Em active when a timeout is set and it clears the .Em active flag in .Fn callout_stop and .Fn callout_drain , but it .Em does not clear it when a callout expires normally via the execution of the callout function. .Ss "Avoiding Race Conditions" The callout subsystem invokes callout functions from its own timer context. Without some kind of synchronization it is possible that a callout function will be invoked concurrently with an attempt to stop or reset the callout by another thread. In particular, since callout functions typically acquire a mutex as their first action, the callout function may have already been invoked, but be blocked waiting for that mutex at the time that another thread tries to reset or stop the callout. .Pp The callout subsystem provides a number of mechanisms to address these synchronization concerns: .Bl -enum -offset indent .It If the callout has an associated mutex that was specified using the .Fn callout_init_mtx function (or implicitly specified as the .Va Giant mutex using .Fn callout_init with .Fa mpsafe set to .Dv FALSE ) , then this mutex is used to avoid the race conditions. The associated mutex must be acquired by the caller before calling .Fn callout_stop or .Fn callout_reset and it is guaranteed that the callout will be correctly stopped or reset as expected. Note that it is still necessary to use .Fn callout_drain before destroying the callout or its associated mutex. .It The return value from .Fn callout_stop indicates whether or not the callout was removed. If it is known that the callout was set and the callout function has not yet executed, then a return value of .Dv FALSE indicates that the callout function is about to be called. For example: .Bd -literal -offset indent if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) { if (callout_stop(&sc->sc_callout)) { sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING; /* successfully stopped */ } else { /* * callout has expired and callout * function is about to be executed */ } } .Ed .Pp Note that there is no equivalent mechanism to determine whether or not .Fn callout_reset stopped the callout. .It The .Fn callout_pending , .Fn callout_active and .Fn callout_deactivate macros can be used together to work around the race conditions. When a callout's timeout is set, the callout subsystem marks the callout as both .Em active and .Em pending . When the timeout time arrives, the callout subsystem begins processing the callout by first clearing the .Em pending flag. It then invokes the callout function without changing the .Em active flag, and does not clear the .Em active flag even after the callout function returns. The mechanism described here requires the callout function itself to clear the .Em active flag using the .Fn callout_deactivate macro. The .Fn callout_stop and .Fn callout_drain functions always clear both the .Em active and .Em pending flags before returning. .Pp The callout function should first check the .Em pending flag and return without action if .Fn callout_pending returns .Dv TRUE . This indicates that the callout was rescheduled using .Fn callout_reset just before the callout function was invoked. If .Fn callout_active returns .Dv FALSE then the callout function should also return without action. This indicates that the callout has been stopped. Finally, the callout function should call .Fn callout_deactivate to clear the .Em active flag. For example: .Bd -literal -offset indent mtx_lock(&sc->sc_mtx); if (callout_pending(&sc->sc_callout)) { /* callout was reset */ mtx_unlock(&sc->sc_mtx); return; } if (!callout_active(&sc->sc_callout)) { /* callout was stopped */ mtx_unlock(&sc->sc_mtx); return; } callout_deactivate(&sc->sc_callout); /* rest of callout function */ .Ed .Pp Together with appropriate synchronization, such as the mutex used above, this approach permits the .Fn callout_stop and .Fn callout_reset functions to be used at any time without races. For example: .Bd -literal -offset indent mtx_lock(&sc->sc_mtx); callout_stop(&sc->sc_callout); /* The callout is effectively stopped now. */ .Ed .Pp If the callout is still pending then these functions operate normally, but if processing of the callout has already begun then the tests in the callout function cause it to return without further action. Synchronization between the callout function and other code ensures that stopping or resetting the callout will never be attempted while the callout function is past the .Fn callout_deactivate call. .Pp The above technique additionally ensures that the .Em active flag always reflects whether the callout is effectively enabled or disabled. If .Fn callout_active returns false, then the callout is effectively disabled, since even if the callout subsystem is actually just about to invoke the callout function, the callout function will return without action. .El .Pp There is one final race condition that must be considered when a callout is being stopped for the last time. In this case it may not be safe to let the callout function itself detect that the callout was stopped, since it may need to access data objects that have already been destroyed or recycled. To ensure that the callout is completely finished, a call to .Fn callout_drain should be used. .Sh RETURN VALUES The .Fn timeout function returns a .Ft struct callout_handle that can be passed to .Fn untimeout . The .Fn callout_stop and .Fn callout_drain functions return non-zero if the callout was still pending when it was called or zero otherwise. .Sh HISTORY The current timeout and untimeout routines are based on the work of .An Adam M. Costello and .An George Varghese , published in a technical report entitled .%T "Redesigning the BSD Callout and Timer Facilities" and modified slightly for inclusion in .Fx by .An Justin T. Gibbs . The original work on the data structures used in this implementation was published by .An G. Varghese and .An A. Lauck in the paper .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility" in the .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" . The current implementation replaces the long standing .Bx linked list callout mechanism which offered O(n) insertion and removal running time but did not generate or require handles for untimeout operations. Index: head/share/man/man9/vfs_suser.9 =================================================================== --- head/share/man/man9/vfs_suser.9 (revision 147397) +++ head/share/man/man9/vfs_suser.9 (revision 147398) @@ -1,73 +1,73 @@ .\" .\" Copyright (c) 2004 Alfred Perlstein .\" 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 ``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 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 April 2, 2004 .Dt VFS_SUSER 9 .Os .Sh NAME .Nm vfs_suser .Nd check if credentials have superuser privileges for a mount point .Sh SYNOPSIS .In sys/param.h .In sys/systm.h .In sys/mount.h .Ft int .Fn vfs_suser "struct mount *mp" "struct thread *td" .Sh DESCRIPTION The .Fn vfs_suser function checks if the credentials given include superuser powers -for the given mountpoint. +for the given mount point. It will check to see if the thread passed in has the same credentials as the user that mounted the file system. If so, it returns 0, otherwise it returns what .Xr suser 9 would have returned. .Sh RETURN VALUES The .Fn vfs_suser function returns 0 if the user has superuser powers and .Er EPERM otherwise. This is the .Em reverse logic of some other implementations of .Fn suser in which a TRUE response indicates superuser powers. .Sh SEE ALSO .Xr chroot 2 , .Xr jail 2 , .Xr suser 9 .Sh HISTORY The .Fn vfs_suser function was introduced in .Fx 5.2 . .Sh AUTHORS This manual page was written by .An Alfred Perlstein .