Index: head/contrib/openbsm/libbsm/audit_submit.3 =================================================================== --- head/contrib/openbsm/libbsm/audit_submit.3 (revision 222285) +++ head/contrib/openbsm/libbsm/audit_submit.3 (revision 222286) @@ -1,156 +1,156 @@ .\" .\" Copyright (c) 2006 Christian S.J. Peron .\" 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 Apple Computer, Inc. ("Apple") 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 APPLE AND ITS 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 APPLE OR ITS 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. .\" .\" $P4: //depot/projects/trustedbsd/openbsm/libbsm/audit_submit.3#17 $ .\" .Dd January 18, 2008 -.Dt audit_submit 3 +.Dt AUDIT_SUBMIT 3 .Os .Sh NAME .Nm audit_submit .Nd "general purpose audit record submission" .Sh LIBRARY .Lb libbsm .Sh SYNOPSIS .In bsm/libbsm.h .Ft int .Fo audit_submit .Fa "short au_event" "au_id_t auid" "char status" .Fa "int reterr" "const char * restrict format" ... .Fc .Sh DESCRIPTION The .Fn audit_submit function provides a generic programming interface for audit record submission. This audit record will contain a header, subject token, an optional text token, return token, and a trailer. The header will contain the event class specified by .Fa au_event . The subject token will be generated based on .Fa auid . The return token is dependent on the .Fa status and .Fa reterr arguments; unlike the argument to .Xr au_to_return , .Fa reterr should be a local rather than BSM error number. Optionally, a text token will be created as a part of this record. .Pp Text token output is under the control of a .Fa format string that specifies how subsequent arguments (or arguments accessed via the variable-length argument facilities of .Xr stdarg 3 ) are converted for output. If .Fa format is .Dv NULL , then no text token is created in the audit record. .Pp It should be noted that .Fn audit_submit assumes that .Xr setaudit 2 , or .Xr setaudit_addr 2 has already been called. As a direct result, the terminal ID for the subject will be retrieved from the kernel via .Xr getaudit 2 , or .Xr getaudit_addr 2 . .Sh EXAMPLES .Bd -literal -offset indent #include #include #include #include #include #include void audit_bad_su(char *from_login, char *to_login) { struct auditinfo_addr aia; struct auditinfo ai; au_id_t aid; int error; error = getaudit_addr(&aia, sizeof(aia)); if (error < 0 && errno == ENOSYS) { error = getaudit(&ai); if (error < 0) err(1, "getaudit"); aid = ai.ai_auid; } else if (error < 0) err(1, "getaudit_addr"); else aid = aia.ai_auid; error = audit_submit(AUE_su, aid, EPERM, 1, "bad su from %s to %s", from_login, to_login); if (error != 0) err(1, "audit_submit"); } .Ed .Pp Will generate the following audit record: .Bd -literal -offset indent header,94,1,su(1),0,Mon Apr 17 23:23:59 2006, + 271 msec subject,root,root,wheel,root,wheel,652,652,0,0.0.0.0 text,bad su from from csjp to root return,failure : Operation not permitted,1 trailer,94 .Ed .Sh RETURN VALUES If successful, .Nm will return zero. Otherwise a -1 is returned and the global variable .Va errno is set to indicate the error. .Sh SEE ALSO .Xr auditon 2 , .Xr getaudit 2 , .Xr libbsm 3 , .Xr stdarg 3 .Sh HISTORY The .Fn audit_submit function first appeared in OpenBSM version 1.0. OpenBSM 1.0 was introduced in .Fx 7.0 . .Sh AUTHORS The .Fn audit_submit function was written by .An Christian S.J. Peron Aq csjp@FreeBSD.org . Index: head/lib/libc/gen/feature_present.3 =================================================================== --- head/lib/libc/gen/feature_present.3 (revision 222285) +++ head/lib/libc/gen/feature_present.3 (revision 222286) @@ -1,72 +1,72 @@ .\" Copyright (c) 2008 Yahoo!, Inc. .\" All rights reserved. .\" Written by: John Baldwin .\" .\" 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 author nor the names of any co-contributors .\" may 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 8, 2008 -.Dt feature_present 3 +.Dt FEATURE_PRESENT 3 .Os .Sh NAME .Nm feature_present .Nd query presence of a kernel feature .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In unistd.h .Ft int .Fn feature_present "const char *feature" .Sh DESCRIPTION The .Fn feature_present function provides a method for an application to determine if a specific kernel feature is present in the currently running kernel. The .Fa feature argument specifies the name of the feature to check. The .Fn feature_present function will return 1 if the specified feature is present, otherwise it will return 0. If the .Fn feature_present function is not able to determine the presence of .Fa feature due to an internal error it will return 0. .Sh RETURN VALUES If .Fa feature is present then 1 is returned; otherwise 0 is returned. .Sh SEE ALSO .Xr sysconf 3 , .Xr sysctl 3 .Sh HISTORY The .Fn feature_present function first appeared in .Fx 8.0 . Index: head/share/man/man4/atrtc.4 =================================================================== --- head/share/man/man4/atrtc.4 (revision 222285) +++ head/share/man/man4/atrtc.4 (revision 222286) @@ -1,56 +1,56 @@ .\" Copyright (c) 2010 Alexander Motin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 17, 2010 -.Dt atrtc 4 +.Dt ATRTC 4 .Os .Sh NAME .Nm atrtc .Nd AT Real-Time Clock (RTC) driver .Sh SYNOPSIS This driver is a mandatory part of i386/amd64 kernels. .Pp The following tunable is settable from the .Xr loader 8 : .Bl -ohang .It Va hint.atrtc. Ns Ar X Ns Va .clock controls event timers functionality support. Setting to 0, disables it. Default value is 1. .El .Sh DESCRIPTION This driver uses RTC hardware to supply kernel with time-of-day clock with 1 second resolution and one event timer. This hardware uses base frequency of 32768Hz for advancing time-of-day clock and generating periodic interrupts. Interrupts could be generated with fixed number of frequencies, from 2Hz to 8192Hz, obtained by dividing base frequency by one of supported power-of-2 divisors. .Pp Event timer provided by the driver is irrelevant to CPU power states. .Sh SEE ALSO .Xr attimer 4 , .Xr hpet 4 , .Xr eventtimers 7 Index: head/share/man/man4/attimer.4 =================================================================== --- head/share/man/man4/attimer.4 (revision 222285) +++ head/share/man/man4/attimer.4 (revision 222286) @@ -1,75 +1,75 @@ .\" Copyright (c) 2010 Alexander Motin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 14, 2010 -.Dt attimer 4 +.Dt ATTIMER 4 .Os .Sh NAME .Nm attimer .Nd i8254 Programmable Interval Timer (AT Timer) driver .Sh SYNOPSIS This driver is a mandatory part of x86 kernels. .Pp The following tunables are settable from the .Xr loader 8 : .Bl -ohang .It Va hint.attimer. Ns Ar X Ns Va .clock controls event timers functionality support. Setting to 0, disables it. Default value is 1. .It Va hint.attimer. Ns Ar X Ns Va .timecounter controls time counter functionality support. Setting to 0, disables it. Default value is 1. .It Va hw.i8254.freq allows to override default counter frequency. The same value is also available in run-time via .Va machdep.i8254_freq sysctl. .El .Sh DESCRIPTION This driver uses i8254 Programmable Interval Timer (AT Timer) hardware to supply kernel with one time counter and one event timer, and generate sound tones for system speaker. This hardware includes three channels. Each channel includes 16bit counter, counting down with known, platform-dependent frequency. Counters can operate in several different modes, including periodic and one-shot. Output of each channel has platform-defined wiring: one channel is wired to the interrupt controller and may be used as event timer, one channel is wired to speaker and used to generate sound tones, and one timer is reserved for platform purposes. .Pp Driver uses single hardware channel to provide both time counter and event timer functionality. To make it possible, respective counter must be running in periodic more. As result, one-shot event timer mode supported only when time counter functionality is disabled. .Pp Event timer provided by the driver is irrelevant to CPU power states. .Sh SEE ALSO .Xr atrtc 4 , .Xr hpet 4 , .Xr eventtimers 7 Index: head/share/man/man4/cc.4 =================================================================== --- head/share/man/man4/cc.4 (revision 222285) +++ head/share/man/man4/cc.4 (revision 222286) @@ -1,117 +1,117 @@ .\" .\" Copyright (c) 2010-2011 The FreeBSD Foundation .\" All rights reserved. .\" .\" This documentation was written at the Centre for Advanced Internet .\" Architectures, Swinburne University of Technology, Melbourne, Australia by .\" David Hayes and Lawrence Stewart under sponsorship from the FreeBSD .\" Foundation. .\" .\" 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, 2011 -.Dt cc 4 +.Dt CC 4 .Os .Sh NAME .Nm cc .Nd Modular congestion control .Sh DESCRIPTION The modular congestion control framework allows the TCP implementation to dynamically change the congestion control algorithm used by new and existing connections. Algorithms are identified by a unique .Xr ascii 7 name. Algorithm modules can be compiled into the kernel or loaded as kernel modules using the .Xr kld 4 facility. .Pp The default algorithm is NewReno, and all connections use the default unless explicitly overridden using the TCP_CONGESTION socket option (see .Xr tcp 4 for details). The default can be changed using a .Xr sysctl 3 MIB variable detailed in the .Sx MIB Variables section below. .Sh MIB Variables The framework exposes the following variables in the .Va net.inet.tcp.cc branch of the .Xr sysctl 3 MIB: .Bl -tag -width ".Va available" .It Va available Read-only list of currently available congestion control algorithms by name. .It Va algorithm Returns the current default congestion control algorithm when read, and changes the default when set. When attempting to change the default algorithm, this variable should be set to one of the names listed by the .Va net.inet.tcp.cc.available MIB variable. .El .Sh SEE ALSO .Xr cc_chd 4 , .Xr cc_cubic 4 , .Xr cc_hd 4 , .Xr cc_htcp 4 , .Xr cc_newreno 4 , .Xr cc_vegas 4 , .Xr tcp 4 , .Xr cc 9 .Sh ACKNOWLEDGEMENTS Development and testing of this software were made possible in part by grants from the FreeBSD Foundation and Cisco University Research Program Fund at Community Foundation Silicon Valley. .Sh HISTORY The .Nm modular congestion control framework first appeared in .Fx 9.0 . .Pp The framework was first released in 2007 by James Healy and Lawrence Stewart whilst working on the NewTCP research project at Swinburne University of Technology's Centre for Advanced Internet Architectures, Melbourne, Australia, which was made possible in part by a grant from the Cisco University Research Program Fund at Community Foundation Silicon Valley. More details are available at: .Pp http://caia.swin.edu.au/urp/newtcp/ .Sh AUTHORS .An -nosplit The .Nm facility was written by .An Lawrence Stewart Aq lstewart@FreeBSD.org , .An James Healy Aq jimmy@deefa.com and .An David Hayes Aq david.hayes@ieee.org . .Pp This manual page was written by .An David Hayes Aq david.hayes@ieee.org and .An Lawrence Stewart Aq lstewart@FreeBSD.org . Index: head/share/man/man4/h_ertt.4 =================================================================== --- head/share/man/man4/h_ertt.4 (revision 222285) +++ head/share/man/man4/h_ertt.4 (revision 222286) @@ -1,143 +1,143 @@ .\" .\" Copyright (c) 2010-2011 The FreeBSD Foundation .\" All rights reserved. .\" .\" This documentation was written at the Centre for Advanced Internet .\" Architectures, Swinburne University of Technology, Melbourne, Australia by .\" David Hayes under sponsorship from the FreeBSD Foundation. .\" .\" 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, 2011 -.Dt h_ertt 9 +.Dt H_ERTT 9 .Os .Sh NAME .Nm h_ertt .Nd Enhanced Round Trip Time Khelp module .Sh SYNOPSIS .In netinet/khelp/h_ertt.h .Sh DESCRIPTION The .Nm Khelp module works within the .Xr khelp 9 framework to provide TCP with a per-connection, low noise estimate of the instantaneous RTT. The implementation attempts to be robust in the face of delayed acknowledgements, TCP Segmentation Offload (TSO), receivers who manipulate TCP timestamps and lack of the TCP timestamp option altogether. .Pp TCP receivers using delayed acknowledgements either acknowledge every second packet (reflecting the time stamp of the first) or use a timeout to trigger the acknowledgement if no second packet arrives. If the heuristic used by .Nm determines that the receiver is using delayed acknowledgements, it measures the RTT using the second packet (the one that triggers the acknowledgement). It does not measure the RTT if the acknowledgement is for the first packet, since it cannot be accurately determined. .Pp When TSO is in use, .Nm will momentarily disable TSO whilst marking a packet to use for a new measurement. The process has negligible impact on the connection. .Pp .Nm associates the following struct with each connection's TCP control block: .Bd -literal struct ertt { TAILQ_HEAD(txseginfo_head, txseginfo) txsegi_q; /* Private. */ long bytes_tx_in_rtt; /* Private. */ long bytes_tx_in_marked_rtt; unsigned long marked_snd_cwnd; int rtt; int maxrtt; int minrtt; int dlyack_rx; /* Private. */ int timestamp_errors; /* Private. */ int markedpkt_rtt; /* Private. */ uint32_t flags; }; .Ed .Pp The fields marked as private should not be manipulated by any code outside of the .Nm implementation. The non-private fields provide the following data: .Bl -tag -width ".Va bytes_tx_in_marked_rtt" -offset indent .It Va bytes_tx_in_marked_rtt The number of bytes transmitted in the .Va markedpkt_rtt . .It Va marked_snd_cwnd The value of cwnd for the marked rtt measurement. .It Va rtt The most recent RTT measurement. .It Va maxrtt The longest RTT measurement that has been taken. .It Va minrtt The shortest RTT measurement that has been taken. .It Va flags The ERTT_NEW_MEASUREMENT flag will be set by the implementation when a new measurement is available. It is the responsibility of .Nm consumers to unset the flag if they wish to use it as a notification method for new measurements. .El .Sh SEE ALSO .Xr cc 4 , .Xr cc_chd 4 , .Xr cc_hd 4 , .Xr cc_vegas 4 , .Xr hhook 9 , .Xr khelp 9 .Sh ACKNOWLEDGEMENTS Development and testing of this software were made possible in part by grants from the FreeBSD Foundation and Cisco University Research Program Fund at Community Foundation Silicon Valley. .Sh HISTORY The .Nm module first appeared in .Fx 9.0 . .Pp The module was first released in 2010 by David Hayes whilst working on the NewTCP research project at Swinburne University of Technology's Centre for Advanced Internet Architectures, Melbourne, Australia. More details are available at: .Pp http://caia.swin.edu.au/urp/newtcp/ .Sh AUTHORS .An -nosplit The .Nm Khelp module and this manual page were written by .An David Hayes Aq david.hayes@ieee.org . .Sh BUGS The module maintains enhanced RTT estimates for all new TCP connections created after the time at which the module was loaded. It might be beneficial to see if it is possible to have the module only affect connections which actually care about ERTT estimates. Index: head/share/man/man4/nvram2env.4 =================================================================== --- head/share/man/man4/nvram2env.4 (revision 222285) +++ head/share/man/man4/nvram2env.4 (revision 222286) @@ -1,119 +1,119 @@ .\" Copyright (c) 2011 Aleksandr Rybalko .\" 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 3, 2011 -.Dt nvram2env 4 +.Dt NVRAM2ENV 4 .Os .Sh NAME .Nm nvram2env .Nd "copy nvram-like data into kernel environment" .Sh SYNOPSIS .Cd "device nvram2env" .Sh DESCRIPTION .Nm implements a simple method of reading the NVRAM-like data and information stored in flash and storing it in the kernel environment. It can then be used by various device drivers at boot-time. .Pp The NVRAM-like data is an array of zero terminated strings. Each string contains the string name, "=" delimiter and the string value. .Pp .Nm copies the environment values into kernel environment using the kernel setenv call. .Pp Configuration of .Nm is done in .Xr device.hints 5 defining the NVRAM base address, fallback base address, maxsize and flags. .Pp .Nm is currently MIPS-specific. .Ss base base - physical address where data block is stored. .Ss fallbackbase fallbackbase - physical address where data block is stored, but only if not found at base. .Ss maxsize maxsize - maximum size of data block. .Ss flags flags - control flags, used to select nvram type and enable/disable CRC check. .Bl -tag -width indent .It Fa 0x0001 Avoid CRC checking. Currently CRC checking is not implemented, so to be future compatible, please set it to "1". .It Fa 0x0002 Use format "Generic", skip uint32_t field, then zero terminating array of strings. .It Fa 0x0004 Use Broadcom CFE format. uint32_t signature "FLSH", uint32_t size, three unused fields uint32_t, then data. .It Fa 0x0008 Use U-Boot format, uint32_t crc, then zero terminating array of strings. .El .Sh EXAMPLES Usage in U-Boot case: .Bd -literal -offset indent hint.nvram.0.base=0x1f030000 hint.nvram.0.maxsize=0x2000 hint.nvram.0.flags=3 # 1 = No check, 2 = Format Generic hint.nvram.1.base=0x1f032000 hint.nvram.1.maxsize=0x4000 hint.nvram.1.flags=3 # 1 = No check, 2 = Format Generic .Ed .Pp CFE nvram with fallback: .Bd -literal -offset indent hint.nvram.0.base=0x1fff8000 hint.nvram.0.fallbackbase=0x1fc00400 hint.nvram.0.flags=4 # 4 = Format Broadcom .Ed .Pp but seems for CFE nvram preferred to read both blocks: .Pp NVRAM partition: Static, CFE internal .Bd -literal -offset indent hint.nvram.0.flags=0x05 # Broadcom + nocheck hint.nvram.0.base=0x1fc00400 .Ed .Pp Dynamic, editable form CFE, override values from first .Pp .Bd -literal -offset indent hint.nvram.1.flags=0x05 # Broadcom + nocheck hint.nvram.1.base=0x1cff8000 .Ed .Sh SEE ALSO .Xr kenv 1 , .Xr kenv 2 . .Sh HISTORY .Nm first appeared in .Fx 9.0 . .Sh AUTHORS .An -nosplit .Nm .An Aleksandr Rybalko Aq ray@ddteam.net . Index: head/share/man/man7/eventtimers.7 =================================================================== --- head/share/man/man7/eventtimers.7 (revision 222285) +++ head/share/man/man7/eventtimers.7 (revision 222286) @@ -1,133 +1,133 @@ .\" Copyright (c) 2010 Alexander Motin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 15, 2010 -.Dt eventtimers 4 +.Dt EVENTTIMERS 4 .Os .Sh NAME .Nm eventtimers .Nd kernel event timers subsystem .Sh SYNOPSIS Kernel uses several types of time-related devices, such as: real time clocks, time counters and event timers. Real time clocks responsible for tracking real world time, mostly when system is down. Time counters are responsible for generation of monotonically increasing timestamps for precise uptime tracking purposes, when system is running. Event timers are responsible for generating interrupts at specified time or periodically, to run different time-based events. This page is about the last. .Sh DESCRIPTION Kernel uses time-based events for many different purposes: scheduling, statistics, time keeping, profiling and many other things, based on .Xr callout 9 mechanism. These purposes now grouped into three main callbacks: .Bl -tag .It hardclock() .Xr callout 9 and timekeeping events entry. Called with frequency defined by hz variable, usually 1000Hz. .It statclock() statistics and scheduler events entry. Called with frequency about 128Hz. .It profclock() profiler events entry. When enabled, called with frequency about 8KHz. .El Different platforms provide different kinds of timer hardware. The goal of the event timers subsystem is to provide unified way to control that hardware, and to use it, supplying kernel with all required time-based events. .Pp Each driver implementing event timers, registers them at the subsystem. It is possible to see the list of present event timers, like this, via .Va kern.eventtimer sysctl: .Bd -literal kern.eventtimer.choice: HPET(550) LAPIC(400) i8254(100) RTC(0) kern.eventtimer.et.LAPIC.flags: 15 kern.eventtimer.et.LAPIC.frequency: 0 kern.eventtimer.et.LAPIC.quality: 400 kern.eventtimer.et.i8254.flags: 1 kern.eventtimer.et.i8254.frequency: 1193182 kern.eventtimer.et.i8254.quality: 100 kern.eventtimer.et.RTC.flags: 17 kern.eventtimer.et.RTC.frequency: 32768 kern.eventtimer.et.RTC.quality: 0 kern.eventtimer.et.HPET.flags: 7 kern.eventtimer.et.HPET.frequency: 14318180 kern.eventtimer.et.HPET.quality: 550 .Ed , where: .Bl -tag .It Va kern.eventtimer.et. Ns Ar X Ns Va .flags bitmask, defining event timer capabilities: .Bl -tag -compact .It 1 periodic mode supported, .It 2 one-shot mode supported, .It 4 timer is per-CPU, .It 8 timer may stop when CPU goes to sleep state, .It 16 timer supports only power-of-2 divisors. .El .It Va kern.eventtimer.et. Ns Ar X Ns Va .frequency timer base frequency, .It Va kern.eventtimer.et. Ns Ar X Ns Va .quality integral value, defining how good is this timer, comparing to others. .El .Pp Timers management code of the kernel chooses one timer from that list. Current choice can be read and affected via .Va kern.eventtimer.timer tunable/sysctl. Several other tunables/sysctls are affecting how exactly this timer is used: .Bl -tag .It Va kern.eventtimer.periodic allows to choose periodic and one-shot operation mode. In periodic mode, periodic interrupts from timer hardware are taken as the only source of time for time events. One-shot mode instead uses currently selected time counter to precisely schedule all needed events and programs event timer to generate interrupt exactly in specified time. Default value depends of chosen timer capabilities, but one-shot mode is preferred, until other is forced by user or hardware. .It Va kern.eventtimer.singlemul in periodic mode specifies how much times higher timer frequency should be, to not strictly alias hardclock() and statclock() events. Default values are 1, 2 or 4, depending on configured HZ value. .It Va kern.eventtimer.idletick makes each CPU to receive every timer interrupt independently of whether they busy or not. By default this options is disabled. If chosen timer is per-CPU and runs in periodic mode, this option has no effect - all interrupts are always generating. .El .Sh SEE ALSO .Xr attimer 4 , .Xr atrtc 4 , .Xr hpet 4 Index: head/share/man/man9/devfs_set_cdevpriv.9 =================================================================== --- head/share/man/man9/devfs_set_cdevpriv.9 (revision 222285) +++ head/share/man/man9/devfs_set_cdevpriv.9 (revision 222286) @@ -1,121 +1,121 @@ .\" Copyright (c) 2008 Konstantin Belousov .\" 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 September 8, 2008 -.Dt DEVFS_CDEVPRIV +.Dt DEVFS_CDEVPRIV 9 .Os .Sh NAME .Nm devfs_set_cdevpriv , .Nm devfs_get_cdevpriv , .Nm devfs_clear_cdevpriv .Nd manage per-open filedescriptor data for devices .Sh SYNOPSIS .In sys/param.h .In sys/conf.h .Bd -literal typedef void (*cdevpriv_dtr_t)(void *data); .Ed .Ft int .Fn devfs_get_cdevpriv "void **datap" .Ft int .Fn devfs_set_cdevpriv "void *priv" "cdevpriv_dtr_t dtr" .Ft void .Fn devfs_clear_cdevpriv "void" .Sh DESCRIPTION The .Fn devfs_xxx_cdevpriv family of functions allows the .Fa cdev driver methods to associate some driver-specific data with each user process .Xr open 2 of the device special file. Currently, functioning of these functions is restricted to the context of the .Fa cdevsw switch method calls performed as .Xr devfs 5 operations in response to system calls that use filedescriptors. .Pp The .Fn devfs_set_cdevpriv function associates a data pointed by .Va priv with current calling context (filedescriptor). The data may be retrieved later, possibly from another call performed on this filedescriptor, by the .Fn devfs_get_cdevpriv function. The .Fn devfs_clear_cdevpriv disassociates previously attached data from context. Immediately after .Fn devfs_clear_cdevpriv finished operating, the .Va dtr callback is called, with private data supplied .Va data argument. .Pp On the last filedescriptor close, system automatically arranges .Fn devfs_clear_cdevpriv call. .Pp If successful, the functions return 0. .Pp The function .Fn devfs_set_cdevpriv returns the following values on error: .Bl -tag -width Er .It Bq Er ENOENT The current call is not associated with some filedescriptor. .It Bq Er EBUSY The private driver data is already associated with current filedescriptor. .El .Pp The function .Fn devfs_get_cdevpriv returns the following values on error: .Bl -tag -width Er .It Bq Er EBADF The current call is not associated with some filedescriptor. .It Bq Er ENOENT The private driver data was not associated with current filedescriptor, or .Fn devfs_clear_cdevpriv was called. .El .Sh SEE ALSO .Xr open 2 , .Xr close 2 , .Xr devfs 5 , .Xr kern_openat 9 .Sh HISTORY The .Fn devfs_cdevpriv family of functions first appeared in .Fx 7.1 . Index: head/share/man/man9/hhook.9 =================================================================== --- head/share/man/man9/hhook.9 (revision 222285) +++ head/share/man/man9/hhook.9 (revision 222286) @@ -1,388 +1,388 @@ .\" .\" Copyright (c) 2010-2011 The FreeBSD Foundation .\" All rights reserved. .\" .\" This documentation was written at the Centre for Advanced Internet .\" Architectures, Swinburne University of Technology, Melbourne, Australia by .\" David Hayes and Lawrence Stewart under sponsorship from the FreeBSD .\" Foundation. .\" .\" 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, 2011 -.Dt hhook 9 +.Dt HHOOK 9 .Os .Sh NAME .Nm hhook , .Nm hhook_head_register , .Nm hhook_head_deregister , .Nm hhook_head_deregister_lookup , .Nm hhook_run_hooks , .Nm HHOOKS_RUN_IF , .Nm HHOOKS_RUN_LOOKUP_IF .Nd Helper Hook Framework .Sh SYNOPSIS .In sys/hhook.h .Ft typedef int .Fn "\*(lp*hhook_func_t\*(rp" "int32_t hhook_type" "int32_t hhook_id" \ "void *udata" "void *ctx_data" "void *hdata" "struct osd *hosd" .Fn "int hhook_head_register" "int32_t hhook_type" "int32_t hhook_id" \ "struct hhook_head **hhh" "uint32_t flags" .Fn "int hhook_head_deregister" "struct hhook_head *hhh" .Fn "int hhook_head_deregister_lookup" "int32_t hhook_type" "int32_t hhook_id" .Fn "void hhook_run_hooks" "struct hhook_head *hhh" "void *ctx_data" \ "struct osd *hosd" .Fn HHOOKS_RUN_IF "hhh" "ctx_data" "hosd" .Fn HHOOKS_RUN_LOOKUP_IF "hhook_type" "hhook_id" "ctx_data" "hosd" .Sh DESCRIPTION .Nm provides a framework for managing and running arbitrary hook functions at defined hook points within the kernel. The KPI was inspired by .Xr pfil 9 , and in many respects can be thought of as a more generic superset of pfil. .Pp The .Xr khelp 9 and .Nm frameworks are tightly integrated. Khelp is responsible for registering and deregistering Khelp module hook functions with .Nm points. The KPI functions used by .Xr khelp 9 to do this are not documented here as they are not relevant to consumers wishing to instantiate hook points. .Ss Information for Khelp Module Implementors Khelp modules indirectly interact with .Nm by defining appropriate hook functions for insertion into hook points. Hook functions must conform to the .Ft hhook_func_t function pointer declaration outlined in the .Sx SYNOPSIS . .Pp The .Fa hhook_type and .Fa hhook_id arguments identify the hook point which has called into the hook function. These are useful when a single hook function is registered for multiple hook points and wants to know which hook point has called into it. .In sys/hhook.h lists available .Fa hhook_type defines and subsystems which export hook points are responsible for defining the .Fa hhook_id value in appropriate header files. .Pp The .Fa udata argument will be passed to the hook function if it was specified in the .Vt struct hookinfo at hook registration time. .Pp The .Fa ctx_data argument contains context specific data from the hook point call site. The data type passed is subsystem dependent. .Pp The .Fa hdata argument is a pointer to the persistent per-object storage allocated for use by the module if required. The pointer will only ever be NULL if the module did not request per-object storage. .Pp The .Fa hosd argument can be used with the .Xr khelp 9 framework's .Fn khelp_get_osd function to access data belonging to a different Khelp module. .Pp Khelp modules instruct the Khelp framework to register their hook functions with .Nm points by creating a .Vt "struct hookinfo" per hook point, which contains the following members: .Bd -literal -offset indent struct hookinfo { hhook_func_t hook_func; struct helper *hook_helper; void *hook_udata; int32_t hook_id; int32_t hook_type; }; .Ed .Pp Khelp modules are responsible for setting all members of the struct except .Va hook_helper which is handled by the Khelp framework. .Ss Creating and Managing Hook Points Kernel subsystems that wish to provide .Nm points typically need to make four and possibly five key changes to their implementation: .Bl -bullet .It Define a list of .Va hhook_id mappings in an appropriate subsystem header. .It Register each hook point with the .Fn hhook_head_register function during initialisation of the subsystem. .It Select or create a standardised data type to pass to hook functions as contextual data. .It Add a call to .Fn HHOOKS_RUN_IF or .Fn HHOOKS_RUN_IF_LOOKUP at the point in the subsystem's code where the hook point should be executed. .It If the subsystem can be dynamically added/removed at runtime, each hook point registered with the .Fn hhook_head_register function when the subsystem was initialised needs to be deregistered with the .Fn hhook_head_deregister or .Fn hhook_head_deregister_lookup functions when the subsystem is being deinitialised prior to removal. .El .Pp The .Fn hhook_head_register function registers a hook point with the .Nm framework. The .Fa hook_type argument defines the high level type for the hook point. Valid types are defined in .In sys/hhook.h and new types should be added as required. The .Fa hook_id argument specifies a unique, subsystem specific identifier for the hook point. The .Fa hhh argument will, if not NULL, be used to store a reference to the .Vt struct hhook_head created as part of the registration process. Subsystems will generally want to store a local copy of the .Vt struct hhook_head so that they can use the .Fn HHOOKS_RUN_IF macro to instantiate hook points. The HHOOK_WAITOK flag may be passed in via the .Fa flags argument if .Xr malloc 9 is allowed to sleep waiting for memory to become available. If the hook point is within a virtualised subsystem (e.g. the network stack), the HHOOK_HEADISINVNET flag should be passed in via the .Fa flags argument so that the .Vt struct hhook_head created during the registration process will be added to a virtualised list. .Pp The .Fn hhook_head_deregister function deregisters a previously registered hook point from the .Nm framework. The .Fa hhh argument is the pointer to the .Vt struct hhook_head returned by .Fn hhoook_head_register when the hook point was registered. .Pp The .Fn hhook_head_deregister_lookup function can be used instead of .Fn hhook_head_deregister in situations where the caller does not have a cached copy of the .Vt struct hhook_head and wants to deregister a hook point using the appropriate .Fa hook_type and .Fa hook_id identifiers instead. .Pp The .Fn hhook_run_hooks function should normally not be called directly and should instead be called indirectly via the .Fn HHOOKS_RUN_IF macro. However, there may be circumstances where it is preferable to call the function directly, and so it is documented here for completeness. The .Fa hhh argument references the .Nm point to call all registered hook functions for. The .Fa ctx_data argument specifies a pointer to the contextual hook point data to pass into the hook functions. The .Fa hosd argument should be the pointer to the appropriate object's .Vt struct osd if the subsystem provides the ability for Khelp modules to associate per-object data. Subsystems which do not should pass NULL. .Pp The .Fn HHOOKS_RUN_IF macro is the preferred way to implement hook points. It only calls the .Fn hhook_run_hooks function if at least one hook function is registered for the hook point. By checking for registered hook functions, the macro minimises the cost associated with adding hook points to frequently used code paths by reducing to a simple if test in the common case where no hook functions are registered. The arguments are as described for the .Fn hhook_run_hooks function. .Pp The .Fn HHOOKS_RUN_IF_LOOKUP macro performs the same function as the .Fn HHOOKS_RUN_IF macro, but performs an additional step to look up the .Vt struct hhook_head for the specified .Fa hook_type and .Fa hook_id identifiers. It should not be used except in code paths which are infrequently executed because of the reference counting overhead associated with the look up. .Sh IMPLEMENTATION NOTES Each .Vt struct hhook_head protects its internal list of hook functions with a .Xr rmlock 9 . Therefore, anytime .Fn hhook_run_hooks is called directly or indirectly via the .Fn HHOOKS_RUN_IF or .Fn HHOOKS_RUN_IF_LOOKUP macros, a non-sleepable read lock will be acquired and held across the calls to all registered hook functions. .Sh RETURN VALUES .Fn hhook_head_register returns 0 if no errors occurred. It returns EEXIST if a hook point with the same .Fa hook_type and .Fa hook_id is already registered. It returns EINVAL if the HHOOK_HEADISINVNET flag is not set in .Fa flags because the implementation does not yet support hook points in non-virtualised subsystems (see the .Sx BUGS section for details). It returns ENOMEM if .Xr malloc 9 failed to allocate memory for the new .Vt struct hhook_head . .Pp .Fn hhook_head_deregister and .Fn hhook_head_deregister_lookup return 0 if no errors occurred. They return ENOENT if .Fa hhh is NULL. They return EBUSY if the reference count of .Fa hhh is greater than one. .Sh EXAMPLES A well commented example Khelp module can be found at: .Pa /usr/share/examples/kld/khelp/h_example.c .Pp The .Xr tcp 4 implementation provides two .Nm points which are called for packets sent/received when a connection is in the established phase. Search for HHOOK in the following files: .Pa sys/netinet/tcp_var.h , .Pa sys/netinet/tcp_input.c , .Pa sys/netinet/tcp_output.c and .Pa sys/netinet/tcp_subr.c . .Sh SEE ALSO .Xr khelp 9 .Sh ACKNOWLEDGEMENTS Development and testing of this software were made possible in part by grants from the FreeBSD Foundation and Cisco University Research Program Fund at Community Foundation Silicon Valley. .Sh HISTORY The .Nm framework first appeared in .Fx 9.0 . .Pp The .Nm framework was first released in 2010 by Lawrence Stewart whilst studying at Swinburne University of Technology's Centre for Advanced Internet Architectures, Melbourne, Australia. More details are available at: .Pp http://caia.swin.edu.au/urp/newtcp/ .Sh AUTHORS .An -nosplit The .Nm framework was written by .An Lawrence Stewart Aq lstewart@FreeBSD.org . .Pp This manual page was written by .An David Hayes Aq david.hayes@ieee.org and .An Lawrence Stewart Aq lstewart@FreeBSD.org . .Sh BUGS The framework does not currently support registering hook points in subsystems which have not been virtualised with VIMAGE. Fairly minimal internal changes to the .Nm implementation are required to address this. Index: head/share/man/man9/khelp.9 =================================================================== --- head/share/man/man9/khelp.9 (revision 222285) +++ head/share/man/man9/khelp.9 (revision 222286) @@ -1,438 +1,438 @@ .\" .\" Copyright (c) 2010-2011 The FreeBSD Foundation .\" All rights reserved. .\" .\" This documentation was written at the Centre for Advanced Internet .\" Architectures, Swinburne University of Technology, Melbourne, Australia by .\" David Hayes and Lawrence Stewart under sponsorship from the FreeBSD .\" Foundation. .\" .\" 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, 2011 -.Dt khelp 9 +.Dt KHELP 9 .Os .Sh NAME .Nm khelp , .Nm khelp_init_osd , .Nm khelp_destroy_osd , .Nm khelp_get_id , .Nm khelp_get_osd , .Nm khelp_add_hhook , .Nm khelp_remove_hhook , .Nm KHELP_DECLARE_MOD , .Nm KHELP_DECLARE_MOD_UMA .Nd Kernel Helper Framework .Sh SYNOPSIS .In sys/khelp.h .In sys/module_khelp.h .Fn "int khelp_init_osd" "uint32_t classes" "struct osd *hosd" .Fn "int khelp_destroy_osd" "struct osd *hosd" .Fn "int32_t khelp_get_id" "char *hname" .Fn "void * khelp_get_osd" "struct osd *hosd" "int32_t id" .Fn "int khelp_add_hhook" "struct hookinfo *hki" "uint32_t flags" .Fn "int khelp_remove_hhook" "struct hookinfo *hki" .Fn KHELP_DECLARE_MOD "hname" "hdata" "hhooks" "version" .Fn KHELP_DECLARE_MOD_UMA "hname" "hdata" "hhooks" "version" "ctor" "dtor" .Sh DESCRIPTION .Nm provides a framework for managing .Nm modules, which indirectly use the .Xr hhook 9 KPI to register their hook functions with hook points of interest within the kernel. Khelp modules aim to provide a structured way to dynamically extend the kernel at runtime in an ABI preserving manner. Depending on the subsystem providing hook points, a .Nm module may be able to associate per-object data for maintaining relevant state between hook calls. The .Xr hhook 9 and .Nm frameworks are tightly integrated and anyone interested in .Nm should also read the .Xr hhook 9 manual page thoroughly. .Ss Information for Khelp Module Implementors .Nm modules are represented within the .Nm framework by a .Vt struct helper which has the following members: .Bd -literal -offset indent struct helper { int (*mod_init) (void); int (*mod_destroy) (void); #define HELPER_NAME_MAXLEN 16 char h_name[HELPER_NAME_MAXLEN]; uma_zone_t h_zone; struct hookinfo *h_hooks; uint32_t h_nhooks; uint32_t h_classes; int32_t h_id; volatile uint32_t h_refcount; uint16_t h_flags; TAILQ_ENTRY(helper) h_next; }; .Ed .Pp Modules must instantiate a .Vt struct helper , but are only required to set the .Va h_classes field, and may optionally set the .Va h_flags , .Va mod_init and .Va mod_destroy fields where required. The framework takes care of all other fields and modules should refrain from manipulating them. Using the C99 designated initialiser feature to set fields is encouraged. .Pp If specified, the .Va mod_init function will be run by the .Nm framework prior to completing the registration process. Returning a non-zero value from the .Va mod_init function will abort the registration process and fail to load the module. If specified, the .Va mod_destroy function will be run by the .Nm framework during the deregistration process, after the module has been deregistered by the .Nm framework. The return value is currently ignored. Valid .Nm classes are defined in .In sys/khelp.h . Valid flags are defined in .In sys/module_khelp.h . The HELPER_NEEDS_OSD flag should be set in the .Va h_flags field if the .Nm module requires persistent per-object data storage. There is no programmatic way (yet) to check if a .Nm class provides the ability for .Nm modules to associate persistent per-object data, so a manual check is required. .Pp The .Fn KHELP_DECLARE_MOD and .Fn KHELP_DECLARE_MOD_UMA macros provide convenient wrappers around the .Xr DECLARE_MODULE 9 macro, and are used to register a .Nm module with the .Nm framework. .Fn KHELP_DECLARE_MOD_UMA should only be used by modules which require the use of persistent per-object storage i.e. modules which set the HELPER_NEEDS_OSD flag in their .Vt struct helper Ns 's .Va h_flags field. .Pp The first four arguments common to both macros are as follows. The .Fa hname argument specifies the unique .Xr ascii 7 name for the .Nm module. It should be no longer than HELPER_NAME_MAXLEN-1 characters in length. The .Fa hdata argument is a pointer to the module's .Vt struct helper . The .Fa hhooks argument points to a static array of .Vt struct hookinfo structures. The array should contain a .Vt struct hookinfo for each .Xr hhook 9 point the module wishes to hook, even when using the same hook function multiple times for different .Xr hhook 9 points. The .Fa version argument specifies a version number for the module which will be passed to .Xr MODULE_VERSION 9 . The .Fn KHELP_DECLARE_MOD_UMA macro takes the additional .Fa ctor and .Fa dtor arguments, which specify optional .Xr uma 9 constructor and destructor functions. NULL should be passed where the functionality is not required. .Pp The .Fn khelp_get_id function returns the numeric identifier for the .Nm module with name .Fa hname . .Pp The .Fn khelp_get_osd function is used to obtain the per-object data pointer for a specified .Nm module. The .Fa hosd argument is a pointer to the underlying subsystem object's .Vt struct osd . This is provided by the .Xr hhook 9 framework when calling into a .Nm module's hook function. The .Fa id argument specifies the numeric identifier for the .Nm module to extract the data pointer from .Fa hosd for. The .Fa id is obtained using the .Fn khelp_get_id function. .Pp The .Fn khelp_add_hhook and .Fn khelp_remove_hhook functions allow a .Nm module to dynamically hook/unhook .Xr hhook 9 points at run time. The .Fa hki argument specifies a pointer to a .Vt struct hookinfo which encapsulates the required information about the .Xr hhook 9 point and hook function being manipulated. The HHOOK_WAITOK flag may be passed in via the .Fa flags argument of .Fn khelp_add_hhook if .Xr malloc 9 is allowed to sleep waiting for memory to become available. .Ss Integrating Khelp Into a Kernel Subsystem Most of the work required to allow .Nm modules to do useful things relates to defining and instantiating suitable .Xr hhook 9 points for .Nm modules to hook into. The only additional decision a subsystem needs to make is whether it wants to allow .Nm modules to associate persistent per-object data. Providing support for persistent data storage can allow .Nm modules to perform more complex functionality which may be desirable. Subsystems which want to allow Khelp modules to associate persistent per-object data with one of the subsystem's data structures need to make the following two key changes: .Bl -bullet .It Embed a .Vt struct osd pointer in the structure definition for the object. .It Add calls to .Fn khelp_init_osd and .Fn khelp_destroy_osd to the subsystem code paths which are responsible for respectively initialising and destroying the object. .El .Pp The .Fn khelp_init_osd function initialises the per-object data storage for all currently loaded .Nm modules of appropriate classes which have set the HELPER_NEEDS_OSD flag in their .Va h_flags field. The .Fa classes argument specifies a bitmask of .Nm classes which this subsystem associates with. If a .Nm module matches any of the classes in the bitmask, that module will be associated with the object. The .Fa hosd argument specifies the pointer to the object's .Vt struct osd which will be used to provide the persistent storage for use by .Nm modules. .Pp The .Fn khelp_destroy_osd function frees all memory that was associated with an object's .Vt struct osd by a previous call to .Fn khelp_init_osd . The .Fa hosd argument specifies the pointer to the object's .Vt struct osd which will be purged in preparation for destruction. .Sh IMPLEMENTATION NOTES .Nm modules are protected from being prematurely unloaded by a reference count. The count is incremented each time a subsystem calls .Fn khelp_init_osd causing persistent storage to be allocated for the module, and decremented for each corresponding call to .Fn khelp_destroy_osd . Only when a module's reference count has dropped to zero can the module be unloaded. .Sh RETURN VALUES The .Fn khelp_init_osd function returns zero if no errors occurred. It returns ENOMEM if a .Nm module which requires per-object storage fails to allocate the necessary memory. .Pp The .Fn khelp_destroy_osd function only returns zero to indicate that no errors occurred. .Pp The .Fn khelp_get_id function returns the unique numeric identifier for the registered .Nm module with name .Fa hname . It return -1 if no module with the specified name is currently registered. .Pp The .Fn khelp_get_osd function returns the pointer to the .Nm module's persistent object storage memory. If the module identified by .Fa id does not have persistent object storage registered with the object's .Fa hosd .Vt struct osd , NULL is returned. .Pp The .Fn khelp_add_hhook function returns zero if no errors occurred. It returns ENOENT if it could not find the requested .Xr hhook 9 point. It returns ENOMEM if .Xr malloc 9 failed to allocate memory. It returns EEXIST if attempting to register the same hook function more than once for the same .Xr hhook 9 point. .Pp The .Fn khelp_remove_hhook function returns zero if no errors occurred. It returns ENOENT if it could not find the requested .Xr hhook 9 point. .Sh EXAMPLES A well commented example Khelp module can be found at: .Pa /usr/share/examples/kld/khelp/h_example.c .Pp The Enhanced Round Trip Time (ERTT) .Xr h_ertt 4 .Nm module provides a more complex example of what is possible. .Sh SEE ALSO .Xr h_ertt 4 , .Xr hhook 9 , .Xr osd 9 .Sh ACKNOWLEDGEMENTS Development and testing of this software were made possible in part by grants from the FreeBSD Foundation and Cisco University Research Program Fund at Community Foundation Silicon Valley. .Sh HISTORY The .Nm kernel helper framework first appeared in .Fx 9.0 . .Pp The .Nm framework was first released in 2010 by Lawrence Stewart whilst studying at Swinburne University of Technology's Centre for Advanced Internet Architectures, Melbourne, Australia. More details are available at: .Pp http://caia.swin.edu.au/urp/newtcp/ .Sh AUTHORS .An -nosplit The .Nm framework was written by .An Lawrence Stewart Aq lstewart@FreeBSD.org . .Pp This manual page was written by .An David Hayes Aq david.hayes@ieee.org and .An Lawrence Stewart Aq lstewart@FreeBSD.org . Index: head/tools/tools/ether_reflect/ether_reflect.1 =================================================================== --- head/tools/tools/ether_reflect/ether_reflect.1 (revision 222285) +++ head/tools/tools/ether_reflect/ether_reflect.1 (revision 222286) @@ -1,108 +1,108 @@ .\" Copyright (c) 2008 George V. Neville-Neil .\" 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 23, 2008 -.Dt ether_reflect 1 +.Dt ETHER_REFLECT 1 .Os .Sh NAME .Nm ether_reflect .Nd "reflect ethernet packets" .Sh SYNOPSIS .Nm .Op Fl a Ar ethernet address .Op Fl e Ar ethertype .Op Fl i Ar interface .Op Fl t Ar timeout .Op Fl p .Op Fl d .Sh DESCRIPTION The .Nm command implements a simple ethernet packet reflector using the .Xr PCAP 3 library and .Xr bpf 4 , the Berkeley Packet Filter. The program is useful primarily to test the low level round trip time of packets through an Ethernet interface and/or a switch. Network protocols, such as IP, and the network stack in general are never invoked, only the device driver that implements the particular interface is executed. As the .Nm command uses the .Xr bpf 4 device the user must have root privileges to execute this program. .Pp The options are as follows: .Bl -tag -width ".Fl d Ar argument" .It Fl a Ar address Instead of reversing the ethernet destination and source addresses supply a different destination ethernet address for each packet received. .It Fl e Ar ether type Use a different ethertype than the default, 0x8822, which is the IEEE ether type for driver testing. .It Fl i Ar interface Network interface, which can be found with ifconfig(1). .It Fl t Ar timeout The time, in milliseconds, to wait for a packet. Lower times decrease latency at the cost of CPU. .It Fl p Set the device into promiscuous mode before testing. This is not usually necessary. .It Fl d Debug output. Print various small pieces of debug information. .El .Sh EXAMPLES The following is an example of a typical usage of the .Nm command: .Pp .Dl "ether_reflect -i em0 -t 1" .Pp Reflect all test packets, those with an ether type of 0x8822, which are seen on ineterface em0. The timeout is 1 millisecond. .Pp .Dl "ether_reflect -i em0 -a 00:00:00:aa:bb:cc -t 1" .Pp Rewrite the destination address in each packet to 00:00:00:aa:bb:cc before reflecting the packet. .Sh SEE ALSO .Xr ifconfig 8 , .Xr tcpdump 1 , .Xr pcap 4 , .Xr bpf 2 . .Sh HISTORY The .Nm program first appeared in .Fx 8.0 . .Sh AUTHORS This manual page was written by .An George V. Neville-Neil Aq gnn@FreeBSD.org . .Sh BUGS Should be reported to the author or to net@FreeBSD.org. Index: head/usr.bin/mkcsmapper/mkcsmapper.1 =================================================================== --- head/usr.bin/mkcsmapper/mkcsmapper.1 (revision 222285) +++ head/usr.bin/mkcsmapper/mkcsmapper.1 (revision 222286) @@ -1,89 +1,89 @@ .\" Copyright (c) 2009 Gabor Kovesdan .\" 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. .\" .\" Portions of this text are reprinted and reproduced in electronic form .\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- .\" Portable Operating System Interface (POSIX), The Open Group Base .\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of .\" Electrical and Electronics Engineers, Inc and The Open Group. In the .\" event of any discrepancy between this version and the original IEEE and .\" The Open Group Standard, the original IEEE and The Open Group Standard is .\" the referee document. The original Standard can be obtained online at .\" http://www.opengroup.org/unix/online.html. .\" .\" $FreeBSD$ .\" .Dd Sep 6, 2009 -.Dt mkcsmapper 1 +.Dt MKCSMAPPER 1 .Os .Sh NAME .Nm mkcsmapper .Nd generates hashed conversion data for .Xr iconv 3 .Sh SYNOPSIS .Nm .Op Fl mpd .Fl o .Ar outfile .Ar infile .Sh DESCRIPTION The .Nm utility generates binary conversion data from plain text conversion tables for the .Xr iconv 3 library. The conversion data has two components: The conversion mapping between specific character encodings. A pivot file, which the possible source and destination encoding pairs or the set of mappings to use for a compound encoding. .Pp The following options are available: .Bl -tag -width 0123 .It Fl d Turns on debug mode. .It Fl m Generate mapping data from .Ar infile . .It Fl o Ar outfile Put generated binary data to .Ar outfile . .It Fl p Generate pivot data from .Ar outfile . .El .Sh EXIT STATUS .Ex -std mkcsmapper .Sh SEE ALSO .Xr iconv 1 , .Xr iconv 3 , .Xr mkesdb 1 .Sh HISTORY .Nm first appeared in .Nx 2.0 , and made its appearance in .Fx 9.0 . .Sh AUTHORS This manual page was written by .An Gabor Kovesdan Aq gabor@FreeBSD.org . Index: head/usr.bin/mkesdb/mkesdb.1 =================================================================== --- head/usr.bin/mkesdb/mkesdb.1 (revision 222285) +++ head/usr.bin/mkesdb/mkesdb.1 (revision 222286) @@ -1,84 +1,84 @@ .\" Copyright (c) 2009 Gabor Kovesdan .\" 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. .\" .\" Portions of this text are reprinted and reproduced in electronic form .\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- .\" Portable Operating System Interface (POSIX), The Open Group Base .\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of .\" Electrical and Electronics Engineers, Inc and The Open Group. In the .\" event of any discrepancy between this version and the original IEEE and .\" The Open Group Standard, the original IEEE and The Open Group Standard is .\" the referee document. The original Standard can be obtained online at .\" http://www.opengroup.org/unix/online.html. .\" .\" $FreeBSD$ .\" .Dd November 1, 2009 -.Dt mkesdb 1 +.Dt MKESDB 1 .Os .Sh NAME .Nm mkesdb .Nd generates conversion catalog for .Xr iconv 3 .Sh SYNOPSIS .Nm .Op Fl md .Fl o .Ar outfile .Ar infile .Sh DESCRIPTION The .Nm utility generates conversion catalog for the .Xr iconv 3 library. The generated data includes a list of supported encodings and their most important characteristics, like the pluggable module to use .Pp The following options are available: .Bl -tag -width 0123 .It Fl d Turns on debug mode. .It Fl m Process directory catalog or alias file. If not specified, the input file is treated as an encoding description. .It Fl o Ar outfile Put generated binary data to .Ar outfile . .El .Sh EXIT STATUS .Ex -std mkesdb .Sh SEE ALSO .Xr iconv 1 , .Xr iconv 3 , .Xr mkcsmapper 1 .Sh HISTORY .Nm first appeared in .Nx 2.0 , and made its appearance in .Fx 9.0 . .Sh AUTHORS This manual page was written by .An Gabor Kovesdan Aq gabor@FreeBSD.org . Index: head/usr.sbin/bsnmpd/modules/snmp_bridge/snmp_bridge.3 =================================================================== --- head/usr.sbin/bsnmpd/modules/snmp_bridge/snmp_bridge.3 (revision 222285) +++ head/usr.sbin/bsnmpd/modules/snmp_bridge/snmp_bridge.3 (revision 222286) @@ -1,119 +1,119 @@ .\"- .\" Copyright (C) 2006 Shteryana Shopova .\" 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 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 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 6, 2007 -.Dt snmp_bridge 3 +.Dt SNMP_BRIDGE 3 .Os .Sh NAME .Nm snmp_bridge .Nd "bridge module for snmpd" .Sh LIBRARY .Pq begemotSnmpdModulePath."bridge" = "/usr/lib/snmp_bridge.so" .Sh DESCRIPTION The .Nm snmp_bridge module implements the BRIDGE-MIB as standardized in RFC 4188, the RSTP-MIB standardized in RFC4318 and a private BEGEMOT-BRIDGE-MIB, which allows management of multiple bridge interfaces. Most of the objects defined in the private BEGEMOT-BRIDGE-MIB are duplicates of the original objects defined by the standard BRIDGE-MIB, but the private MIB also defines additional objects which make the functionality of .Nm similar to .Xr ifconfig 8 for configuring bridge interfaces. Therefore one should consider adding write communities or loading the .Nm module on systems where security is crucial. .Sh IMPLEMENTATION NOTES The additional objects to configure a bridge are: .Bl -tag -width "XXXXXXXXX" .It Va begemotBridgeBaseStatus Bridge interfaces can be created and destroyed via this object. SNMP SET operations with the following values are allowed: .Bl -tag -width ".It Va createAndWait" .It Va createAndWait will attempt to create a bridge interface with the name given by the table index. .It Va createAndGo will attempt to create a bridge interface with the name given by the table index and set the status of the interface to "active/up". .It Va destroy will attempt to destroy the bridge interface. .El .It Va begemotBridgeBaseSpanEnabled A SNMP SET operation on this object is only successful if the corresponding port has not been added as member of the bridge interface on the system. .It Va begemotBridgeBasePortStatus SNMP SET operations with the following values are allowed: .Bl -tag -width ".It Va createAndWait" .It Va createAndWait will create a new row for the bridge member in the SNMP .Va begemotBridgeBasePortTable but will not try to commit the information to the system. .It Va active will attempt to commit the information to the system and will be successful only if a value for .Va begemotBridgeBaseSpanEnabled has been SET already. .It Va destroy will attempt to remove the interface from the system bridge interface. .El .It Va begemotBridgeBasePortPrivate This object controls a bridge interface flag called PRIVATE where any private port can not communicate with another private port. .El .Sh RESTRICTIONS Not all information in the MIBs is currently available in FreeBSD. The following variables carry no information: .Bl -tag -width "XXXXXXXXX" .It Va dot1dBasePortCircuit .It Va dot1dBasePortDelayExceededDiscards .It Va dot1dBasePortMtuExceededDiscards .It Va begemotBridgeBasePortDelayExceededDiscards .It Va begemotBridgeBasePortMtuExceededDiscards .El .Sh FILES .Bl -tag -width "XXXXXXXXX" .It Pa /usr/share/snmp/defs/bridge_tree.def The description of the MIB tree implemented by .Nm . .It Pa /usr/share/snmp/mibs/BRIDGE-MIB.txt This is the BRIDGE-MIB that is implemented by this module. .It Pa /usr/share/snmp/mibs/RSTP-MIB.txt This is the RSTP-MIB implemented by this module. .It Pa /usr/share/snmp/mibs/BEGEMOT-BRIDGE-MIB.txt This is the private BEGEMOT-BRIDGE-MIB that is implemented by this module. .El .Sh SEE ALSO .Xr bsnmpd 1 , .Xr gensnmptree 1 , .Xr if_bridge 4 , .Xr ifconfig 8 , .Xr snmpmod 3 .Sh AUTHORS .An Shteryana Shopova Aq syrinx@FreeBSD.org Index: head/usr.sbin/bsnmpd/modules/snmp_hostres/snmp_hostres.3 =================================================================== --- head/usr.sbin/bsnmpd/modules/snmp_hostres/snmp_hostres.3 (revision 222285) +++ head/usr.sbin/bsnmpd/modules/snmp_hostres/snmp_hostres.3 (revision 222286) @@ -1,88 +1,88 @@ .\" .\" Copyright (C) 2005-2006 .\" The FreeBSD Project. .\" All rights reserved. .\" .\" Author: Harti Brandt .\" .\" 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 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 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 3, 2006 -.Dt snmp_hostres 3 +.Dt SNMP_HOSTRES 3 .Os .Sh NAME .Nm snmp_hostres .Nd host resources module for .Xr bsnmpd 8 .Sh LIBRARY .Pq begemotSnmpdModulePath."hostres" = "/usr/lib/snmp_hostres.so" .Sh DESCRIPTION The .Nm module implements the HOST-RESOURCES-MIB as standardized in RFC 2790. .Sh RESTRICTIONS Not all information in the MIB is meaningful in FreeBSD or is available. The following variables are not implemented or carry no information: .Bl -tag -width indent .It Va hrFSType There are several types of file systems for which no appropriate OID exists yet which are supported by .Fx . For smbfs, procfs and devfs , .Va hrFSOther is returned. In all other cases, .Va hrFSUnknown . .It Va hrFSBootable It is questionable what bootable means here. Does it mean that the BIOS is available to start a boot on that file system or does it mean that there is something bootable? In either case this information is not available so this variable returns True for the root file system (which is not necessarily correct) and False for all others. .It Va hrFSLastFullBackupDate , hrFSLastPartialBackupDate This is not available and always returns an empty string. Theoretically, this could be retrieved from .Pa /etc/dumpdates , which would hardly be correct given the different ways of doing backups. .It Va hrDiskStorageTable Floppy devices are currently not reported. Also the names of the disks are hard-coded in the module. .El .Sh FILES .Bl -tag -width indent .It Pa /usr/share/snmp/defs/hostres_tree.def The description of the MIB tree implemented by .Nm . .It Pa /usr/share/snmp/mibs/HOST-RESOURCES-TYPES.txt .It Pa /usr/share/snmp/mibs/HOST-RESOURCES-MIB.txt .It Pa /usr/share/snmp/mibs/BEGEMOT-HOSTRES-MIB.txt This is the MIB that is implemented by this module. .El .Sh SEE ALSO .Xr gensnmptree 1 , .Xr snmpmod 3 .Sh AUTHORS .An Victor Cruceru Aq soc-victor@FreeBSD.org Index: head/usr.sbin/bsnmpd/modules/snmp_wlan/snmp_wlan.3 =================================================================== --- head/usr.sbin/bsnmpd/modules/snmp_wlan/snmp_wlan.3 (revision 222285) +++ head/usr.sbin/bsnmpd/modules/snmp_wlan/snmp_wlan.3 (revision 222286) @@ -1,160 +1,160 @@ .\"- .\" Copyright (C) 2010 The FreeBSD Foundation .\" All rights reserved. .\" .\" This documentation was written by Shteryana Sotirova Shopova under .\" sponsorship from the FreeBSD Foundation. .\" .\" 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 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 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 June 28, 2010 -.Dt snmp_wlan 3 +.Dt SNMP_WLAN 3 .Os .Sh NAME .Nm snmp_wlan .Nd "wireless networking module for .Xr bsnmpd 1 .Sh LIBRARY .Pq begemotSnmpdModulePath."wlan" = "/usr/lib/snmp_wlan.so" .Sh DESCRIPTION The .Nm snmp_wlan module implements a private BEGEMOT-WIRELESS-MIB, which allows management of virtual wireless interfaces. The MIB defines objects similar to the state data and configuration capabilities of .Xr ifconfig 8 for configuring virtual wireless interfaces. Therefore one should consider adding write communities or loading the .Nm module on systems where security is crucial. .Sh IMPLEMENTATION NOTES A short description of the Tables and interesting objects in the MIB follows. .Bl -tag -width "XXXXXXXXX" .It Va wlanInterfaceTable The table is used for creation and deletion of virtual wireless interfaces. To add a new interface, a SET should be executed on the .Va wlanIfaceName column with value the desired name of the interface. Next the parent interface must be set via .Va wlanParentIfName column. Any optional parameters may be set via the .Va wlanIfaceOperatingMode, .Va wlanIfaceFlags, .Va wlanIfaceBssid and .Va wlanIfaceLocalAddress columns. To finally create the interface in the system, a SET with value of active(1) to .Va wlanIfaceStatus column should be executed. To destroy a wireless interface a SET with value of destroy(6) to the relevant .Va wlanIfaceStatus column should be executed. .It Va wlanIfParentTable The table contains information about the hardware capabilities of the parent of a wireless interface. .It Va wlanIfaceConfigTable The table is used to get or set various configuration parameters for a virtual wireless interface. Depending on the operating mode of the interface and the hardware capabilities of the underlying hardware interface, not all parameters and values may be supported. .It Va wlanIfacePeerTable The table contains information about the associated stations for interfaces operating as access points, or the stations identified as neighbors in the IBSS for interfaces operating in adhoc mode. .It Va wlanIfaceChannelTable Information about the active channels for the wireless interfaces in the system. .It Va wlanIfRoamParamsTable The parameters that govern the roaming operation on the wireless interfaces. .It Va wlanIfTxParamsTable The parameters that govern the transmit operation on the wireless interfaces. .It Va wlanScanConfigTable The table that contains a configuration for channel scanning initiated via SNMP. .It Va wlanScanResultsTable The table contains the scan results from the last scan for each wireless interface on the system. .It Va wlanIfaceStatisticsTable Summary statistics for each wireless interface on the system. .It Va wlanWepInterfaceTable WEP configuration for the wireless interfaces on the system. .It Va wlanMACAccessControlTable Access Control configuration for wireless interfaces operating as access points. .It Va wlanMACAccessControlMACTable The table with Access Control MAC entries for which the configured Access Control Policy on wireless interfaces operating in Host AP mode is applied. .Va wlanMACAccessControlMACStatus column is used to add or delete MAC ACL entries. A set with value createAndGo(4) will add new entry, while with value destroy(6) will delete an existing one. .It Va wlanMeshRoutingConfig The subtree contains system configuration related to Wireless Mesh Routing. .It Va wlanMeshInterfaceTable The table contains information for wireless interfaces operating as wireless mesh points. .It Va wlanMeshNeighborTable The table contains information for the neighbors of wireless interfaces operating in mesh mode. .It Va wlanMeshRouteTable The mesh routing table for interfaces operating as mesh points, used for forwarding packets on a mesh network. .Va wlanMeshRouteStatus column is used to add or delete entries in the mesh routing table for an interface. A set with value createAndGo(4) will add new entry, while with value destroy(6) will delete an existing one. .It Va wlanMeshStatsTable Summary statistics for each virtual wireless interface operating as mesh point. .It Va wlanMeshHWMPConfig The subtree contains system configuration related to Hybrid Wireless Mesh Protocol. .It Va wlanHWMPInterfaceTable The table contains HWMP information for wireless interfaces operating in mesh mode. .It Va wlanMeshHWMPStatsTable Summary statistics for HWMP operation on interfaces operating as mesh points. .El .Sh RESTRICTIONS Not all information or configuration in the MIBs is currently available in FreeBSD. The values of the following variables carry no information: .Bl -tag -width "XXXXXXXXX" .It Va wlanStatsReset .El .Sh FILES .Bl -tag -width "XXXXXXXXX" .It Pa /usr/share/snmp/defs/wlan_tree.def The description of the MIB tree implemented by .Nm . .It Pa /usr/share/snmp/mibs/BEGEMOT-WIRELESS-MIB.txt The private BEGEMOT-WIRELESS-MIB that is implemented by this module. .El .Sh SEE ALSO .Xr bsnmpd 1 , .Xr gensnmptree 1 , .Xr wlan 4 , .Xr wlan_acl 4 , .Xr wlan_wep 4 , .Xr ifconfig 8 , .Xr snmpmod 3 .Sh AUTHORS .An Shteryana Shopova Aq syrinx@FreeBSD.org Index: head/usr.sbin/usbdump/usbdump.8 =================================================================== --- head/usr.sbin/usbdump/usbdump.8 (revision 222285) +++ head/usr.sbin/usbdump/usbdump.8 (revision 222286) @@ -1,132 +1,132 @@ .\" .\" Copyright (c) 2010 Weongyo Jeong. .\" 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 4, 2010 -.Dt usbdump 8 +.Dt USBDUMP 8 .Os .Sh NAME .Nm usbdump .Nd "dump traffic on USB host controller" .Sh SYNOPSIS .Nm .Op Fl i Ar ifname .Op Fl r Ar file .Op Fl s Ar snaplen .Op Fl v .Op Fl w Ar file .Sh DESCRIPTION The .Nm utility provides a way to dump USB packets on host controllers. .Pp The following options are accepted: .Bl -tag -width ".Fl f Ar file" .It Fl i Ar ifname Listen on USB bus interface .Ar ifname . .It Fl r Ar file Read the raw packets from .Ar file . .It Fl s Ar snaplen Snapshot .Ar snaplen bytes from each packet. .It Fl v Enable debugging messages. When defined multiple times the verbosity level increases. .It Fl w Ar file Write the raw packets to .Ar file . .El .Sh EXAMPLES Captures USB raw packets on usbus2: .Pp .Dl "usbdump -i usbus2 -s 256 -v" .Pp Dumps the USB raw packets of usbus2 into the file without packet size limit: .Pp .Dl "usbdump -i usbus2 -s 0 -w /tmp/dump_pkts" .Pp Read the USB raw packets from previous file: .Pp .Dl "usbdump -r /tmp/dump_pkts -v" .Sh OUTPUT FORMAT The output format of .Nm is as follows: .Pp .Dl "