Index: head/share/man/man3/pthread_mutex_lock.3 =================================================================== --- head/share/man/man3/pthread_mutex_lock.3 (revision 162403) +++ head/share/man/man3/pthread_mutex_lock.3 (revision 162404) @@ -1,78 +1,78 @@ .\" Copyright (c) 1997 Brian Cully .\" 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 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 JOHN BIRRELL 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 8, 2005 +.Dd January 31, 2006 .Dt PTHREAD_MUTEX_LOCK 3 .Os .Sh NAME .Nm pthread_mutex_lock .Nd lock a mutex .Sh LIBRARY .Lb libc_r .Lb libpthread .Lb libthr .Sh SYNOPSIS .In pthread.h .Ft int .Fn pthread_mutex_lock "pthread_mutex_t *mutex" .Sh DESCRIPTION The .Fn pthread_mutex_lock function locks .Fa mutex . If the mutex is already locked, the calling thread will block until the mutex becomes available. .Sh RETURN VALUES If successful, .Fn pthread_mutex_lock will return zero, otherwise an error number will be returned to indicate the error. .Sh ERRORS The .Fn pthread_mutex_lock function will fail if: .Bl -tag -width Er .It Bq Er EINVAL The value specified by .Fa mutex is invalid. .It Bq Er EDEADLK A deadlock would occur if the thread blocked waiting for .Fa mutex . .El .Sh SEE ALSO .Xr pthread_mutex_destroy 3 , .Xr pthread_mutex_init 3 , .Xr pthread_mutex_trylock 3 , .Xr pthread_mutex_unlock 3 .Sh STANDARDS The .Fn pthread_mutex_lock function conforms to .St -p1003.1-96 . Index: head/share/man/man3/queue.3 =================================================================== --- head/share/man/man3/queue.3 (revision 162403) +++ head/share/man/man3/queue.3 (revision 162404) @@ -1,979 +1,979 @@ .\" Copyright (c) 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. .\" .\" @(#)queue.3 8.2 (Berkeley) 1/24/94 .\" $FreeBSD$ .\" -.Dd January 24, 1994 +.Dd March 24, 2006 .Dt QUEUE 3 .Os .Sh NAME .Nm SLIST_EMPTY , .Nm SLIST_ENTRY , .Nm SLIST_FIRST , .Nm SLIST_FOREACH , .Nm SLIST_FOREACH_SAFE , .Nm SLIST_HEAD , .Nm SLIST_HEAD_INITIALIZER , .Nm SLIST_INIT , .Nm SLIST_INSERT_AFTER , .Nm SLIST_INSERT_HEAD , .Nm SLIST_NEXT , .Nm SLIST_REMOVE_HEAD , .Nm SLIST_REMOVE , .Nm STAILQ_CONCAT , .Nm STAILQ_EMPTY , .Nm STAILQ_ENTRY , .Nm STAILQ_FIRST , .Nm STAILQ_FOREACH , .Nm STAILQ_FOREACH_SAFE , .Nm STAILQ_HEAD , .Nm STAILQ_HEAD_INITIALIZER , .Nm STAILQ_INIT , .Nm STAILQ_INSERT_AFTER , .Nm STAILQ_INSERT_HEAD , .Nm STAILQ_INSERT_TAIL , .Nm STAILQ_LAST , .Nm STAILQ_NEXT , .Nm STAILQ_REMOVE_HEAD , .Nm STAILQ_REMOVE , .Nm LIST_EMPTY , .Nm LIST_ENTRY , .Nm LIST_FIRST , .Nm LIST_FOREACH , .Nm LIST_FOREACH_SAFE , .Nm LIST_HEAD , .Nm LIST_HEAD_INITIALIZER , .Nm LIST_INIT , .Nm LIST_INSERT_AFTER , .Nm LIST_INSERT_BEFORE , .Nm LIST_INSERT_HEAD , .Nm LIST_NEXT , .Nm LIST_REMOVE , .Nm TAILQ_CONCAT , .Nm TAILQ_EMPTY , .Nm TAILQ_ENTRY , .Nm TAILQ_FIRST , .Nm TAILQ_FOREACH , .Nm TAILQ_FOREACH_SAFE , .Nm TAILQ_FOREACH_REVERSE , .Nm TAILQ_FOREACH_REVERSE_SAFE , .Nm TAILQ_HEAD , .Nm TAILQ_HEAD_INITIALIZER , .Nm TAILQ_INIT , .Nm TAILQ_INSERT_AFTER , .Nm TAILQ_INSERT_BEFORE , .Nm TAILQ_INSERT_HEAD , .Nm TAILQ_INSERT_TAIL , .Nm TAILQ_LAST , .Nm TAILQ_NEXT , .Nm TAILQ_PREV , .Nm TAILQ_REMOVE .Nd implementations of singly-linked lists, singly-linked tail queues, lists and tail queues .Sh SYNOPSIS .In sys/queue.h .\" .Fn SLIST_EMPTY "SLIST_HEAD *head" .Fn SLIST_ENTRY "TYPE" .Fn SLIST_FIRST "SLIST_HEAD *head" .Fn SLIST_FOREACH "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" .Fn SLIST_FOREACH_SAFE "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" "TYPE *temp_var" .Fn SLIST_HEAD "HEADNAME" "TYPE" .Fn SLIST_HEAD_INITIALIZER "SLIST_HEAD head" .Fn SLIST_INIT "SLIST_HEAD *head" .Fn SLIST_INSERT_AFTER "TYPE *listelm" "TYPE *elm" "SLIST_ENTRY NAME" .Fn SLIST_INSERT_HEAD "SLIST_HEAD *head" "TYPE *elm" "SLIST_ENTRY NAME" .Fn SLIST_NEXT "TYPE *elm" "SLIST_ENTRY NAME" .Fn SLIST_REMOVE_HEAD "SLIST_HEAD *head" "SLIST_ENTRY NAME" .Fn SLIST_REMOVE "SLIST_HEAD *head" "TYPE *elm" "TYPE" "SLIST_ENTRY NAME" .\" .Fn STAILQ_CONCAT "STAILQ_HEAD *head1" "STAILQ_HEAD *head2" .Fn STAILQ_EMPTY "STAILQ_HEAD *head" .Fn STAILQ_ENTRY "TYPE" .Fn STAILQ_FIRST "STAILQ_HEAD *head" .Fn STAILQ_FOREACH "TYPE *var" "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" .Fn STAILQ_FOREACH_SAFE "TYPE *var" "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" "TYPE *temp_var" .Fn STAILQ_HEAD "HEADNAME" "TYPE" .Fn STAILQ_HEAD_INITIALIZER "STAILQ_HEAD head" .Fn STAILQ_INIT "STAILQ_HEAD *head" .Fn STAILQ_INSERT_AFTER "STAILQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "STAILQ_ENTRY NAME" .Fn STAILQ_INSERT_HEAD "STAILQ_HEAD *head" "TYPE *elm" "STAILQ_ENTRY NAME" .Fn STAILQ_INSERT_TAIL "STAILQ_HEAD *head" "TYPE *elm" "STAILQ_ENTRY NAME" .Fn STAILQ_LAST "STAILQ_HEAD *head" "TYPE" "STAILQ_ENTRY NAME" .Fn STAILQ_NEXT "TYPE *elm" "STAILQ_ENTRY NAME" .Fn STAILQ_REMOVE_HEAD "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" .Fn STAILQ_REMOVE "STAILQ_HEAD *head" "TYPE *elm" "TYPE" "STAILQ_ENTRY NAME" .\" .Fn LIST_EMPTY "LIST_HEAD *head" .Fn LIST_ENTRY "TYPE" .Fn LIST_FIRST "LIST_HEAD *head" .Fn LIST_FOREACH "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" .Fn LIST_FOREACH_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" .Fn LIST_HEAD "HEADNAME" "TYPE" .Fn LIST_HEAD_INITIALIZER "LIST_HEAD head" .Fn LIST_INIT "LIST_HEAD *head" .Fn LIST_INSERT_AFTER "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" .Fn LIST_INSERT_BEFORE "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" .Fn LIST_INSERT_HEAD "LIST_HEAD *head" "TYPE *elm" "LIST_ENTRY NAME" .Fn LIST_NEXT "TYPE *elm" "LIST_ENTRY NAME" .Fn LIST_REMOVE "TYPE *elm" "LIST_ENTRY NAME" .\" .Fn TAILQ_CONCAT "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TAILQ_ENTRY NAME" .Fn TAILQ_EMPTY "TAILQ_HEAD *head" .Fn TAILQ_ENTRY "TYPE" .Fn TAILQ_FIRST "TAILQ_HEAD *head" .Fn TAILQ_FOREACH "TYPE *var" "TAILQ_HEAD *head" "TAILQ_ENTRY NAME" .Fn TAILQ_FOREACH_SAFE "TYPE *var" "TAILQ_HEAD *head" "TAILQ_ENTRY NAME" "TYPE *temp_var" .Fn TAILQ_FOREACH_REVERSE "TYPE *var" "TAILQ_HEAD *head" "HEADNAME" "TAILQ_ENTRY NAME" .Fn TAILQ_FOREACH_REVERSE_SAFE "TYPE *var" "TAILQ_HEAD *head" "HEADNAME" "TAILQ_ENTRY NAME" "TYPE *temp_var" .Fn TAILQ_HEAD "HEADNAME" "TYPE" .Fn TAILQ_HEAD_INITIALIZER "TAILQ_HEAD head" .Fn TAILQ_INIT "TAILQ_HEAD *head" .Fn TAILQ_INSERT_AFTER "TAILQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "TAILQ_ENTRY NAME" .Fn TAILQ_INSERT_BEFORE "TYPE *listelm" "TYPE *elm" "TAILQ_ENTRY NAME" .Fn TAILQ_INSERT_HEAD "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" .Fn TAILQ_INSERT_TAIL "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" .Fn TAILQ_LAST "TAILQ_HEAD *head" "HEADNAME" .Fn TAILQ_NEXT "TYPE *elm" "TAILQ_ENTRY NAME" .Fn TAILQ_PREV "TYPE *elm" "HEADNAME" "TAILQ_ENTRY NAME" .Fn TAILQ_REMOVE "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" .\" .Sh DESCRIPTION These macros define and operate on four types of data structures: singly-linked lists, singly-linked tail queues, lists, and tail queues. All four structures support the following functionality: .Bl -enum -compact -offset indent .It Insertion of a new entry at the head of the list. .It Insertion of a new entry after any element in the list. .It O(1) removal of an entry from the head of the list. .It O(n) removal of any entry in the list. .It Forward traversal through the list. .El .Pp Singly-linked lists are the simplest of the four data structures and support only the above functionality. Singly-linked lists are ideal for applications with large datasets and few or no removals, or for implementing a LIFO queue. .Pp Singly-linked tail queues add the following functionality: .Bl -enum -compact -offset indent .It Entries can be added at the end of a list. .It They may be concatenated. .El However: .Bl -enum -compact -offset indent .It All list insertions must specify the head of the list. .It Each head entry requires two pointers rather than one. .It Code size is about 15% greater and operations run about 20% slower than singly-linked lists. .El .Pp Singly-linked tailqs are ideal for applications with large datasets and few or no removals, or for implementing a FIFO queue. .Pp All doubly linked types of data structures (lists and tail queues) additionally allow: .Bl -enum -compact -offset indent .It Insertion of a new entry before any element in the list. .It O(1) removal of any entry in the list. .El However: .Bl -enum -compact -offset indent .It Each elements requires two pointers rather than one. .It Code size and execution time of operations (except for removal) is about twice that of the singly-linked data-structures. .El .Pp Linked lists are the simplest of the doubly linked data structures and support only the above functionality over singly-linked lists. .Pp Tail queues add the following functionality: .Bl -enum -compact -offset indent .It Entries can be added at the end of a list. .It They may be traversed backwards, from tail to head. .It They may be concatenated. .El However: .Bl -enum -compact -offset indent .It All list insertions and removals must specify the head of the list. .It Each head entry requires two pointers rather than one. .It Code size is about 15% greater and operations run about 20% slower than singly-linked lists. .El .Pp In the macro definitions, .Fa TYPE is the name of a user defined structure, that must contain a field of type .Li SLIST_ENTRY , .Li STAILQ_ENTRY , .Li LIST_ENTRY , or .Li TAILQ_ENTRY , named .Fa NAME . The argument .Fa HEADNAME is the name of a user defined structure that must be declared using the macros .Li SLIST_HEAD , .Li STAILQ_HEAD , .Li LIST_HEAD , or .Li TAILQ_HEAD . See the examples below for further explanation of how these macros are used. .Sh SINGLY-LINKED LISTS A singly-linked list is headed by a structure defined by the .Nm SLIST_HEAD macro. This structure contains a single pointer to the first element on the list. The elements are singly linked for minimum space and pointer manipulation overhead at the expense of O(n) removal for arbitrary elements. New elements can be added to the list after an existing element or at the head of the list. An .Fa SLIST_HEAD structure is declared as follows: .Bd -literal -offset indent SLIST_HEAD(HEADNAME, TYPE) head; .Ed .Pp where .Fa HEADNAME is the name of the structure to be defined, and .Fa TYPE is the type of the elements to be linked into the list. A pointer to the head of the list can later be declared as: .Bd -literal -offset indent struct HEADNAME *headp; .Ed .Pp (The names .Li head and .Li headp are user selectable.) .Pp The macro .Nm SLIST_HEAD_INITIALIZER evaluates to an initializer for the list .Fa head . .Pp The macro .Nm SLIST_EMPTY evaluates to true if there are no elements in the list. .Pp The macro .Nm SLIST_ENTRY declares a structure that connects the elements in the list. .Pp The macro .Nm SLIST_FIRST returns the first element in the list or NULL if the list is empty. .Pp The macro .Nm SLIST_FOREACH traverses the list referenced by .Fa head in the forward direction, assigning each element in turn to .Fa var . .Pp The macro .Nm SLIST_FOREACH_SAFE traverses the list referenced by .Fa head in the forward direction, assigning each element in turn to .Fa var . However, unlike .Fn SLIST_FOREACH here it is permitted to both remove .Fa var as well as free it from within the loop safely without interfering with the traversal. .Pp The macro .Nm SLIST_INIT initializes the list referenced by .Fa head . .Pp The macro .Nm SLIST_INSERT_HEAD inserts the new element .Fa elm at the head of the list. .Pp The macro .Nm SLIST_INSERT_AFTER inserts the new element .Fa elm after the element .Fa listelm . .Pp The macro .Nm SLIST_NEXT returns the next element in the list. .Pp The macro .Nm SLIST_REMOVE_HEAD removes the element .Fa elm from the head of the list. For optimum efficiency, elements being removed from the head of the list should explicitly use this macro instead of the generic .Fa SLIST_REMOVE macro. .Pp The macro .Nm SLIST_REMOVE removes the element .Fa elm from the list. .Sh SINGLY-LINKED LIST EXAMPLE .Bd -literal SLIST_HEAD(slisthead, entry) head = SLIST_HEAD_INITIALIZER(head); struct slisthead *headp; /* Singly-linked List head. */ struct entry { ... SLIST_ENTRY(entry) entries; /* Singly-linked List. */ ... } *n1, *n2, *n3, *np; SLIST_INIT(&head); /* Initialize the list. */ n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ SLIST_INSERT_HEAD(&head, n1, entries); n2 = malloc(sizeof(struct entry)); /* Insert after. */ SLIST_INSERT_AFTER(n1, n2, entries); SLIST_REMOVE(&head, n2, entry, entries);/* Deletion. */ free(n2); n3 = SLIST_FIRST(&head); SLIST_REMOVE_HEAD(&head, entries); /* Deletion from the head. */ free(n3); /* Forward traversal. */ SLIST_FOREACH(np, &head, entries) np-> ... /* Safe forward traversal. */ SLIST_FOREACH_SAFE(np, &head, entries, np_temp) { np->do_stuff(); ... SLIST_REMOVE(&head, np, entry, entries); free(np); } while (!SLIST_EMPTY(&head)) { /* List Deletion. */ n1 = SLIST_FIRST(&head); SLIST_REMOVE_HEAD(&head, entries); free(n1); } .Ed .Sh SINGLY-LINKED TAIL QUEUES A singly-linked tail queue is headed by a structure defined by the .Nm STAILQ_HEAD macro. This structure contains a pair of pointers, one to the first element in the tail queue and the other to the last element in the tail queue. The elements are singly linked for minimum space and pointer manipulation overhead at the expense of O(n) removal for arbitrary elements. New elements can be added to the tail queue after an existing element, at the head of the tail queue, or at the end of the tail queue. A .Fa STAILQ_HEAD structure is declared as follows: .Bd -literal -offset indent STAILQ_HEAD(HEADNAME, TYPE) head; .Ed .Pp where .Li HEADNAME is the name of the structure to be defined, and .Li TYPE is the type of the elements to be linked into the tail queue. A pointer to the head of the tail queue can later be declared as: .Bd -literal -offset indent struct HEADNAME *headp; .Ed .Pp (The names .Li head and .Li headp are user selectable.) .Pp The macro .Nm STAILQ_HEAD_INITIALIZER evaluates to an initializer for the tail queue .Fa head . .Pp The macro .Nm STAILQ_CONCAT concatenates the tail queue headed by .Fa head2 onto the end of the one headed by .Fa head1 removing all entries from the former. .Pp The macro .Nm STAILQ_EMPTY evaluates to true if there are no items on the tail queue. .Pp The macro .Nm STAILQ_ENTRY declares a structure that connects the elements in the tail queue. .Pp The macro .Nm STAILQ_FIRST returns the first item on the tail queue or NULL if the tail queue is empty. .Pp The macro .Nm STAILQ_FOREACH traverses the tail queue referenced by .Fa head in the forward direction, assigning each element in turn to .Fa var . .Pp The macro .Nm STAILQ_FOREACH_SAFE traverses the tail queue referenced by .Fa head in the forward direction, assigning each element in turn to .Fa var . However, unlike .Fn STAILQ_FOREACH here it is permitted to both remove .Fa var as well as free it from within the loop safely without interfering with the traversal. .Pp The macro .Nm STAILQ_INIT initializes the tail queue referenced by .Fa head . .Pp The macro .Nm STAILQ_INSERT_HEAD inserts the new element .Fa elm at the head of the tail queue. .Pp The macro .Nm STAILQ_INSERT_TAIL inserts the new element .Fa elm at the end of the tail queue. .Pp The macro .Nm STAILQ_INSERT_AFTER inserts the new element .Fa elm after the element .Fa listelm . .Pp The macro .Nm STAILQ_LAST returns the last item on the tail queue. If the tail queue is empty the return value is .Dv NULL . .Pp The macro .Nm STAILQ_NEXT returns the next item on the tail queue, or NULL this item is the last. .Pp The macro .Nm STAILQ_REMOVE_HEAD removes the element at the head of the tail queue. For optimum efficiency, elements being removed from the head of the tail queue should use this macro explicitly rather than the generic .Fa STAILQ_REMOVE macro. .Pp The macro .Nm STAILQ_REMOVE removes the element .Fa elm from the tail queue. .Sh SINGLY-LINKED TAIL QUEUE EXAMPLE .Bd -literal STAILQ_HEAD(stailhead, entry) head = STAILQ_HEAD_INITIALIZER(head); struct stailhead *headp; /* Singly-linked tail queue head. */ struct entry { ... STAILQ_ENTRY(entry) entries; /* Tail queue. */ ... } *n1, *n2, *n3, *np; STAILQ_INIT(&head); /* Initialize the queue. */ n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ STAILQ_INSERT_HEAD(&head, n1, entries); n1 = malloc(sizeof(struct entry)); /* Insert at the tail. */ STAILQ_INSERT_TAIL(&head, n1, entries); n2 = malloc(sizeof(struct entry)); /* Insert after. */ STAILQ_INSERT_AFTER(&head, n1, n2, entries); /* Deletion. */ STAILQ_REMOVE(&head, n2, entry, entries); free(n2); /* Deletion from the head. */ n3 = STAILQ_FIRST(&head); STAILQ_REMOVE_HEAD(&head, entries); free(n3); /* Forward traversal. */ STAILQ_FOREACH(np, &head, entries) np-> ... /* Safe forward traversal. */ STAILQ_FOREACH_SAFE(np, &head, entries, np_temp) { np->do_stuff(); ... STAILQ_REMOVE(&head, np, entry, entries); free(np); } /* TailQ Deletion. */ while (!STAILQ_EMPTY(&head)) { n1 = STAILQ_FIRST(&head); STAILQ_REMOVE_HEAD(&head, entries); free(n1); } /* Faster TailQ Deletion. */ n1 = STAILQ_FIRST(&head); while (n1 != NULL) { n2 = STAILQ_NEXT(n1, entries); free(n1); n1 = n2; } STAILQ_INIT(&head); .Ed .Sh LISTS A list is headed by a structure defined by the .Nm LIST_HEAD macro. This structure contains a single pointer to the first element on the list. The elements are doubly linked so that an arbitrary element can be removed without traversing the list. New elements can be added to the list after an existing element, before an existing element, or at the head of the list. A .Fa LIST_HEAD structure is declared as follows: .Bd -literal -offset indent LIST_HEAD(HEADNAME, TYPE) head; .Ed .Pp where .Fa HEADNAME is the name of the structure to be defined, and .Fa TYPE is the type of the elements to be linked into the list. A pointer to the head of the list can later be declared as: .Bd -literal -offset indent struct HEADNAME *headp; .Ed .Pp (The names .Li head and .Li headp are user selectable.) .Pp The macro .Nm LIST_HEAD_INITIALIZER evaluates to an initializer for the list .Fa head . .Pp The macro .Nm LIST_EMPTY evaluates to true if there are no elements in the list. .Pp The macro .Nm LIST_ENTRY declares a structure that connects the elements in the list. .Pp The macro .Nm LIST_FIRST returns the first element in the list or NULL if the list is empty. .Pp The macro .Nm LIST_FOREACH traverses the list referenced by .Fa head in the forward direction, assigning each element in turn to .Fa var . .Pp The macro .Nm LIST_FOREACH_SAFE traverses the list referenced by .Fa head in the forward direction, assigning each element in turn to .Fa var . However, unlike .Fn LIST_FOREACH here it is permitted to both remove .Fa var as well as free it from within the loop safely without interfering with the traversal. .Pp The macro .Nm LIST_INIT initializes the list referenced by .Fa head . .Pp The macro .Nm LIST_INSERT_HEAD inserts the new element .Fa elm at the head of the list. .Pp The macro .Nm LIST_INSERT_AFTER inserts the new element .Fa elm after the element .Fa listelm . .Pp The macro .Nm LIST_INSERT_BEFORE inserts the new element .Fa elm before the element .Fa listelm . .Pp The macro .Nm LIST_NEXT returns the next element in the list, or NULL if this is the last. .Pp The macro .Nm LIST_REMOVE removes the element .Fa elm from the list. .Sh LIST EXAMPLE .Bd -literal LIST_HEAD(listhead, entry) head = LIST_HEAD_INITIALIZER(head); struct listhead *headp; /* List head. */ struct entry { ... LIST_ENTRY(entry) entries; /* List. */ ... } *n1, *n2, *n3, *np, *np_temp; LIST_INIT(&head); /* Initialize the list. */ n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ LIST_INSERT_HEAD(&head, n1, entries); n2 = malloc(sizeof(struct entry)); /* Insert after. */ LIST_INSERT_AFTER(n1, n2, entries); n3 = malloc(sizeof(struct entry)); /* Insert before. */ LIST_INSERT_BEFORE(n2, n3, entries); LIST_REMOVE(n2, entries); /* Deletion. */ free(n2); /* Forward traversal. */ LIST_FOREACH(np, &head, entries) np-> ... /* Safe forward traversal. */ LIST_FOREACH_SAFE(np, &head, entries, np_temp) { np->do_stuff(); ... LIST_REMOVE(np, entries); free(np); } while (!LIST_EMPTY(&head)) { /* List Deletion. */ n1 = LIST_FIRST(&head); LIST_REMOVE(n1, entries); free(n1); } n1 = LIST_FIRST(&head); /* Faster List Deletion. */ while (n1 != NULL) { n2 = LIST_NEXT(n1, entries); free(n1); n1 = n2; } LIST_INIT(&head); .Ed .Sh TAIL QUEUES A tail queue is headed by a structure defined by the .Nm TAILQ_HEAD macro. This structure contains a pair of pointers, one to the first element in the tail queue and the other to the last element in the tail queue. The elements are doubly linked so that an arbitrary element can be removed without traversing the tail queue. New elements can be added to the tail queue after an existing element, before an existing element, at the head of the tail queue, or at the end of the tail queue. A .Fa TAILQ_HEAD structure is declared as follows: .Bd -literal -offset indent TAILQ_HEAD(HEADNAME, TYPE) head; .Ed .Pp where .Li HEADNAME is the name of the structure to be defined, and .Li TYPE is the type of the elements to be linked into the tail queue. A pointer to the head of the tail queue can later be declared as: .Bd -literal -offset indent struct HEADNAME *headp; .Ed .Pp (The names .Li head and .Li headp are user selectable.) .Pp The macro .Nm TAILQ_HEAD_INITIALIZER evaluates to an initializer for the tail queue .Fa head . .Pp The macro .Nm TAILQ_CONCAT concatenates the tail queue headed by .Fa head2 onto the end of the one headed by .Fa head1 removing all entries from the former. .Pp The macro .Nm TAILQ_EMPTY evaluates to true if there are no items on the tail queue. .Pp The macro .Nm TAILQ_ENTRY declares a structure that connects the elements in the tail queue. .Pp The macro .Nm TAILQ_FIRST returns the first item on the tail queue or NULL if the tail queue is empty. .Pp The macro .Nm TAILQ_FOREACH traverses the tail queue referenced by .Fa head in the forward direction, assigning each element in turn to .Fa var . .Fa var is set to .Dv NULL if the loop completes normally, or if there were no elements. .Pp The macro .Nm TAILQ_FOREACH_REVERSE traverses the tail queue referenced by .Fa head in the reverse direction, assigning each element in turn to .Fa var . .Pp The macros .Nm TAILQ_FOREACH_SAFE and .Nm TAILQ_FOREACH_REVERSE_SAFE traverse the list referenced by .Fa head in the forward or reverse direction respectively, assigning each element in turn to .Fa var . However, unlike their unsafe counterparts, .Nm TAILQ_FOREACH and .Nm TAILQ_FOREACH_REVERSE permit to both remove .Fa var as well as free it from within the loop safely without interfering with the traversal. .Pp The macro .Nm TAILQ_INIT initializes the tail queue referenced by .Fa head . .Pp The macro .Nm TAILQ_INSERT_HEAD inserts the new element .Fa elm at the head of the tail queue. .Pp The macro .Nm TAILQ_INSERT_TAIL inserts the new element .Fa elm at the end of the tail queue. .Pp The macro .Nm TAILQ_INSERT_AFTER inserts the new element .Fa elm after the element .Fa listelm . .Pp The macro .Nm TAILQ_INSERT_BEFORE inserts the new element .Fa elm before the element .Fa listelm . .Pp The macro .Nm TAILQ_LAST returns the last item on the tail queue. If the tail queue is empty the return value is .Dv NULL . .Pp The macro .Nm TAILQ_NEXT returns the next item on the tail queue, or NULL if this item is the last. .Pp The macro .Nm TAILQ_PREV returns the previous item on the tail queue, or NULL if this item is the first. .Pp The macro .Nm TAILQ_REMOVE removes the element .Fa elm from the tail queue. .Sh TAIL QUEUE EXAMPLE .Bd -literal TAILQ_HEAD(tailhead, entry) head = TAILQ_HEAD_INITIALIZER(head); struct tailhead *headp; /* Tail queue head. */ struct entry { ... TAILQ_ENTRY(entry) entries; /* Tail queue. */ ... } *n1, *n2, *n3, *np; TAILQ_INIT(&head); /* Initialize the queue. */ n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ TAILQ_INSERT_HEAD(&head, n1, entries); n1 = malloc(sizeof(struct entry)); /* Insert at the tail. */ TAILQ_INSERT_TAIL(&head, n1, entries); n2 = malloc(sizeof(struct entry)); /* Insert after. */ TAILQ_INSERT_AFTER(&head, n1, n2, entries); n3 = malloc(sizeof(struct entry)); /* Insert before. */ TAILQ_INSERT_BEFORE(n2, n3, entries); TAILQ_REMOVE(&head, n2, entries); /* Deletion. */ free(n2); /* Forward traversal. */ TAILQ_FOREACH(np, &head, entries) np-> ... /* Safe forward traversal. */ TAILQ_FOREACH_SAFE(np, &head, entries, np_temp) { np->do_stuff(); ... TAILQ_REMOVE(&head, np, entries); free(np); } /* Reverse traversal. */ TAILQ_FOREACH_REVERSE(np, &head, tailhead, entries) np-> ... /* TailQ Deletion. */ while (!TAILQ_EMPTY(&head)) { n1 = TAILQ_FIRST(&head); TAILQ_REMOVE(&head, n1, entries); free(n1); } /* Faster TailQ Deletion. */ n1 = TAILQ_FIRST(&head); while (n1 != NULL) { n2 = TAILQ_NEXT(n1, entries); free(n1); n1 = n2; } TAILQ_INIT(&head); .Ed .Sh HISTORY The .Nm queue functions first appeared in .Bx 4.4 . Index: head/share/man/man4/acpi.4 =================================================================== --- head/share/man/man4/acpi.4 (revision 162403) +++ head/share/man/man4/acpi.4 (revision 162404) @@ -1,602 +1,602 @@ .\" .\" 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 July 29, 2006 .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" .Cd "options DDB" .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 SYSCTL VARIABLES The .Nm driver is intended to provide power management without user intervention. If the default settings are not optimal, the following sysctls can be used to modify or monitor .Nm behavior. .Bl -tag -width indent .It Va hw.acpi.acline AC line state (1 means online, 0 means on battery power). .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 .Li 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., .Li C2 ) . .Li C1 is equivalent to the ia32 .Li HLT instruction, .Li C2 provides a deeper sleep with the same semantics, and .Li C3 provides the deepest sleep but additionally requires bus mastering to be disabled. States greater than .Li C3 provide even more power savings with the same semantics as the .Li C3 state. Deeper sleeps provide more power savings but increased transition latency when an interrupt occurs. .It Va hw.acpi.disable_on_reboot Disable ACPI during the reboot process. Most systems reboot fine with ACPI still enabled, but some require exiting to legacy mode first. Default is 0, leave ACPI enabled. .It Va hw.acpi.handle_reboot Use the ACPI Reset Register capability to reboot the system. Default is 0, use legacy reboot support. Some newer systems require use of this register, while some only work with legacy rebooting support. .It Va hw.acpi.lid_switch_state Suspend state .Pq Li S1 Ns \[en] Ns Li S5 to enter when the lid switch (i.e., a notebook screen) is closed. Default is .Dq Li NONE (do nothing). .It Va hw.acpi.power_button_state Suspend state .Pq Li S1 Ns \[en] Ns Li S5 to enter when the power button is pressed. Default is .Li S5 (power-off nicely). .It Va hw.acpi.reset_video Reset the video adapter from real mode during the resume path. Some systems need this help, others have display problems if it is enabled. Default is 0 (disabled). .It Va hw.acpi.s4bios Indicate whether the system supports .Li S4BIOS . This means that the BIOS can handle all the functions of suspending the system to disk. Otherwise, the OS is responsible for suspending to disk .Pq Li S4OS . Most current systems do not support .Li S4BIOS . .It Va hw.acpi.sleep_button_state Suspend state .Pq Li S1 Ns \[en] Ns Li S5 to enter when the sleep button is pressed. This is usually a special function button on the keyboard. Default is .Li S3 (suspend-to-RAM). .It Va hw.acpi.sleep_delay Wait this number of seconds between preparing the system to suspend and actually entering the suspend state. Default is 1 second. .It Va hw.acpi.supported_sleep_state Suspend states .Pq Li S1 Ns \[en] Ns Li S5 supported by the BIOS. .Bl -tag -width indent .It Li S1 Quick suspend to RAM. The CPU enters a lower power state, but most peripherals are left running. .It Li S2 Lower power state than .Li S1 , but with the same basic characteristics. Not supported by many systems. .It Li S3 Suspend to RAM. Most devices are powered off, and the system stops running except for memory refresh. .It Li S4 Suspend to disk. All devices are powered off, and the system stops running. When resuming, the system starts as if from a cold power on. Not yet supported by .Fx unless .Li S4BIOS is available. .It Li S5 System shuts down cleanly and powers off. .El .It Va hw.acpi.verbose Enable verbose printing from the various ACPI subsystems. .El .Sh LOADER TUNABLES Tunables can be set at the .Xr loader 8 prompt before booting the kernel or stored in .Pa /boot/loader.conf . Many of these tunables also have a matching .Xr sysctl 8 entry for access after boot. .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 debug.acpi.resume_beep Beep the PC speaker on resume. This can help diagnose suspend/resume problems. Default is 0 (disabled). .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.reset_video Enables calling the VESA reset BIOS vector on the resume path. This can fix some graphics cards that have problems such as LCD white-out after resume. Default is 0 (disabled). .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. .It Va hw.pci.link.%s.%d.irq Override the interrupt to use for this link and index. This capability should be used carefully, and only if a device is not working with .Nm enabled. .Qq %s is the name of the link (e.g., LNKA). .Qq %d is the resource index when the link supports multiple IRQs. Most PCI links only have one IRQ resource, so the below form should be used. .It Va hw.pci.link.%s.irq Override the interrupt to use. This capability should be used carefully, and only if a device is not working with .Nm enabled. .Qq %s is the name of the link (e.g., LNKA). .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 .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 Many BIOS versions have serious bugs that may cause system instability, break suspend/resume, or prevent devices from operating properly due to IRQ routing problems. Upgrade your BIOS to the latest version available from the vendor before -deciding it's a problem with +deciding it is a problem with .Nm . .Pp The .Nm CPU idle power management drive conflicts with the local APIC (LAPIC) timer. Disable APIC mode with .Va hint.apic.0.disabled -or don't use the +or do not use the .Li C2 and .Li C3 states if APIC mode is enabled. Index: head/share/man/man4/adw.4 =================================================================== --- head/share/man/man4/adw.4 (revision 162403) +++ head/share/man/man4/adw.4 (revision 162404) @@ -1,103 +1,104 @@ .\" .\" Copyright (c) 1998, 2000 .\" Justin T. Gibbs. 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. 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 July 14, 2004 .Dt ADW 4 .Os .Sh NAME .Nm adw .Nd Advansys PCI 16bit SCSI Host adapter driver .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device pci" .Cd "device scbus" .Cd "device adw" +.Ed .Sh DESCRIPTION This driver provides access to the 16bit .Tn SCSI bus connected to the Advanced Systems Products, Inc. .Tn ASC3550 Ultra , and .Tn ASC38C0800 Ultra2 , SCSI Host Adapter chips. Both chips support, synchronous transfers (20MHz and 40MHz max respectively), 16bit transfers, tagged queueing, and up to 253 concurrent SCSI transactions. .Pp Per target configuration performed in the .Tn AdvanceWare menu, which is accessible at boot, is honored by this driver. This includes synchronous/asynchronous transfers, maximum synchronous negotiation rate, wide transfers, disconnection, tagged queueing, and the host adapter's SCSI ID. The global setting for the maximum number of tagged transactions allowed per target is not honored as the CAM SCSI system will automatically determine the maximum number of tags a device can receive as well as guarantee fair resource allocation among devices. .Sh HARDWARE The .Nm driver supports SCSI controllers including: .Pp .Bl -bullet -compact .It AdvanSys ABP940UW/ABP3940UW .It AdvanSys ABP950UW .It AdvanSys ABP970UW .It AdvanSys ABP3940U2W .It AdvanSys ABP3950U2W .El .Sh SEE ALSO .Xr adv 4 , .Xr cd 4 , .Xr da 4 , .Xr sa 4 , .Xr scsi 4 .Sh HISTORY The .Nm driver appeared in .Fx 3.0 . .Sh AUTHORS .An -nosplit The .Nm driver was ported by .An Justin T. Gibbs from the Linux driver written by .An Bob Frey of Advanced System Products, Inc. Many thanks to AdvanSys for providing the original driver under a suitable license for use in .Fx . Index: head/share/man/man4/ataraid.4 =================================================================== --- head/share/man/man4/ataraid.4 (revision 162403) +++ head/share/man/man4/ataraid.4 (revision 162404) @@ -1,148 +1,148 @@ .\" Copyright (c) 2005 Christian Brueffer .\" 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 17, 2006 .Dt ATARAID 4 .Os .Sh NAME .Nm ataraid .Nd "ATA software RAID support" .Sh SYNOPSIS .Cd "device ata" .Cd "device ataraid" .Sh DESCRIPTION The .Nm driver provides support for so-called software RAID (sometimes referred to as fake RAID or pseudo RAID). .Pp When a controller that supports software RAID is instructed to create a RAID array, its BIOS writes data structures in a specific metadata format to the disks. These data structures are picked up by the .Nm driver, so that .Fx can work with the array. The .Nm driver has to understand the specific metadata format of a controller BIOS in order to support its RAID capabilities. .Pp Read-only support for a metadata format means that .Fx can use the given RAID array for normal read/write operations. Creation and rebuild of such arrays has to be done from the controller BIOS. .Pp Read and write support for a metadata format means that .Fx can use the given RAID array for normal read/write operations. Additionally, the .Xr atacontrol 8 utility can be used to create, rebuild, update and fail such RAID arrays. .Pp The .Nm driver can read the following metadata formats: .Pp .Bl -bullet -compact .It Adaptec HostRAID .It Highpoint V2 RocketRAID .It Highpoint V3 RocketRAID .It Intel MatrixRAID .It Integrated Technology Express (ITE) .It JMicron .It LSI Logic V2 MegaRAID .It LSI Logic V3 MegaRAID .It NVIDIA MediaShield .It Promise FastTrak .It Silicon Image Medley .It Silicon Integrated Systems (SiS) .It VIA Tech V-RAID .It FreeBSD PseudoRAID .El .Pp The .Nm driver can write the following metadata formats: .Pp .Bl -bullet -compact .It Highpoint V2 RocketRAID .It Intel MatrixRAID .It JMicron .It Promise FastTrak .It Silicon Integrated Systems (SiS) .It VIA Tech V-RAID .It FreeBSD PseudoRAID .El .Pp It is also possible to use software RAID on controllers that do not have special software RAID capabilities. See .Xr atacontrol 8 for details. .Sh FILES .Bl -tag -width ".Pa /dev/ar*" -compact .It Pa /dev/ar* ATA RAID device nodes .El .Sh SEE ALSO .Xr ata 4 , .Xr atacontrol 8 .Sh CAVEATS RAID5 is not supported at this time. -Code exists, but it neither uses nor maintains parity information. +Code exists, but it neither uses nor maintains parity information. .Sh AUTHORS .An -nosplit The .Nm driver was written by .An S\(/oren Schmidt Aq sos@FreeBSD.org . This manual page was written by .An Christian Brueffer Aq brueffer@FreeBSD.org . Index: head/share/man/man4/atkbd.4 =================================================================== --- head/share/man/man4/atkbd.4 (revision 162403) +++ head/share/man/man4/atkbd.4 (revision 162404) @@ -1,223 +1,223 @@ .\" .\" Copyright (c) 1999 .\" Kazutaka YOKOTA .\" 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 as .\" the first lines of this file unmodified. .\" 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 May 21, 1999 .Dt ATKBD 4 .Os .Sh NAME .Nm atkbd .Nd the AT keyboard interface .Sh SYNOPSIS .Cd "options ATKBD_DFLT_KEYMAP" .Cd "makeoptions ATKBD_DFLT_KEYMAP=_keymap_name_" .Cd "options KBD_DISABLE_KEYMAP_LOAD" .Cd "device atkbd" .Pp In .Pa /boot/device.hints : .Cd hint.atkbd.0.at="atkbdc" .Cd hint.atkbd.0.irq="1" .Sh DESCRIPTION The .Nm driver, together with the .Nm atkbdc driver, provides access to the AT 84 keyboard or the AT enhanced keyboard which is connected to the AT keyboard controller. .Pp This driver is required for the console driver -.Xr syscons 4 +.Xr syscons 4 . .Pp There can be only one .Nm device defined in the kernel configuration file. This device also requires the .Nm atkbdc keyboard controller to be present. The .Em irq number must always be 1; there is no provision of changing the number. .Ss Function Keys The AT keyboard has a number of function keys. They are numbered as follows and can be associated with strings by the .Xr kbdcontrol 1 command. .Pp .Bl -tag -width "Function Key Number" -compact .It "Function Key number" Function Key .It "1, 2,...12" F1, F2,...\& F12 .It "13, 14,...24" Shift+F1, Shift+F2,...\& Shift+F12 .It "25, 26,...36" Ctl+F1, Ctl+F2,...\& Ctl+F12 .It "37, 38,...48" Shift+Ctl+F1, Shift+Ctl+F2,...\& Shift+Ctl+F12 .It 49 Home and Numpad 7 (without NumLock) .It 50 Up Arrow and Numpad 8 (without NumLock) .It 51 Page Up and Numpad 9 (without NumLock) .It 52 Numpad - .It 53 Left Arrow and Numpad 4 (without NumLock) .It 54 Numpad 5 (without NumLock) .It 55 Right Arrow and Numpad 6 (without NumLock) .It 56 Numpad + .It 57 End and Numpad 1 (without NumLock) .It 58 Down Arrow and Numpad 2 (without NumLock) .It 59 Page Down and Numpad 3 (without NumLock) .It 60 Ins and Numpad 0 (without NumLock) .It 61 Del .It 62 Left GUI Key .It 63 Right GUI Key .It 64 Menu .El .Pp See the man page for the .Xr kbdcontrol 1 command for how to assign a string to the function key. .Sh DRIVER CONFIGURATION .Ss Kernel Configuration Options The following kernel configuration options control the .Nm driver. .Bl -tag -width ATKBD_DFLT .It Em ATKBD_DFLT_KEYMAP This option sets the default, built-in keymap of the .Nm driver to the named keymap. See .Sx EXAMPLES below. .It Em KBD_DISABLE_KEYMAP_LOAD The keymap can be modified by the .Xr kbdcontrol 1 command. This option will disable this feature and prevent the user from changing key assignment. .El .Pp .Ss Driver Flags The .Nm driver accepts the following driver flags. They can be set either in .Pa /boot/device.hints , or else from within the boot loader (see .Xr loader 8 ) . .Bl -tag -width FAIL .It bit 0 (FAIL_IF_NO_KBD) By default the .Nm driver will install even if a keyboard is not actually connected to the system. This option prevents the driver from being installed in this situation. .It bit 1 (NO_RESET) When this option is given, the .Nm driver will not reset the keyboard when initializing it. It may be useful for laptop computers whose function keys have special functions and these functions are forgotten when the keyboard is reset. .It bit 2 (ALT_SCANCODESET) Certain keyboards, such as those on some ThinkPad models, behave like the old XT keyboard and require this option. .It bit 3 (NO_PROBE_TEST) When this option is given, the .Nm driver will not test the keyboard port during the probe routine. Some machines hang during boot when this test is performed. .El .\".Sh FILES .Sh EXAMPLES The .Nm driver requires the keyboard controller .Nm atkbdc . Thus, the kernel configuration file should contain the following lines. .Pp .Dl "device atkbdc" .Dl "device atkbd" .Pp The following example shows how to set the default, built-in keymap to .Pa jp.106.kbd . .Pp .Dl "device atkbdc" .Dl "options ATKBD_DFLT_KEYMAP" .Dl "makeoptions ATKBD_DFLT_KEYMAP=jp.106" .Dl "device atkbd" .Pp In both cases, you also need to have following lines in .Pa /boot/device.hints . .Pp .Dl hint.atkbdc.0.at="isa" .Dl hint.atkbdc.0.port="0x060" .Dl hint.atkbd.0.at="atkbdc" .Dl hint.atkbd.0.irq="1" .\".Sh DIAGNOSTICS .\".Sh CAVEATS .\".Sh BUGS .Sh SEE ALSO .Xr kbdcontrol 1 , .Xr atkbdc 4 , .Xr psm 4 , .Xr syscons 4 , .Xr loader 8 .Sh HISTORY The .Nm driver first appeared in .Fx 3.1 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An S\(/oren Schmidt Aq sos@FreeBSD.org and .An Kazutaka Yokota Aq yokota@FreeBSD.org . This manual page was written by .An Kazutaka Yokota . Index: head/share/man/man4/cpufreq.4 =================================================================== --- head/share/man/man4/cpufreq.4 (revision 162403) +++ head/share/man/man4/cpufreq.4 (revision 162404) @@ -1,305 +1,305 @@ .\" 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 March 03, 2006 +.Dd March 3, 2006 .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 /etc/rc.d/power_profile that it should switch settings when the AC line state changes via .Xr rc.conf 5 . .Sh SYSCTL VARIABLES 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 . .Pp The frequency cannot be changed if TSC is in use as the timecounter. This is because the timecounter system needs to use a source that has a constant rate. The timecounter source can be changed with the .Pa kern.timecounter.hardware sysctl. Available modes are in .Pa kern.timecounter.choice sysctl entry. .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!\& and Cool'n'Quiet 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/da.4 =================================================================== --- head/share/man/man4/da.4 (revision 162403) +++ head/share/man/man4/da.4 (revision 162404) @@ -1,216 +1,216 @@ .\" Copyright (c) 1996 .\" Julian Elischer . 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 2, 2003 .Dt DA 4 .Os .Sh NAME .Nm da .Nd SCSI Direct Access device driver .Sh SYNOPSIS .Cd device da .Sh DESCRIPTION The .Nm driver provides support for all .Tn SCSI devices of the direct access class that are attached to the system through a supported .Tn SCSI Host Adapter. The direct access class includes disk, magneto-optical, and solid-state devices. .Pp A .Tn SCSI Host adapter must also be separately configured into the system before a .Tn SCSI direct access device can be configured. .Sh CACHE EFFECTS Many direct access devices are equipped with read and/or write caches. Parameters affecting the device's cache are stored in mode page 8, the caching control page. Mode pages can be examined and modified via the .Xr camcontrol 8 utility. .Pp The read cache is used to store data from device-initiated read ahead operations as well as frequently used data. The read cache is transparent to the user and can be enabled without any adverse effect. Most devices with a read cache come from the factory with it enabled. The read cache can be disabled by setting the .Tn RCD (Read Cache Disable) bit in the caching control mode page. .Pp The write cache can greatly decrease the latency of write operations and allows the device to reorganize writes to increase efficiency and performance. This performance gain comes at a price. Should the device lose power while its cache contains uncommitted write operations, these writes will be lost. The effect of a loss of write transactions on a file system is non-deterministic and can cause corruption. Most devices age write transactions to limit vulnerability to a few transactions recently reported as complete, but it is none-the-less recommended that systems with write cache enabled devices reside on an Uninterruptible Power Supply (UPS). The .Nm device driver ensures that the cache and media are synchronized upon final close of the device or an unexpected shutdown (panic) event. This ensures that it is safe to disconnect power once the operating system has reported that it has halted. The write cache can be enabled by setting the .Tn WCE (Write Cache Enable) bit in the caching control mode page. .Sh TAGGED QUEUING The .Nm device driver will take full advantage of the SCSI feature known as tagged queueing. Tagged queueing allows the device to process multiple transactions concurrently, often re-ordering them to reduce the number and length of seeks. To ensure that transactions to distant portions of the media, which may be deferred indefinitely by servicing requests nearer the current head position, are completed in a timely fashion, an ordered tagged transaction is sent every 15 seconds during continuous device operation. .Sh BAD BLOCK RECOVERY Direct Access devices have the capability of mapping out portions of defective media. Media recovery parameters are located in mode page 1, the Read-Write Error Recovery mode page. The most important media remapping features are 'Auto Write Reallocation' and 'Auto Read Reallocation' which can be enabled via the AWRE and ARRE bits, respectively, of the Read-Write Error Recovery page. Many devices do not ship from the factory with these feature enabled. Mode pages can be examined and modified via the .Xr camcontrol 8 utility. .Sh KERNEL CONFIGURATION It is only necessary to explicitly configure one .Nm device; data structures are dynamically allocated as disks are found on the .Tn SCSI bus. .Sh SYSCTL VARIABLES The following variables are available as both .Xr sysctl 8 variables and .Xr loader 8 tunables: .Bl -tag -width 12 .It kern.cam.da.retry_count .Pp This variable determines how many times the .Nm driver will retry a READ or WRITE command. This does not affect the number of retries used during probe time or for the .Nm driver dump routine. This value currently defaults to 4. .It kern.cam.da.default_timeout .Pp This variable determines how long the .Nm driver will wait before timing out an outstanding command. The units for this value are seconds, and the default is currently 60 seconds. .It kern.cam.da.%d.minimum_cmd_size .Pp This variable determines what the minimum READ/WRITE CDB size is for a given .Nm unit. (The %d above denotes the unit number of the .Nm driver instance, e.g.\& 1, 2, 4, 8, etc.) Valid minimum command size values are 6, 10, 12 and 16 bytes. The default is 6 bytes. .Pp The .Nm driver issues a CAM Path Inquiry CCB at probe time to determine whether the protocol the device in question speaks (e.g.\& ATAPI) typically does not allow 6 byte commands. If it does not, the .Nm driver will default to using at least 10 byte CDBs. If a 6 byte READ or WRITE fails with an ILLEGAL REQUEST error, the .Nm driver will then increase the default CDB size for the device to 10 bytes and retry the command. CDB size is always chosen as the smallest READ/WRITE CDB that will satisfy the specified minimum command size, and the LBA and length of the READ or WRITE in question. (e.g., a write to an LBA larger than 2^32 will require a 16 byte CDB.) .El .Sh NOTES If a device becomes invalidated (media is removed, device becomes unresponsive) the disklabel and information held within the kernel about the device will be invalidated. To avoid corruption of a newly inserted piece of media or a replacement device, all accesses to the device will be discarded until the last file descriptor referencing the old device is closed. During this period, all new open attempts will be rejected. .Sh FILES -.Bl -tag -width /dev/da* -compact +.Bl -tag -width ".Pa /dev/da*" -compact .It Pa /dev/da* SCSI disk device nodes .El .Sh DIAGNOSTICS None. .Sh SEE ALSO .Xr ad 4 , .Xr geom 4 , .Xr bsdlabel 8 , .Xr fdisk 8 .Sh HISTORY The .Nm driver was written for the .Tn CAM .Tn SCSI subsystem by .An Justin T. Gibbs . Many ideas were gleaned from the .Nm sd device driver written and ported from .Tn Mach 2.5 by .An Julian Elischer . Index: head/share/man/man4/ddb.4 =================================================================== --- head/share/man/man4/ddb.4 (revision 162403) +++ head/share/man/man4/ddb.4 (revision 162404) @@ -1,631 +1,625 @@ .\" .\" Mach Operating System .\" Copyright (c) 1991,1990 Carnegie Mellon University .\" All Rights Reserved. .\" .\" Permission to use, copy, modify and distribute this software and its .\" documentation is hereby granted, provided that both the copyright .\" notice and this permission notice appear in all copies of the .\" software, derivative works or modified versions, and any portions .\" thereof, and that both notices appear in supporting documentation. .\" .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. .\" .\" Carnegie Mellon requests users of this software to return to .\" .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU .\" School of Computer Science .\" Carnegie Mellon University .\" Pittsburgh PA 15213-3890 .\" .\" any improvements or extensions that they make and grant Carnegie Mellon .\" the rights to redistribute these changes. .\" .\" changed a \# to #, since groff choked on it. .\" .\" HISTORY .\" ddb.4,v .\" Revision 1.1 1993/07/15 18:41:02 brezak .\" Man page for DDB .\" .\" Revision 2.6 92/04/08 08:52:57 rpd .\" Changes from OSF. .\" [92/01/17 14:19:22 jsb] .\" Changes for OSF debugger modifications. .\" [91/12/12 tak] .\" .\" Revision 2.5 91/06/25 13:50:22 rpd .\" Added some watchpoint explanation. .\" [91/06/25 rpd] .\" .\" Revision 2.4 91/06/17 15:47:31 jsb .\" Added documentation for continue/c, match, search, and watchpoints. .\" I've not actually explained what a watchpoint is; maybe Rich can .\" do that (hint, hint). .\" [91/06/17 10:58:08 jsb] .\" .\" Revision 2.3 91/05/14 17:04:23 mrt .\" Correcting copyright .\" .\" Revision 2.2 91/02/14 14:10:06 mrt .\" Changed to new Mach copyright .\" [91/02/12 18:10:12 mrt] .\" .\" Revision 2.2 90/08/30 14:23:15 dbg .\" Created. .\" [90/08/30 dbg] .\" .\" $FreeBSD$ .Dd September 15, 2006 .Dt DDB 4 .Os .Sh NAME .Nm ddb .Nd interactive kernel debugger .Sh SYNOPSIS .Cd options KDB .Cd options DDB .Pp To prevent activation of the debugger on kernel .Xr panic 9 : .Cd options KDB_UNATTENDED .Sh DESCRIPTION The .Nm kernel debugger has most of the features of the old kdb, but with a more rational syntax inspired by .Xr gdb 1 . If linked into the running kernel, it can be invoked locally with the .Ql debug .Xr keymap 5 action. The debugger is also invoked on kernel .Xr panic 9 if the .Va debug.debugger_on_panic .Xr sysctl 8 MIB variable is set non-zero, which is the default unless the .Dv KDB_UNATTENDED option is specified. .Pp The current location is called `dot'. The `dot' is displayed with a hexadecimal format at a prompt. Examine and write commands update `dot' to the address of the last line examined or the last location modified, and set `next' to the address of the next location to be examined or changed. Other commands do not change `dot', and set `next' to be the same as `dot'. .Pp The general command syntax is: .Cm command Ns Op Li \&/ Ns Ar modifier .Ar address Ns Op Li , Ns Ar count .Pp A blank line repeats the previous command from the address `next' with count 1 and no modifiers. Specifying .Ar address sets `dot' to the address. Omitting .Ar address uses `dot'. A missing .Ar count is taken to be 1 for printing commands or infinity for stack traces. .Pp The .Nm debugger has a feature like the .Xr more 1 command for the output. If an output line exceeds the number set in the .Li \&$lines variable, it displays .Dq Em --db_more-- and waits for a response. The valid responses for it are: .Pp .Bl -tag -compact -width ".Li SPC" .It Li SPC one more page .It Li RET one more line .It Li q abort the current command, and return to the command input mode .El .Pp Finally, .Nm provides a small (currently 10 items) command history, and offers simple emacs-style command line editing capabilities. In addition to the emacs control keys, the usual ANSI arrow keys might be used to browse through the history buffer, and move the cursor within the current line. .Sh COMMANDS .Bl -ohang .It Cm examine .It Cm x Display the addressed locations according to the formats in the modifier. Multiple modifier formats display multiple locations. If no format is specified, the last formats specified for this command is used. .Pp The format characters are: .Bl -tag -compact -width indent .It Li b look at by bytes (8 bits) .It Li h look at by half words (16 bits) .It Li l look at by long words (32 bits) .It Li a print the location being displayed .It Li A print the location with a line number if possible .It Li x display in unsigned hex .It Li z display in signed hex .It Li o display in unsigned octal .It Li d display in signed decimal .It Li u display in unsigned decimal .It Li r display in current radix, signed .It Li c display low 8 bits as a character. Non-printing characters are displayed as an octal escape code (e.g., `\e000'). .It Li s display the null-terminated string at the location. Non-printing characters are displayed as octal escapes. .It Li m display in unsigned hex with character dump at the end of each line. The location is also displayed in hex at the beginning of each line. .It Li i display as an instruction .It Li I display as an instruction with possible alternate formats depending on the machine: .Bl -tag -width ".Tn powerpc" -compact .It Tn alpha Show the registers of the instruction. .It Tn amd64 No alternate format. .It Tn i386 No alternate format. .It Tn ia64 No alternate format. .It Tn powerpc No alternate format. .It Tn sparc64 No alternate format. .El .El .It Cm xf Examine forward: Execute an examine command with the last specified parameters to it except that the next address displayed by it is used as the start address. .It Cm xb Examine backward: Execute an examine command with the last specified parameters to it except that the last start address subtracted by the size displayed by it is used as the start address. .It Cm print Ns Op Cm /acdoruxz Print .Ar addr Ns s according to the modifier character (as described above for .Li examine ) . Valid formats are: .Li a , .Li x , .Li z , .Li o , .Li d , .Li u , .Li r , and .Li c . If no modifier is specified, the last one specified to it is used. .Ar addr can be a string, in which case it is printed as it is. For example: .Bd -literal -offset indent print/x \&"eax = \&" $eax \&"\enecx = \&" $ecx \&"\en\&" .Ed .Pp will print like: .Bd -literal -offset indent eax = xxxxxx ecx = yyyyyy .Ed .It Xo .Cm write Ns Op Cm /bhl .Ar addr Ar expr1 Op Ar "expr2 ..." .Xc Write the expressions specified after .Ar addr on the command line at succeeding locations starting with .Ar addr The write unit size can be specified in the modifier with a letter .Li b (byte), .Li h (half word) or .Li l (long word) respectively. If omitted, long word is assumed. .Pp .Sy Warning : since there is no delimiter between expressions, strange things may happen. It is best to enclose each expression in parentheses. .It Xo .Cm set .Li \&$ Ns Ar variable .Op Li = .Ar expr .Xc Set the named variable or register with the value of .Ar expr . Valid variable names are described below. .It Cm break Ns Op Cm /u Set a break point at .Ar addr . If .Ar count is supplied, continues .Ar count - 1 times before stopping at the break point. If the break point is set, a break point number is printed with .Sq Li \&# . This number can be used in deleting the break point or adding conditions to it. .Pp If the .Li u modifier is specified, this command sets a break point in user space address. Without the .Li u option, the address is considered in the kernel space, and wrong space address is rejected with an error message. This modifier can be used only if it is supported by machine dependent routines. .Pp .Sy Warning : If a user text is shadowed by a normal user space debugger, user space break points may not work correctly. Setting a break point at the low-level code paths may also cause strange behavior. .It Cm delete Ar addr .It Cm delete Li \&# Ns Ar number Delete the break point. The target break point can be specified by a break point number with .Li # , or by using the same .Ar addr specified in the original .Cm break command. .It Cm step Ns Op Cm /p Single step .Ar count times (the comma is a mandatory part of the syntax). If the .Li p modifier is specified, print each instruction at each step. Otherwise, only print the last instruction. .Pp .Sy Warning : depending on machine type, it may not be possible to single-step through some low-level code paths or user space code. On machines with software-emulated single-stepping (e.g., pmax), stepping through code executed by interrupt handlers will probably do the wrong thing. .It Cm continue Ns Op Cm /c Continue execution until a breakpoint or watchpoint. If the .Li c modifier is specified, count instructions while executing. Some machines (e.g., pmax) also count loads and stores. .Pp .Sy Warning : when counting, the debugger is really silently single-stepping. This means that single-stepping on low-level code may cause strange behavior. .It Cm until Ns Op Cm /p Stop at the next call or return instruction. If the .Li p modifier is specified, print the call nesting depth and the cumulative instruction count at each call or return. Otherwise, only print when the matching return is hit. .It Cm next Ns Op Cm /p .It Cm match Ns Op Cm /p Stop at the matching return instruction. If the .Li p modifier is specified, print the call nesting depth and the cumulative instruction count at each call or return. Otherwise, only print when the matching return is hit. .It Xo .Cm trace Ns Op Cm /u .Op Ar frame .Op , Ns Ar count .Xc Stack trace. The .Li u option traces user space; if omitted, .Cm trace only traces kernel space. .Ar count is the number of frames to be traced. If .Ar count is omitted, all frames are printed. .Pp .Sy Warning : User space stack trace is valid only if the machine dependent code supports it. .It Xo .Cm search Ns Op Cm /bhl .Ar addr .Ar value .Op Ar mask .Op , Ns Ar count .Xc Search memory for .Ar value . This command might fail in interesting ways if it does not find the searched-for value. This is because ddb does not always recover from touching bad memory. The optional .Ar count argument limits the search. .It Cm show all procs Ns Op Cm /m .It Cm ps Ns Op Cm /m Display all process information. The process information may not be shown if it is not supported in the machine, or the bottom of the stack of the target process is not in the main memory at that time. The .Li m modifier will alter the display to show VM map addresses for the process and not show other info. .It Cm show registers Ns Op Cm /u Display the register set. If the .Li u option is specified, it displays user registers instead of kernel or currently saved one. .Pp .Sy Warning : The support of the .Li u modifier depends on the machine. If not supported, incorrect information will be displayed. -.It Xo -.Cm show geom -.Op Ar addr -.Xc +.It Cm show geom Op Ar addr If the .Ar addr argument is not given, displays the entire GEOM topology. If the .Ar addr -is given, displays details about the given GEOM object (class, geom, provider +is given, displays details about the given GEOM object (class, geom, provider or consumer). .It Xo .Cm show map Ns Op Cm /f .Ar addr .Xc Prints the VM map at .Ar addr . If the .Li f modifier is specified the complete map is printed. .It Xo .Cm show object Ns Op Cm /f .Ar addr .Xc Prints the VM object at .Ar addr . If the .Li f option is specified the complete object is printed. -.It Xo -.Cm show vnode -.Ar addr -.Xc +.It Cm show vnode Ar addr Displays details about the given vnode. .It Cm "show watches" Displays all watchpoints. .It Cm reset Hard reset the system. .It Xo .Cm watch .Ar addr Ns Li \&, Ns Ar size .Xc Set a watchpoint for a region. Execution stops when an attempt to modify the region occurs. The .Ar size argument defaults to 4. If you specify a wrong space address, the request is rejected with an error message. .Pp .Sy Warning : Attempts to watch wired kernel memory may cause unrecoverable error in some systems such as i386. Watchpoints on user addresses work best. .It Xo .Cm hwatch .Ar addr Ns Li \&, Ns Ar size .Xc Set a hardware watchpoint for a region if supported by the architecture. Execution stops when an attempt to modify the region occurs. The .Ar size argument defaults to 4. .Pp .Sy Warning : The hardware debug facilities do not have a concept of separate address spaces like the watch command does. Use .Cm hwatch for setting watchpoints on kernel address locations only, and avoid its use on user mode address spaces. .It Xo .Cm dhwatch .Ar addr Ns Li \&, Ns Ar size .Xc Delete specified hardware watchpoint. .It Cm gdb Toggles between remote GDB and DDB mode. In remote GDB mode, another machine is required that runs .Xr gdb 1 using the remote debug feature, with a connection to the serial console port on the target machine. Currently only available on the .Em i386 architecture. .It Cm help Print a short summary of the available commands and command abbreviations. .El .Sh VARIABLES The debugger accesses registers and variables as .Li \&$ Ns Em name . Register names are as in the .Dq Cm show registers command. Some variables are suffixed with numbers, and may have some modifier following a colon immediately after the variable name. For example, register variables can have a .Li u modifier to indicate user register (e.g., .Li $eax:u ) . .Pp Built-in variables currently supported are: .Bl -tag -width ".Li tabstops" -compact .It Li radix Input and output radix .It Li maxoff Addresses are printed as 'symbol'+offset unless offset is greater than maxoff. .It Li maxwidth The width of the displayed line. .It Li lines The number of lines. It is used by .Dq more feature. .It Li tabstops Tab stop width. .It Li work Ns Ar xx Work variable. .Ar xx can be 0 to 31. .El .Sh EXPRESSIONS Almost all expression operators in C are supported except .Sq Li \&~ , .Sq Li \&^ , and unary .Sq Li \&& . Special rules in .Nm are: .Bl -tag -width ".Em Identifiers" .It Em Identifiers The name of a symbol is translated to the value of the symbol, which is the address of the corresponding object. .Sq Li \&. and .Sq Li \&: can be used in the identifier. If supported by an object format dependent routine, .Sm off .Oo Em filename : Oc Em func : lineno , .Sm on .Oo Em filename : Oc Ns Em variable , and .Oo Em filename : Oc Ns Em lineno can be accepted as a symbol. .It Em Numbers Radix is determined by the first two letters: .Li 0x : hex, .Li 0o : octal, .Li 0t : decimal; otherwise, follow current radix. .It Li \&. `dot' .It Li \&+ `next' .It Li \&.. address of the start of the last line examined. Unlike `dot' or `next', this is only changed by .Dq Li examine or .Dq Li write command. .It Li \&' last address explicitly specified. .It Li \&$ Ns Em variable Translated to the value of the specified variable. It may be followed by a .Li : and modifiers as described above. .It Em a Ns Li \&# Ns Em b a binary operator which rounds up the left hand side to the next multiple of right hand side. .It Li \&* Ns Em expr indirection. It may be followed by a .Sq Li : and modifiers as described above. .El .Sh HINTS On machines with an ISA expansion bus, a simple NMI generation card can be constructed by connecting a push button between the A01 and B01 (CHCHK# and GND) card fingers. Momentarily shorting these two fingers together may cause the bridge chipset to generate an NMI, which causes the kernel to pass control to .Nm . Some bridge chipsets do not generate a NMI on CHCHK#, so your mileage may vary. The NMI allows one to break into the debugger on a wedged machine to diagnose problems. Other bus' bridge chipsets may be able to generate NMI using bus specific methods. .Sh SEE ALSO .Xr gdb 1 .Sh HISTORY The .Nm debugger was developed for Mach, and ported to .Bx 386 0.1 . This manual page translated from .Fl man macros by Garrett Wollman. Index: head/share/man/man4/fast_ipsec.4 =================================================================== --- head/share/man/man4/fast_ipsec.4 (revision 162403) +++ head/share/man/man4/fast_ipsec.4 (revision 162404) @@ -1,134 +1,134 @@ .\" Copyright (c) 2003 .\" Sam Leffler . 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 Sam Leffler 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 Bill Paul OR THE VOICES IN HIS 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. .\" .\" $FreeBSD$ .\" .Dd August 24, 2006 .Dt FAST_IPSEC 4 .Os .Sh NAME .Nm "Fast IPsec" .Nd hardware-accelerated IP Security Protocols .Sh SYNOPSIS .Cd "options FAST_IPSEC" .Cd "options IPSEC_FILTERGIF" .Cd "device crypto" .Pp .Bl -item -compact .It .Va net.inet.esp.enable .It .Va net.inet.ah.enable .It .Va net.inet.ipcomp.enable .El .Sh DESCRIPTION .Tn IPsec is a set of protocols, .Tn ESP (for Encapsulating Security Payload) .Tn AH (for Authentication Header), and .Tn IPComp (for IP Payload Compression Protocol) that provide security services for IP datagrams. .Nm is an experimental implementation of these protocols that uses the .Xr crypto 4 subsystem to carry out cryptographic operations. This means, in particular, that cryptographic hardware devices are employed whenever possible to optimize the performance of these protocols. .Pp In general, the .Nm implementation is intended to be compatible with the .Tn KAME IPsec implementation. This documentation concentrates on differences from that software. The user should refer to .Xr ipsec 4 for basic information on setting up and using these protocols. Note that it is not currently possible to use .Nm in conjuction with the .Tn "KAME IPsec" implementation. .Pp System configuration requires the .Xr crypto 4 subsystem. When the .Nm protocols are configured for use, all protocols are included in the system. To selectively enable/disable protocols, use .Xr sysctl 8 . .Pp The packets can be passed to a virtual interface, .Dq enc0 , to perform packet filtering before outbound encryption and after decapsulation inbound. .Pp -To properly filter +To properly filter .Xr gif 4 tunnels with firewalls, add .Cd "options IPSEC_FILTERGIF" to the kernel configuration file. .Sh DIAGNOSTICS To be added. .Sh SEE ALSO .Xr crypto 4 , .Xr enc 4 , .Xr ipsec 4 , .Xr setkey 8 , .Xr sysctl 8 .Sh HISTORY The protocols draw heavily on the .Ox implementation of the .Tn IPsec protocols. The policy management code is derived from the .Tn KAME implementation found in their .Tn IPsec protocols. The .Nm protocols first appeared in .Fx 5.0 . .Sh BUGS There is presently no support for IPv6. .Pp The .Tn IPcomp protocol support does not work. .Pp Certain legacy authentication algorithms are not supported because of issues with the .Xr crypto 4 subsystem. .Pp This documentation is incomplete. Index: head/share/man/man4/hptmv.4 =================================================================== --- head/share/man/man4/hptmv.4 (revision 162403) +++ head/share/man/man4/hptmv.4 (revision 162404) @@ -1,101 +1,101 @@ .\" .\" Copyright (c) 2004 David E. O'Brien .\" 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 November 17, 2005 .Dt HPTMV 4 .Os .Sh NAME .Nm hptmv .Nd "HighPoint RocketRAID 182x device driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device hptmv" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent hptmv_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for HighPoint's RocketRAID 182x based RAID controller. .Pp These devices support ATA disk drives and provide RAID0 (striping), RAID1 (mirroring), and RAID5 functionality. .Sh HARDWARE The .Nm driver supports the following ATA RAID controllers: .Pp .Bl -bullet -compact .It HighPoint's RocketRAID 182x series .El .Sh NOTES The .Nm driver only works on the i386 and amd64 platforms as it requires a binary blob object from the manufacturer which they only supply for these platforms. The .Nm -driver -.Em does not +driver does +.Em not work on i386 with .Xr pae 4 enabled. .Sh SEE ALSO .Xr kld 4 , .Xr kldload 8 , .Xr loader 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 5.3 . .Sh AUTHORS .An -nosplit The .Nm device driver was written by .An HighPoint Technologies, Inc. , and ported to .Fx by .An Scott Long . This manual page was written by .An David E. O'Brien . .Sh BUGS The .Nm driver does not support manipulating the RAID from the OS, RAIDs need to be set up from the on-board BIOS. Index: head/share/man/man4/if_bridge.4 =================================================================== --- head/share/man/man4/if_bridge.4 (revision 162403) +++ head/share/man/man4/if_bridge.4 (revision 162404) @@ -1,287 +1,286 @@ .\" $NetBSD: bridge.4,v 1.5 2004/01/31 20:14:11 jdc Exp $ .\" .\" Copyright 2001 Wasabi Systems, Inc. .\" All rights reserved. .\" .\" Written by Jason R. Thorpe for Wasabi Systems, Inc. .\" .\" 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 for the NetBSD Project by .\" Wasabi Systems, Inc. .\" 4. The name of Wasabi Systems, Inc. may not be used to endorse .\" or promote products derived from this software without specific prior .\" written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``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 WASABI SYSTEMS, INC .\" 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 13, 2006 .Dt IF_BRIDGE 4 .Os .Sh NAME .Nm if_bridge .Nd network bridge device .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device if_bridge" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following lines in .Xr loader.conf 5 : .Bd -literal -offset indent if_bridge_load="YES" bridgestp_load="YES" .Ed .Sh DESCRIPTION The .Nm driver creates a logical link between two or more IEEE 802 networks that use the same (or .Dq "similar enough" ) framing format. For example, it is possible to bridge Ethernet and 802.11 networks together, but it is not possible to bridge Ethernet and Token Ring together. .Pp Each .Nm interface is created at runtime using interface cloning. This is most easily done with the .Xr ifconfig 8 .Cm create command or using the .Va cloned_interfaces variable in .Xr rc.conf 5 . .Pp A bridge can be used to provide several services, such as a simple 802.11-to-Ethernet bridge for wireless hosts, and traffic isolation. .Pp A bridge works like a hub, forwarding traffic from one interface to another. Multicast and broadcast packets are always forwarded to all interfaces that are part of the bridge. For unicast traffic, the bridge learns which MAC addresses are associated with which interfaces and will forward the traffic selectively. .Pp The .Nm driver implements the IEEE 802.1D Spanning Tree protocol (STP). Spanning Tree is used to detect and remove loops in a network topology. The bridge can log STP port changes to .Xr syslog 3 by enabling the .Va net.link.bridge.log_stp variable using .Xr sysctl 8 . .Pp All the bridged member interfaces need to be up in order to pass network traffic. These can be enabled using -.Xr ifconfig 8 +.Xr ifconfig 8 or -.Va ifconfig_ Ns Ao Ar interface Ac Ns Va ="up" +.Va ifconfig_ Ns Ao Ar interface Ac Ns Li ="up" in .Xr rc.conf 5 . .Pp The MTU of the first member interface to be added is used as the bridge MTU. All additional members are required to have exactly the same value. .Pp The TXCSUM capability is disabled for any interface added to the bridge, and it is restored when the interface is removed again. .Pp The bridge supports .Dq monitor mode , where the packets are discarded after .Xr bpf 4 processing, and are not processed or forwarded further. This can be used to multiplex the input of two or more interfaces into a single .Xr bpf 4 stream. This is useful for reconstructing the traffic for network taps that transmit the RX/TX signals out through two separate interfaces. .Sh PACKET FILTERING -.Pp Packet filtering can be used with any firewall package that hooks in via the .Xr pfil 9 framework. When filtering is enabled, bridged packets will pass through the filter inbound on the originating interface, on the bridge interface and outbound on the appropriate interfaces. Either stage can be disabled. The filtering behaviour can be controlled using .Xr sysctl 8 : .Bl -tag -width ".Va net.link.bridge.pfil_onlyip" .It Va net.link.bridge.pfil_onlyip Controls the handling of non-IP packets which are not passed to .Xr pfil 9 . Set to .Li 1 to only allow IP packets to pass (subject to firewall rules), set to .Li 0 to unconditionally pass all non-IP Ethernet frames. .It Va net.link.bridge.pfil_member Set to .Li 1 to enable filtering on the incoming and outgoing member interfaces, set to .Li 0 to disable it. .It Va net.link.bridge.pfil_bridge Set to .Li 1 to enable filtering on the bridge interface, set to .Li 0 to disable it. .It Va net.link.bridge.ipfw Set to .Li 1 to enable layer2 filtering with .Xr ipfirewall 4 , set to .Li 0 to disable it. This needs to be enabled for .Xr dummynet 4 support. When .Va ipfw is enabled, .Va pfil_bridge and .Va pfil_member will be disabled so that IPFW is not run twice; these can be re-enabled if desired. .El .Pp ARP and REVARP packets are forwarded without being filtered and others that are not IP nor IPv6 packets are not forwarded when .Va pfil_onlyip is enabled. IPFW can filter Ethernet types using .Cm mac-type so all packets are passed to the filter for processing. .Pp Note that packets to and from the bridging host will be seen by the filter on the interface with the appropriate address configured as well as on the interface on which the packet arrives or departs. .Sh EXAMPLES The following when placed in the file .Pa /etc/rc.conf will cause a bridge called .Dq Li bridge0 to be created, and will add the interfaces .Dq Li ath0 and .Dq Li fxp0 to the bridge, and then enable packet forwarding. Such a configuration could be used to implement a simple 802.11-to-Ethernet bridge (assuming the 802.11 interface is in ad-hoc mode). .Bd -literal -offset indent cloned_interfaces="bridge0" ifconfig_bridge0="addm ath0 addm fxp0 up" .Ed .Pp For the bridge to forward packets all member interfaces and the bridge need to be up. The above example would also require: .Bd -literal -offset indent ifconfig_ath0="up ssid my_ap mode 11g mediaopt hostap" ifconfig_fxp0="up" .Ed .Pp Consider a system with two 4-port Ethernet boards. The following will cause a bridge consisting of all 8 ports with Spanning Tree enabled to be created: .Bd -literal -offset indent ifconfig bridge0 create ifconfig bridge0 \e addm fxp0 stp fxp0 \e addm fxp1 stp fxp1 \e addm fxp2 stp fxp2 \e addm fxp3 stp fxp3 \e addm fxp4 stp fxp4 \e addm fxp5 stp fxp5 \e addm fxp6 stp fxp6 \e addm fxp7 stp fxp7 \e up .Ed .Pp The bridge can tunnel Ethernet across an IP internet using the EtherIP protocol. This can be combined with .Xr ipsec 4 to provide an encrypted connection. Create a .Xr gif 4 interface and set the local and remote IP addresses for the tunnel, these are reversed on the remote bridge. .Bd -literal -offset indent ifconfig gif0 create ifconfig gif0 tunnel 1.2.3.4 5.6.7.8 up ifconfig bridge0 create ifconfig bridge0 addm fxp0 addm gif0 up .Ed .Sh SEE ALSO .Xr gif 4 , .Xr ipf 4 , .Xr ipfw 4 , .Xr pf 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm driver first appeared in .Fx 6.0 . .Sh AUTHORS .An -nosplit The .Nm bridge driver was originally written by .An Jason L. Wright .Aq jason@thought.net as part of an undergraduate independent study at the University of North Carolina at Greensboro. .Pp This version of the .Nm driver has been heavily modified from the original version by .An Jason R. Thorpe .Aq thorpej@wasabisystems.com . .Sh BUGS The .Nm driver currently supports only Ethernet and Ethernet-like (e.g., 802.11) network devices, with exactly the same interface MTU size as the bridge device. .Pp Only wireless interfaces in hostap mode can be bridged due to the 802.11 framing format, bridging a wireless client is not supported yet. .Pp The bridge implements version IEEE 802.1D 1998 of the Spanning Tree Protocol so newer features in IEEE 802.1D 2004 such as RSTP are not available. Index: head/share/man/man4/iic.4 =================================================================== --- head/share/man/man4/iic.4 (revision 162403) +++ head/share/man/man4/iic.4 (revision 162404) @@ -1,182 +1,182 @@ .\" Copyright (c) 2006, M. Warner Losh .\" Copyright (c) 1998, Nicolas Souchu .\" 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 6, 2006 .Dt IIC 4 .Os .Sh NAME .Nm iic .Nd I2C generic I/O device driver .Sh SYNOPSIS .Cd "device iic" .Pp .In dev/iicbus/iic.h .Sh DESCRIPTION The .Nm device driver provides generic I/O to any .Xr iicbus 4 instance. In order to control I2C devices, use .Pa /dev/iic? with the following ioctls: .Bl -tag -width ".Dv I2CRSTCARD" .It Dv I2CSTART .Pq Vt "struct iiccmd" Sends the start condition to the slave specified by the .Va slave element to the bus. All other elements are ignored. .It Dv I2CSTOP No argument is passed. Sends the stop condition to the bus. This terminates the current transaction. .It Dv I2CRSTCARD .Pq Vt "struct iiccmd" Resets the bus. The argument is completely ignored. .It Dv I2CWRITE .Pq Vt "struct iiccmd" Writes data to the .Xr iicbus 4 . The bus should already be started. The .Va slave element is ignored. The .Va count element is the number of bytes to write. The .Va last element is a boolean flag. It is non-zero when additional write commands will follow. The .Va buf element is a pointer to the data to write to the bus. .It Dv I2CREAD .Pq Vt "struct iiccmd" Reads data from the .Xr iicbus 4 . The bus should already be started. The .Va slave element is ignored. The .Va count element is the number of bytes to write. The .Va last element is a boolean flag. It is non-zero when additional write commands will follow. The .Va buf element is a pointer to where to store the data read from the bus. Short reads on the bus produce undefined results. .It Dv I2CRDWR .Pq Vt "struct iic_rdwr_data" Generic read/write interface. Allows for an arbitrary number of commands to be sent to an arbitrary number of devices on the bus. A read transfer is speficied if .Dv IIC_M_RD is set in .Va flags . Otherwise the transfer is a write transfer. The .Va slave element specifies the 7-bit address for the transfer. The .Va len element is the length of the data. The .Va buf element is a buffer for that data. This ioctl is intended to be .Tn Linux compatible. .El .Pp The following data structures are defined in .In dev/iicbus/iic.h and referenced above: .Bd -literal -offset indent struct iiccmd { u_char slave; int count; int last; char *buf; }; /* Designed to be compatible with linux's struct i2c_msg */ struct iic_msg { uint16_t slave; uint16_t flags; #define IIC_M_RD 0x0001 /* read vs write */ uint16_t len; /* msg legnth */ uint8_t * buf; }; struct iic_rdwr_data { struct iic_msg *msgs; uint32_t nmsgs; }; .Ed .Pp It is also possible to use read/write routines, then I2C start/stop handshake is managed by the .Xr iicbus 4 system. However, the address used for the read/write routines is the one passed to last .Dv I2CSTART .Xr ioctl 2 to this device. -.Sh BUGS -Only the -.Dv I2CRDWR -.Xr ioctl 2 -is thread safe. -All other interfaces suffer from some kind of race. .Sh SEE ALSO .Xr ioctl 2 , .Xr read 2 , .Xr write 2 , .Xr iicbus 4 .Sh HISTORY The .Nm manual page first appeared in .Fx 3.0 . .Sh AUTHORS .An -nosplit This manual page was written by .An Nicolas Souchu and .An M. Warner Losh . +.Sh BUGS +Only the +.Dv I2CRDWR +.Xr ioctl 2 +is thread safe. +All other interfaces suffer from some kind of race. Index: head/share/man/man4/ipsec.4 =================================================================== --- head/share/man/man4/ipsec.4 (revision 162403) +++ head/share/man/man4/ipsec.4 (revision 162404) @@ -1,329 +1,339 @@ .\" $KAME: ipsec.4,v 1.17 2001/06/27 15:25:10 itojun Exp $ .\" .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. .\" 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 project 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 PROJECT AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 24, 2006 .Dt IPSEC 4 .Os .Sh NAME .Nm ipsec .Nd IP security protocol .Sh SYNOPSIS -.In sys/types.h -.In netinet/in.h -.In netinet6/ipsec.h .Cd "options IPSEC" .Cd "options IPSEC_DEBUG" .Cd "options IPSEC_ESP" .Cd "options IPSEC_FILTERGIF" +.Pp +.In sys/types.h +.In netinet/in.h +.In netinet6/ipsec.h .Sh DESCRIPTION .Nm is a security protocol implemented within the Internet Protocol layer of the TCP/IP stack. .Nm is defined for both IPv4 and IPv6 .Xr ( inet 4 and .Xr inet6 4 ) . .Nm -contains two protocols, +contains two protocols, ESP, the encapsulated security payload protocol and AH, the authentication header protocol. ESP prevents unauthorized parties from reading the payload of an IP packet by encrypting it using secret key cryptography algorithms. AH both authenticates guarantees the integrity of an IP packet by attaching a cryptographic checksum computed using one-way hash functions. .Nm has operates in one of two modes: transport mode or tunnel mode. Transport mode is used to protect peer-to-peer communication between end nodes. Tunnel mode encapsulates IP packets within other IP packets and is designed for security gateways such as VPN endpoints. .\" .Ss Kernel interface .Nm is controlled by a key management and policy engine, -that reside in the operating system kernel. Key management +that reside in the operating system kernel. +Key management is the process of associating keys with security associations, also -know as SAs. Policy management dictates when new security +know as SAs. +Policy management dictates when new security associations created or destroyed. .Pp The key management engine can be accessed from userland by using .Dv PF_KEY sockets. The .Dv PF_KEY socket API is defined in RFC2367. .Pp The policy engine is controlled by an extension to the .Dv PF_KEY API, .Xr setsockopt 2 operations, and .Xr sysctl 3 interface. The kernel implements an extended version of the .Dv PF_KEY interface, and allows the programmer to define IPsec policies -which are similar to the per-packet filters. The +which are similar to the per-packet filters. +The .Xr setsockopt 2 interface is used to define per-socket behavior, and .Xr sysctl 3 interface is used to define host-wide default behavior. .Pp The kernel code does not implement a dynamic encryption key exchange protocol such as IKE (Internet Key Exchange). Key exchange protocols are beyond what is necessary in the kernel and should be implemented as daemon processes which call the .Nm APIs. .\" .Ss Policy management -IPsec policies can be managed in one of two ways, either by +IPsec policies can be managed in one of two ways, either by configuring per-socket policies using the -.Xr setsockopt 2 +.Xr setsockopt 2 system calls, or by configuring kernel level packet filter-based policies using the .Dv PF_KEY interface, via the -.Xr setkey 8 +.Xr setkey 8 command. In either case, IPsec policies must be specified using the syntax described in .Xr ipsec_set_policy 3 . Please refer to the .Xr setkey 8 man page for instructions on its use. .Pp When setting policies using the .Xr setkey 8 command the .Dq Li default option you can have the system use its default policy, explained below, for processing packets. The following sysctl variables are available for configuring the -system's IPsec behavior. The variables can have one of two values. +system's IPsec behavior. +The variables can have one of two values. A .Li 1 means .Dq Li use , which means that if there is a security association then use it but if -there is not then the packets are not processed by IPsec. The value +there is not then the packets are not processed by IPsec. +The value .Li 2 is synonymous with .Dq Li require , which requires that a security association must exist for the packets -to move, and not be dropped. These terms are defined in +to move, and not be dropped. +These terms are defined in .Xr ipsec_set_policy 8 . .Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx .It Sy "Name Type Changeable" .It "net.inet.ipsec.esp_trans_deflev integer yes" .It "net.inet.ipsec.esp_net_deflev integer yes" .It "net.inet.ipsec.ah_trans_deflev integer yes" .It "net.inet.ipsec.ah_net_deflev integer yes" .It "net.inet6.ipsec6.esp_trans_deflev integer yes" .It "net.inet6.ipsec6.esp_net_deflev integer yes" .It "net.inet6.ipsec6.ah_trans_deflev integer yes" .It "net.inet6.ipsec6.ah_net_deflev integer yes" .El .Pp If the kernel does not find a matching, system wide, policy then the -default value is applied. The system wide default policy is specified +default value is applied. +The system wide default policy is specified by the following .Xr sysctl 8 variables. .Li 0 means .Dq Li discard which asks the kernel to drop the packet. .Li 1 means .Dq Li none . .Bl -column net.inet6.ipsec6.def_policy integerxxx .It Sy "Name Type Changeable" .It "net.inet.ipsec.def_policy integer yes" .It "net.inet6.ipsec6.def_policy integer yes" .El .\" .Ss Miscellaneous sysctl variables The following variables are accessible via .Xr sysctl 8 , for tweaking the kernel's IPsec behavior: .Bl -column net.inet6.ipsec6.inbonud_call_ike integerxxx .It Sy "Name Type Changeable" .It "net.inet.ipsec.ah_cleartos integer yes" .It "net.inet.ipsec.ah_offsetmask integer yes" .It "net.inet.ipsec.dfbit integer yes" .It "net.inet.ipsec.ecn integer yes" .It "net.inet.ipsec.debug integer yes" .It "net.inet6.ipsec6.ecn integer yes" .It "net.inet6.ipsec6.debug integer yes" .El .Pp The variables are interpreted as follows: .Bl -tag -width 6n .It Li ipsec.ah_cleartos If set to non-zero, the kernel clears the type-of-service field in the IPv4 header during AH authentication data computation. This variable is used to get current systems to inter-operate with devices that implement RFC1826 AH. It should be set to non-zero (clear the type-of-service field) for RFC2402 conformance. .It Li ipsec.ah_offsetmask During AH authentication data computation, the kernel will include a 16bit fragment offset field (including flag bits) in the IPv4 header, after computing logical AND with the variable. The variable is used for inter-operating with devices that implement RFC1826 AH. It should be set to zero (clear the fragment offset field during computation) for RFC2402 conformance. .It Li ipsec.dfbit This variable configures the kernel behavior on IPv4 IPsec tunnel encapsulation. If set to 0, the DF bit on the outer IPv4 header will be cleared while 1 means that the outer DF bit is set regardless from the inner DF bit and 2 indicates that the DF bit is copied from the inner header to the outer one. The variable is supplied to conform to RFC2401 chapter 6.1. .It Li ipsec.ecn If set to non-zero, IPv4 IPsec tunnel encapsulation/decapsulation behavior will be friendly to ECN (explicit congestion notification), as documented in .Li draft-ietf-ipsec-ecn-02.txt . .Xr gif 4 talks more about the behavior. .It Li ipsec.debug If set to non-zero, debug messages will be generated via .Xr syslog 3 . .El .Pp Variables under the .Li net.inet6.ipsec6 tree have similar meanings to those described above. .\" .Sh PROTOCOLS The .Nm protocol acts as a plug-in to the .Xr inet 4 and .Xr inet6 4 protocols and therefore supports most of the protocols defined upon -those IP-layer protocols. The +those IP-layer protocols. +The .Xr icmp 4 and -.Xr icmp6 4 +.Xr icmp6 4 protocols may behave differently with -.Nm +.Nm because .Nm can prevent .Xr icmp 4 or .Xr icmp6 4 routines from looking into the IP payload. .\" .Sh SEE ALSO .Xr ioctl 2 , .Xr socket 2 , .Xr ipsec_set_policy 3 , .Xr fast_ipsec 4 , .Xr icmp6 4 , .Xr intro 4 , .Xr ip6 4 , .Xr setkey 8 , .Xr sysctl 8 .\".Xr racoon 8 .Rs .%A "S. Kent" .%A "R. Atkinson" .%T "IP Authentication Header" .%O "RFC 2404" .Re .Rs .%A "S. Kent" .%A "R. Atkinson" .%T "IP Encapsulating Security Payload (ESP)" .%O "RFC 2406" .Re .Sh STANDARDS .Rs .%A Daniel L. McDonald .%A Craig Metz .%A Bao G. Phan .%T "PF_KEY Key Management API, Version 2" .%R RFC .%N 2367 .Re .Pp .Rs .%A "D. L. McDonald" .%T "A Simple IP Security API Extension to BSD Sockets" .%R internet draft .%N "draft-mcdonald-simple-ipsec-api-03.txt" .%O work in progress material .Re .Sh HISTORY The implementation described herein appeared in WIDE/KAME IPv6/IPsec stack. .Sh BUGS The IPsec support is subject to change as the IPsec protocols develop. .Pp There is no single standard for the policy engine API, so the policy engine API described herein is just for KAME implementation. .Pp AH and tunnel mode encapsulation may not work as you might expect. If you configure inbound .Dq require policy with an AH tunnel or any IPsec encapsulating policy with AH (like .Dq Li esp/tunnel/A-B/use ah/transport/A-B/require ) , tunnelled packets will be rejected. This is because the policy check is enforced on the inner packet on reception, and AH authenticates encapsulating (outer) packet, not the encapsulated (inner) packet (so for the receiving kernel there is no sign of authenticity). The issue will be solved when we revamp our policy engine to keep all the packet decapsulation history. .Pp When a large database of security associations or policies is present in the kernel the .Dv SADB_DUMP and .Dv SADB_SPDDUMP operations on .Dv PF_KEY -sockets may fail due to lack of space. Increasing the socket buffer +sockets may fail due to lack of space. +Increasing the socket buffer size may alleviate this problem. Index: head/share/man/man4/isp.4 =================================================================== --- head/share/man/man4/isp.4 (revision 162403) +++ head/share/man/man4/isp.4 (revision 162404) @@ -1,225 +1,222 @@ .\" $NetBSD: isp.4,v 1.5 1999/12/18 18:33:05 mjacob Exp $ .\" .\" Copyright (c) 1998, 1999, 2001 .\" Matthew Jacob, for 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. 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. .\" .\" Additional Copyright (c) 2006 by Marcus Alves Grando .\" .\" $FreeBSD$ .\" .Dd February 6, 2006 .Dt ISP 4 .Os .Sh NAME .Nm isp .Nd Qlogic based SCSI and FibreChannel SCSI Host Adapters .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device scbus" .Cd "device isp" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent isp_load="YES" .Ed .Sh DESCRIPTION This driver provides access to .Tn SCSI or .Tn FibreChannel devices. .Pp SCSI features include support for Ultra SCSI and wide mode transactions for .Tn SCSI , Ultra2 LVD (for the ISP1080 and ISP1280), and Ultra3 LVD (for the ISP12160). .Pp Fibre Channel support uses FCP SCSI profile for .Tn FibreChannel . and utilizes Class 3 and Class 2 connections (Qlogic 2100 is Class 3 only, minor patches to the Qlogic 2200 to force Class 2 mode). Support is available for Public and Private loops, and for point-to-point connections (Qlogic 2200 only). The newer 2-Gigabit cards (2300, 2312) are also supported. Command tagging is supported for all (in fact, .Tn FibreChannel requires tagging). Fabric support is enabled by default (but may be contingent upon the correct firmware being loaded). .Sh FIRMWARE Firmware is available if the .Xr ispfw 4 module is loaded during bootstrap (q.v.). .Pp It is very strongly recommended that you use the firmware available from .Xr ispfw 4 as it is the most likely to have been tested with this driver. .Sh HARDWARE Cards supported by the .Nm driver include: .Pp .Bl -tag -width xxxxxx -offset indent .It ISP1000 SBus Fast Wide, Ultra Fast Wide cards, Single Ended or Differential cards. .It ISP1020 Qlogic 1020 Fast Wide and Differential Fast Wide PCI cards. .It ISP1040 Qlogic 1040 Ultra Wide and Differential Ultra Wide PCI cards. Also known as the DEC KZPBA-CA (single ended) and KZPBA-CB (HVD differential). .It Qlogic 1240 Qlogic 1240 Dual Bus Ultra Wide and Differential Ultra Wide PCI cards. .It Qlogic 1020 Qlogic 1020 SCSI cards. .It Qlogic 1040 Qlogic 1040 Ultra SCSI cards. .It Qlogic 1080 Qlogic 1280 LVD Ultra2 Wide PCI cards. .It Qlogic 1280 Qlogic 1280 Dual Bus LVD Ultra2 Wide PCI cards. .It Qlogic 12160 Qlogic 12160 Dual Bus LVD Ultra3 Wide PCI cards. .It Qlogic 210X Qlogic 2100 and 2100A Copper and Optical Fibre Channel Arbitrated Loop (single, dual). .It Qlogic 220X Qlogic 2200 Copper and Optical Fibre Channel Arbitrated Loop PCI cards (single, dual, quad). .It Qlogic 2300 Qlogic 2300 Optical Fibre Channel PCI cards. .It Qlogic 2312 Qlogic 2312 Optical Fibre Channel PCI cards. .It Qlogic 234X Qlogic 234X Optical Fibre Channel PCI cards (2312 chipset, single and dual attach). .It Qlogic 2322 Qlogic 2322 Optical Fibre Channel PCI cards. .It Qlogic 200 Dell Branded version of the QLogic 2312 Fibre Channel PCI cards. .El .Sh CONFIGURATION OPTIONS .Pp Target mode support may be enabled with the .Pp .Cd options ISP_TARGET_MODE .Pp option. .Sh BOOT OPTIONS The following options are switchable by setting values in .Pa /boot/device.hints . .Pp They are: -.Pp .Bl -tag -width indent .It Va hint.isp.0.disable A hint value to disable driver in kernel. .It Va hint.isp.0.fwload_disable A hint value to disable loading of firmware -.Cd ispfw(4) . +.Xr ispfw 4 . .It Va hint.isp.0.prefer_memmap -A hint value to use PCI Memory space instead of I/O space +A hint value to use PCI memory space instead of I/O space access for. .It Va hint.isp.0.prefer_iomap A hint value to use PCI I/O space instead of Memory space access for. .It Va hint.isp.0.ignore_nvram -A hint value to ignore board NVRAM settings for. Otherwise -use NVRAM settings. +A hint value to ignore board NVRAM settings for. +Otherwise use NVRAM settings. .It Va hint.isp.0.fullduplex A hint value to set full duplex mode. .It Va hint.isp.0.topology -A hint value to select topology of connection. Supported -values are: +A hint value to select topology of connection. +Supported values are: .Pp -.Cd lport -(Prefer loopback and fallback to point to point). -.Pp -.Cd nport -(Prefer point to point and fallback to loopback). -.Pp -.Cd lport-only -(Loopback only). -.Pp -.Cd nport-only -(Point to point only). -.Pp +.Bl -tag -width ".Li lport-only" -compact +.It Li lport +Prefer loopback and fallback to point to point. +.It Li nport +Prefer point to point and fallback to loopback. +.It Li lport-only +Loopback only. +.It Li nport-only +Point to point only. +.El .It Va hint.isp.0.portwwn This should be the full 64 bit World Wide Port Name you would like to use, overriding the value in NVRAM for the card. .It Va hint.isp.0.nodewwn This should be the full 64 bit World Wide Node Name you would like to use, overriding the value in NVRAM for the card. .It Va hint.isp.0.iid A hint to override or set the Initiator ID (principally for SPI SCSI). .It Va hint.isp.0.role A hint to define default role for isp instance (target, initiator, both). .It Va hint.isp.0.debug A hint value for a driver debug level (values from 0 through 7). Default is 0. .El .Sh SEE ALSO .Xr da 4 , .Xr intro 4 , .Xr ispfw 4 , .Xr sa 4 , .Xr scsi 4 .Sh AUTHORS The .Nm driver was written by Matthew Jacob for NASA/Ames Research Center. .Sh BUGS The driver currently ignores some NVRAM settings. .Pp The driver currently does not do error recovery for timed out commands very gracefully. .Pp Target mode support is not completely debugged yet. It works reasonably well for Fibre Channel, somewhat well for Qlogic 1040 cards, but does not yet work for the other cards (due to last minute unannounced changes in firmware interfaces). .Pp Sometimes, when booting, the driver gets stuck waiting for the Fibre Channel f/w to tell it that the loop port database is ready, or waiting for a good loop to be seen (this does not yet support booting without being connected to a fibre channel device). To unwedge the system, unplug and replug the fibre channel connection, or otherwise cause a LIP (Loop Initialization Primitive sequence)- this will kick the f/w into getting unstuck. .Pp QLogic 2322 support is limited to platforms where the BIOS can enable firmware as there is no code yet to do the 3 stage loading for 2322 firmware. Index: head/share/man/man4/man4.i386/linux.4 =================================================================== --- head/share/man/man4/man4.i386/linux.4 (revision 162403) +++ head/share/man/man4/man4.i386/linux.4 (revision 162404) @@ -1,131 +1,131 @@ .\" Copyright (c) 2000 Sheldon Hearn .\" 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 June 18, 2006 .Dt LINUX 4 i386 .Os .Sh NAME .Nm linux .Nd Linux ABI support .Sh SYNOPSIS To link Linux ABI support into the kernel: .Cd "options COMPAT_LINUX" .Pp To load the Linux ABI support kernel module: .Dl kldload linux .Sh DESCRIPTION The .Nm module provides limited Linux ABI (application binary interface) compatibility for userland applications. The module provides the following significant facilities: .Bl -bullet .It An image activator for correctly branded .Xr elf 5 executable images .It Special signal handling for activated images .It Linux to native system call translation .El .Pp It is important to note that the Linux ABI support it not provided through an emulator. Rather, a true (albeit limited) ABI implementation is provided. .Pp The following .Xr sysctl 8 tunable variables are available: .Bl -tag -width compat.linux.oss_version .It compat.linux.osname Linux kernel operating system name. .It compat.linux.osrelease Linux kernel operating system release. Changing this to something else is discouraged on non-development systems, -because it may change the way linux programs work. +because it may change the way Linux programs work. Recent versions of GNU libc are known to use different syscalls depending on the value of this sysctl. .It compat.linux.oss_version Linux Open Sound System version. .El .Pp The .Nm module can be linked into the kernel statically with the .Dv COMPAT_LINUX kernel configuration option or loaded as required. The following command will load the module if it is neither linked into the kernel nor already loaded as a module: .Bd -literal -offset indent if ! kldstat -v | grep -E 'linux(aout|elf)' > /dev/null; then kldload linux > /dev/null 2>&1 fi .Ed .Pp Note that dynamically linked Linux executables will require a suitable environment in .Pa /compat/linux . Specifically, the Linux run-time linker's hints files should be correctly initialized. For this reason, it is common to execute the following commands to prepare the system to correctly run Linux executables: .Bd -literal -offset indent if [ -x /compat/linux/sbin/ldconfig ]; then /compat/linux/sbin/ldconfig -r /compat/linux fi .Ed .Pp For information on loading the .Nm kernel loadable module automatically on system startup, see .Xr rc.conf 5 . This information applies regardless of whether the .Nm module is statically linked into the kernel or loaded as a module. .Sh FILES .Bl -tag -width /compat/linux/proc -compact .It Pa /compat/linux minimal Linux run-time environment .It Pa /compat/linux/proc limited Linux process file system .It Pa /compat/linux/sys limited Linux system file system .El .Sh SEE ALSO .Xr brandelf 1 , .Xr elf 5 , .Xr linprocfs 5 , .Xr linsysfs 5 .Sh HISTORY Linux ABI support first appeared in .Fx 2.1 . Index: head/share/man/man4/man4.sparc64/machfb.4 =================================================================== --- head/share/man/man4/man4.sparc64/machfb.4 (revision 162403) +++ head/share/man/man4/man4.sparc64/machfb.4 (revision 162404) @@ -1,180 +1,180 @@ .\"- .\" Copyright (c) 2002 Jason L. Wright (jason@thought.net) .\" Copyright (c) 2005, 2006 Marius Strobl .\" 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. .\" .\" from: OpenBSD: creator.4,v 1.20 2005/03/05 01:48:59 miod Exp .\" $FreeBSD$ .\" .Dd September 2, 2006 .Dt MACHFB 4 sparc64 .Os .Sh NAME .Nm machfb .Nd "accelerated color frame buffer" .Sh SYNOPSIS .Cd "device machfb" .Sh DESCRIPTION The .Tn ATI Mach64 family of chips are color frame buffers with graphics acceleration. The .Nm driver interfaces those frame buffers with the .Xr syscons 4 console driver. .Pp .Tn ATI Mach64 chips are very common as low-end graphics chips in .Tn PCI based .Tn UltraSPARC systems. They are found on-board in .Tn Sun Blade 100 , .Tn Sun Blade 150 , .Tn Sun Ultra 5 and .Tn Sun Ultra 10 as well as on .Tn Sun OEM mainboards like the .Tn Sun AXe . They are also used on add-on cards like the .Tn Sun PGX and .Tn Sun PGX64 . .Pp The .Nm driver requires the chip which it is supposed to drive to be also supported by the .Tn Open Firmware , either by a built-in FCode driver package of the on-board firmware or by additional FCode on the add-on card. As a matter of course .Tn UltraSPARC systems with an on-board .Tn ATI Mach64 chip also have a built-in FCode driver package for this chip. There are also mainboards like the .Tn Sun AX1105 and .Tn Sun AXi boards however, which have built-in FCode for certain .Tn ATI Mach64 chips although they are not equipped with an on-board one. Mainboards with built-in FCode for certain .Tn ATI Mach64 chips can be used with any add-on card which is based on one of those chips, including cards which are equipped with x86 firmware and intended for use in PCs. Otherwise an add-on card which comes with its own FCode like the .Tn Sun PGX or .Tn Sun PGX64 has to be used. .Sh HARDWARE The .Nm driver provides support for the following chips: .Pp .Bl -bullet -compact .It .Tn ATI 3D Rage II+ .It .Tn ATI 3D Rage IIC .It .Tn ATI 3D Rage I/II .It .Tn ATI 3D Rage LT .It .Tn ATI 3D Rage LT Pro .It .Tn ATI 3D Rage Pro .It .Tn ATI 3D Rage Pro Turbo .It .Tn ATI Mach64 CT .It .Tn ATI Mach64 VT .It .Tn ATI Mach64 VT4 .It .Tn ATI Mach64 VTB .It .Tn ATI Rage L Mobility .It .Tn ATI Rage Mobility .It .Tn ATI Rage Mobility M1 .It .Tn ATI Rage Mobility M3 .It .Tn ATI Rage XC .It .Tn ATI Rage XL .El .Pp The following add-on cards are known to work with the .Nm driver at this time: .Pp .Bl -bullet -compact .It .Tn ATI 3D Charger PCI .It .Tn Sun PGX 8-Bit Color Frame Buffer -(part no. 370-2256) +(part no.\& 370-2256) .It .Tn Sun PGX64 8/24-Bit Color Frame Buffer -(part no. 370-4362) +(part no.\& 370-4362) .El .Sh CAVEATS Font loading and mode switching are not implemented. .Sh SEE ALSO .Xr creator 4 , .Xr syscons 4 .Sh HISTORY The .Nm driver first appeared in .Nx 2.0 . The first .Fx version to include it was .Fx 6.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An "Marius Strobl" Aq marius@FreeBSD.org based on the .Nx driver written by .An "Bang Jun-Young" . Index: head/share/man/man4/mpt.4 =================================================================== --- head/share/man/man4/mpt.4 (revision 162403) +++ head/share/man/man4/mpt.4 (revision 162404) @@ -1,171 +1,169 @@ .\" $NetBSD: mpt.4,v 1.1 2003/04/16 22:32:15 thorpej Exp $ .\" .\" Copyright (c) 2003 Wasabi Systems, Inc. .\" All rights reserved. .\" .\" Written by Jason R. Thorpe for Wasabi Systems, Inc. .\" .\" 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 for the NetBSD Project by .\" Wasabi Systems, Inc. .\" 4. The name of Wasabi Systems, Inc. may not be used to endorse .\" or promote products derived from this software without specific prior .\" written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``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 WASABI SYSTEMS, INC .\" 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 5, 2006 .Dt MPT 4 .Os .Sh NAME .Nm mpt .Nd LSI Fusion-MPT SCSI/Fibre Channel driver .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device scbus" .Cd "device mpt" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent mpt_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for the LSI Logic Fusion-MPT family of .Tn SCSI , .Tn Fibre Channel and .Tn SAS controllers. .Sh HARDWARE The following controllers are supported by the .Nm driver: .Pp .Bl -bullet -compact .It LSI Logic 53c1030, LSI Logic LSI2x320-X (Single and Dual Ultra320 .Tn SCSI ) .It LSI Logic AS1064, LSI Logic AS1068 -( -.Tn SAS/SATA ) +.Pq Tn SAS/SATA .It LSI Logic FC909 (1Gb/s .Tn Fibre Channel ) .It LSI Logic FC909A (Dual 1Gb/s .Tn Fibre Channel ) .It LSI Logic FC919, LSI Logic 7102XP-LC (Single 2Gb/s .Tn Fibre Channel ) .It LSI Logic FC929, LSI Logic FC929X, LSI Logic 7202XP-LC (Dual 2Gb/s .Tn Fibre Channel ) .It LSI Logic FC949X (Dual 4Gb/s .Tn Fibre Channel ) .El .Pp The .Tn SCSI controller chips supported by the .Nm driver can be found onboard on many systems including: .Pp .Bl -bullet -compact .It Dell PowerEdge 1750 thru 2850 .It IBM eServer xSeries 335 .El .Pp These systems also contain Integrated Raid Mirroring and Integrated Raid Mirroring Enhanced which this driver also supports. .Pp The .Tn SAS controller chips are also present on many new AMD/Opteron based systems, like the Sun 4100. Note that this controller can drive both SAS and SATA drives or a mix of them at the same time. .Pp This driver also supports target mode for Fibre Channel cards. This support may be enabled by setting the desired role of the core via the LSI Logic firmware utility that establishes what roles the card can take on - no separate compilation is required. .Sh SEE ALSO .Xr cd 4 , .Xr ch 4 , .Xr da 4 , .Xr pci 4 , .Xr sa 4 , .Xr scsi 4 , .Xr targ 4 .Rs .%T "LSI Logic Website" .%O http://www.lsilogic.com/ .Re -.Sh BUGS -.Pp -This driver has been reported to have problems under the VMware ESX server. -.Pp -This driver does not yet work on big endian machines like Sparc64. .Sh HISTORY The .Nm driver first appeared in .Fx 4.6 . .Sh AUTHORS .An -nosplit The .Nm driver was originally written for .Fx by .An Greg Ansley and substantially improved upon by .An Matt Jacob Aq mjacob@FreeBSD.org and .An Justin Gibbs Aq gibbs@FreeBSD.org . +.Sh BUGS +This driver has been reported to have problems under the VMware ESX server. +.Pp +This driver does not yet work on big endian machines like Sparc64. Index: head/share/man/man4/ng_pppoe.4 =================================================================== --- head/share/man/man4/ng_pppoe.4 (revision 162403) +++ head/share/man/man4/ng_pppoe.4 (revision 162404) @@ -1,506 +1,504 @@ .\" Copyright (c) 1996-1999 Whistle Communications, 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 Whistle Communications; .\" 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 Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS 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. .\" WHISTLE COMMUNICATIONS 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 WHISTLE COMMUNICATIONS 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" $Whistle: ng_pppoe.8,v 1.1 1999/01/25 23:46:27 archie Exp $ .\" .Dd August 9, 2006 .Dt NG_PPPOE 4 .Os .Sh NAME .Nm ng_pppoe .Nd RFC 2516 PPPoE protocol netgraph node type .Sh SYNOPSIS .In sys/types.h .In net/ethernet.h .In netgraph.h .In netgraph/ng_pppoe.h .Sh DESCRIPTION The .Nm pppoe node type performs the PPPoE protocol. It is used in conjunction with the .Xr netgraph 4 extensions to the Ethernet framework to divert and inject Ethernet packets to and from a PPP agent (which is not specified). .Pp The .Dv NGM_PPPOE_GET_STATUS control message can be used at any time to query the current status of the PPPoE module. The only statistics presently available are the total packet counts for input and output. This node does not yet support the .Dv NGM_TEXT_STATUS control message. .Sh HOOKS This node type supports the following hooks: .Pp .Bl -tag -width [unspecified] .It Dv ethernet The hook that should normally be connected to an .Xr ng_ether 4 node. Once connected, .Nm will send a message down this hook to determine Ethernet address of the underlying node. Obtained address will be stored and then used for outgoing datagrams. .It Dv debug Presently no use. .It Dv [unspecified] Any other name is assumed to be a session hook that will be connected to a PPP client agent, or a PPP server agent. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width 3n .It Dv NGM_PPPOE_GET_STATUS This command returns status information in a .Dv "struct ngpppoestat" : .Bd -literal -offset 4n struct ngpppoestat { u_int packets_in; /* packets in from Ethernet */ u_int packets_out; /* packets out towards Ethernet */ }; .Ed .It Dv NGM_TEXT_STATUS This generic message returns a human-readable version of the node status. (not yet) .It Dv NGM_PPPOE_CONNECT Tell a nominated newly created hook that its session should enter the state machine in a manner to become a client. It must be newly created and a service name can be given as an argument. It is legal to specify a zero length service name. This is common on some DSL setups. A session request packet will be broadcast on the Ethernet. This command uses the .Dv ngpppoe_init_data structure shown below. .It Dv NGM_PPPOE_LISTEN Tell a nominated newly created hook that its session should enter the state machine in a manner to become a server listener. The argument given is the name of the service to listen on behalf of a zero length service length will match all requests for service. A matching service request packet will be passed unmodified back to the process responsible for starting the service. It can then examine it and pass it on to the session that is started to answer the request. This command uses the .Dv ngpppoe_init_data structure shown below. .It Dv NGM_PPPOE_OFFER Tell a nominated newly created hook that its session should enter the state machine in a manner to become a server. The argument given is the name of the service to offer. A zero length service is legal. The State machine will progress to a state where it will await a request packet to be forwarded to it from the startup server, which in turn probably received it from a LISTEN mode hook ( see above). This is so that information that is required for the session that is embedded in the original session request packet, is made available to the state machine that eventually answers the request. When the Session request packet is received, the session negotiation will proceed. This command uses the .Dv ngpppoe_init_data structure shown below. .El .Pp The three commands above use a common data structure: .Bd -literal -offset 4n struct ngpppoe_init_data { char hook[NG_HOOKSIZ]; /* hook to monitor on */ u_int16_t data_len; /* service name length */ char data[0]; /* init data goes here */ }; .Ed .Bl -tag -width 3n .It Dv NGM_PPPOE_SUCCESS This command is sent to the node that started this session with one of the above messages, and reports a state change. This message reports successful Session negotiation. It uses the structure shown below, and reports back the hook name corresponding to the successful session. .It Dv NGM_NGM_PPPOE_FAIL This command is sent to the node that started this session with one of the above messages, and reports a state change. This message reports failed Session negotiation. It uses the structure shown below, and reports back the hook name corresponding to the failed session. The hook will probably have been removed immediately after sending this message .It Dv NGM_NGM_PPPOE_CLOSE This command is sent to the node that started this session with one of the above messages, and reports a state change. This message reports a request to close a session. It uses the structure shown below, and reports back the hook name corresponding to the closed session. The hook will probably have been removed immediately after sending this message. At present this message is not yet used and a 'failed' message will be received at closure instead. .It Dv NGM_PPPOE_ACNAME This command is sent to the node that started this session with one of the above messages, and reports the Access Concentrator Name. .El .Pp The four commands above use a common data structure: .Bd -literal -offset 4n struct ngpppoe_sts { char hook[NG_HOOKSIZ]; /* hook associated with event session */ }; .Ed .Bl -tag -width 3n .It Dv NGM_PPPOE_GETMODE This command returns the current compatibility mode of the node as a string. .Tn ASCII form of this message is .Qq Li pppoe_getmode . -The following keywords are can be returned: +The following keywords can be returned: .Bl -tag -width 3n .It Qq standard The node operates according to RFC 2516. .It Qq 3Com When .Nm is a PPPoE client, it initiates a session encapsulating packets into incorrect 3Com ethertypes. This compatibility option does not affect server mode. In server mode .Nm supports both modes simultaneously, depending on the ethertype, the client used when connecting. .It Qq D-Link When .Nm is a PPPoE server serving only specific Service-Name(s), it will respond to a PADI requests with empty Service-Name tag, returning all available Service-Name(s) on node. This option is necessary for compatibility with D-Link DI-614+ and DI-624+ SOHO routers as clients, when serving only specific Service-Name. This compatibility option does not affect client mode. .El -.Pp .It Dv NGM_PPPOE_SETMODE Configure node to the specified mode. The string argument is required. -This command understands same keywords, that are returned by +This command understands the same keywords that are returned by the .Dv NGM_PPPOE_GETMODE command. .Tn ASCII form of this message is .Qq Li pppoe_setmode . For example, the following command will configure the node to initiate the next session in the proprietary 3Com mode: -.Pp .Bd -literal -offset indent ngctl msg fxp0:orphans pppoe_setmode '"3Com"' .Ed .It Dv NGM_PPPOE_SETENADDR Set the node Ethernet address for outgoing datagrams. This message is important when a node has failed to obtain an Ethernet address from its peer on the .Dv ethernet hook, or when user wants to override this address with another one. .Tn ASCII form of this message is .Qq Li setenaddr . .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, when all session have been disconnected or when the .Dv ethernet hook is disconnected. .Sh EXAMPLES The following code uses .Dv libnetgraph to set up a .Nm node and connect it to both a socket node and an Ethernet node. It can handle the case of when a .Nm node is already attached to the Ethernet. It then starts a client session. .Bd -literal #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include static int setup(char *ethername, char *service, char *sessname, int *dfd, int *cfd); int main() { int fd1, fd2; setup("xl0", NULL, "fred", &fd1, &fd2); sleep (30); } static int setup(char *ethername, char *service, char *sessname, int *dfd, int *cfd) { struct ngm_connect ngc; /* connect */ struct ngm_mkpeer mkp; /* mkpeer */ /******** nodeinfo stuff **********/ u_char rbuf[2 * 1024]; struct ng_mesg *const resp = (struct ng_mesg *) rbuf; struct hooklist *const hlist = (struct hooklist *) resp->data; struct nodeinfo *const ninfo = &hlist->nodeinfo; int ch, no_hooks = 0; struct linkinfo *link; struct nodeinfo *peer; /****message to connect PPPoE session*****/ struct { struct ngpppoe_init_data idata; char service[100]; } message; /********tracking our little graph ********/ char path[100]; char source_ID[NG_NODESIZ]; char pppoe_node_name[100]; int k; /* * Create the data and control sockets */ if (NgMkSockNode(NULL, cfd, dfd) < 0) { return (errno); } /* * find the ether node of the name requested by asking it for * it's inquiry information. */ if (strlen(ethername) > 16) return (EINVAL); sprintf(path, "%s:", ethername); if (NgSendMsg(*cfd, path, NGM_GENERIC_COOKIE, NGM_LISTHOOKS, NULL, 0) < 0) { return (errno); } /* * the command was accepted so it exists. Await the reply (It's * almost certainly already waiting). */ if (NgRecvMsg(*cfd, resp, sizeof(rbuf), NULL) < 0) { return (errno); } /** * The following is available about the node: * ninfo->name (string) * ninfo->type (string) * ninfo->id (u_int32_t) * ninfo->hooks (u_int32_t) (count of hooks) * check it is the correct type. and get it's ID for use * with mkpeer later. */ if (strncmp(ninfo->type, NG_ETHER_NODE_TYPE, strlen(NG_ETHER_NODE_TYPE)) != 0) { return (EPROTOTYPE); } sprintf(source_ID, "[%08x]:", ninfo->id); /* * look for a hook already attached. */ for (k = 0; k < ninfo->hooks; k++) { /** * The following are available about each hook. * link->ourhook (string) * link->peerhook (string) * peer->name (string) * peer->type (string) * peer->id (u_int32_t) * peer->hooks (u_int32_t) */ link = &hlist->link[k]; peer = &hlist->link[k].nodeinfo; /* Ignore debug hooks */ if (strcmp("debug", link->ourhook) == 0) continue; /* If the orphans hook is attached, use that */ if (strcmp(NG_ETHER_HOOK_ORPHAN, link->ourhook) == 0) { break; } /* the other option is the 'divert' hook */ if (strcmp("NG_ETHER_HOOK_DIVERT", link->ourhook) == 0) { break; } } /* * See if we found a hook there. */ if (k < ninfo->hooks) { if (strcmp(peer->type, NG_PPPOE_NODE_TYPE) == 0) { /* * If it's a type PPPoE, we skip making one * ourself, but we continue, using * the existing one. */ sprintf(pppoe_node_name, "[%08x]:", peer->id); } else { /* * There is already someone hogging the data, * return an error. Some day we'll try * daisy-chaining.. */ return (EBUSY); } } else { /* * Try make a node of type PPPoE against node "ID" * On hook NG_ETHER_HOOK_ORPHAN. */ snprintf(mkp.type, sizeof(mkp.type), "%s", NG_PPPOE_NODE_TYPE); snprintf(mkp.ourhook, sizeof(mkp.ourhook), "%s", NG_ETHER_HOOK_ORPHAN); snprintf(mkp.peerhook, sizeof(mkp.peerhook), "%s", NG_PPPOE_HOOK_ETHERNET); /* Send message */ if (NgSendMsg(*cfd, source_ID, NGM_GENERIC_COOKIE, NGM_MKPEER, &mkp, sizeof(mkp)) < 0) { return (errno); } /* * Work out a name for the new node. */ sprintf(pppoe_node_name, "%s:%s", source_ID, NG_ETHER_HOOK_ORPHAN); } /* * We now have a PPPoE node attached to the Ethernet * card. The Ethernet is addressed as ethername: The PPPoE * node is addressed as pppoe_node_name: attach to it. * Connect socket node to specified node Use the same hook * name on both ends of the link. */ snprintf(ngc.path, sizeof(ngc.path), "%s", pppoe_node_name); snprintf(ngc.ourhook, sizeof(ngc.ourhook), "%s", sessname); snprintf(ngc.peerhook, sizeof(ngc.peerhook), "%s", sessname); if (NgSendMsg(*cfd, ".:", NGM_GENERIC_COOKIE, NGM_CONNECT, &ngc, sizeof(ngc)) < 0) { return (errno); } #ifdef NONSTANDARD /* * In some cases we are speaking to 3Com hardware, so * configure node to non-standard mode. */ if (NgSendMsg(*cfd, ngc.path, NGM_PPPOE_COOKIE, NGM_PPPOE_SETMODE, NG_PPPOE_NONSTANDARD, strlen(NG_PPPOE_NONSTANDARD) + 1) == -1) { return (errno); } #endif /* * Send it a message telling it to start up. */ bzero(&message, sizeof(message)); snprintf(message.idata.hook, sizeof(message.idata.hook), "%s", sessname); if (service == NULL) { message.idata.data_len = 0; } else { snprintf(message.idata.data, sizeof(message.idata.data), "%s", service); message.idata.data_len = strlen(service); } /* Tell session/hook to start up as a client */ if (NgSendMsg(*cfd, ngc.path, NGM_PPPOE_COOKIE, NGM_PPPOE_CONNECT, &message.idata, sizeof(message.idata) + message.idata.data_len) < 0) { return (errno); } return (0); } .Ed .Sh SEE ALSO .Xr netgraph 3 , .Xr netgraph 4 , .Xr ng_ether 4 , .Xr ng_ppp 4 , .Xr ng_socket 4 , .Xr ngctl 8 , .Xr ppp 8 .Rs .%A L. Mamakos .%A K. Lidl .%A J. Evarts .%A D. Carrel .%A D. Simone .%A R. Wheeler .%T "A Method for transmitting PPP over Ethernet (PPPoE)" .%O RFC 2516 .Re .Sh HISTORY The .Nm node type was implemented in .Fx 4.0 . .Sh AUTHORS .An Julian Elischer Aq julian@FreeBSD.org Index: head/share/man/man4/pty.4 =================================================================== --- head/share/man/man4/pty.4 (revision 162403) +++ head/share/man/man4/pty.4 (revision 162404) @@ -1,229 +1,242 @@ .\" Copyright (c) 1983, 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. .\" .\" @(#)pty.4 8.2 (Berkeley) 11/30/93 .\" $FreeBSD$ .\" .Dd November 30, 1993 .Dt PTY 4 .Os .Sh NAME .Nm pty .Nd pseudo terminal driver .Sh SYNOPSIS .Cd "device pty" .Sh DESCRIPTION The .Nm driver provides support for a device-pair termed a .Em pseudo terminal . A pseudo terminal is a pair of character devices, a .Em master device and a .Em slave device. The slave device provides to a process an interface identical to that described in .Xr tty 4 . However, whereas all other devices which provide the interface described in .Xr tty 4 have a hardware device of some sort behind them, the slave device has, instead, another process manipulating it through the master half of the pseudo terminal. That is, anything written on the master device is given to the slave device as input and anything written on the slave device is presented as input on the master device. .Pp The following .Xr ioctl 2 calls apply only to pseudo terminals: .Bl -tag -width TIOCREMOTE .It Dv TIOCSTOP Stops output to a terminal (e.g.\& like typing .Ql ^S ) . Takes no parameter. .It Dv TIOCSTART Restarts output (stopped by .Dv TIOCSTOP or by typing .Ql ^S ) . Takes no parameter. .It Dv TIOCPKT Enable/disable .Em packet mode. Packet mode is enabled by specifying (by reference) a nonzero parameter and disabled by specifying (by reference) a zero parameter. When applied to the master side of a pseudo terminal, each subsequent .Xr read 2 from the terminal will return data written on the slave part of the pseudo terminal preceded by a zero byte (symbolically defined as .Dv TIOCPKT_DATA ) , or a single byte reflecting control status information. In the latter case, the byte is an inclusive-or of zero or more of the bits: .Bl -tag -width TIOCPKT_FLUSHWRITE .It Dv TIOCPKT_FLUSHREAD whenever the read queue for the terminal is flushed. .It Dv TIOCPKT_FLUSHWRITE whenever the write queue for the terminal is flushed. .It Dv TIOCPKT_STOP whenever output to the terminal is stopped a la .Ql ^S . .It Dv TIOCPKT_START whenever output to the terminal is restarted. .It Dv TIOCPKT_DOSTOP whenever .Em t_stopc is .Ql ^S and .Em t_startc is .Ql ^Q . .It Dv TIOCPKT_NOSTOP whenever the start and stop characters are not .Ql ^S/^Q . .Pp While this mode is in use, the presence of control status information to be read from the master side may be detected by a .Xr select 2 for exceptional conditions. .Pp This mode is used by .Xr rlogin 1 and .Xr rlogind 8 to implement a remote-echoed, locally .Ql ^S/^Q flow-controlled remote login with proper back-flushing of output; it can be used by other similar programs. .El .It Dv TIOCUCNTL Enable/disable a mode that allows a small number of simple user .Xr ioctl 2 commands to be passed through the pseudo-terminal, using a protocol similar to that of .Dv TIOCPKT . The .Dv TIOCUCNTL and .Dv TIOCPKT modes are mutually exclusive. This mode is enabled from the master side of a pseudo terminal by specifying (by reference) a nonzero parameter and disabled by specifying (by reference) a zero parameter. Each subsequent .Xr read 2 from the master side will return data written on the slave part of the pseudo terminal preceded by a zero byte, or a single byte reflecting a user control operation on the slave side. A user control command consists of a special .Xr ioctl 2 operation with no data; the command is given as .Dv UIOCCMD Ns (n) , where .Ar n is a number in the range 1-255. The operation value .Ar n will be received as a single byte on the next .Xr read 2 from the master side. The .Xr ioctl 2 .Dv UIOCCMD Ns (0) is a no-op that may be used to probe for the existence of this facility. As with .Dv TIOCPKT mode, command operations may be detected with a .Xr select 2 for exceptional conditions. .El - -There is currently two pty systems available : the original BSD pty, and a +.Pp +There is currently two +.Nm +systems available: the original +.Bx Nm , +and a SysVR4 pts-like implementation. -You can switch between the two implementations by setting the +It is possible to switch between the two implementations by setting the .Va kern.pts.enable -sysctl. Setting it to 0 will use the BSD pty, to non-zero the pts -implementation. It defaults to 0. -You can set the maximum number of ptys which can be allocated at the same time -with the +sysctl. +Setting it to 0 will use the +.Bx Nm , +to non-zero the pts implementation. +It defaults to 0. +It is possible to set the maximum number of ptys +which can be allocated at the same time with the .Va kern.pts.max -sysctl. It defaults to 1000. +sysctl. +It defaults to 1000. It is not recommanded to use more than 1000 pseudo-terminals, as all software which use .Xr utmp 5 will not be able to handle pseudo-terminals with number superior to 999. - -The pts implementation also supports the +.Pp +The pts implementation also supports the .Dv TIOCGPTN .Xr ioctl 2 -call, which takes a pointer to an unsigned int as a parameter and provides the +call, which takes a pointer to an +.Vt "unsigned int" +as a parameter and provides the number of the pty. - .Sh FILES -.Bl -tag -width /dev/tty[p-sP-S][0-9a-v]x -compact -The files used by the BSD pseudo terminals implementation are : +The files used by the +.Bx +pseudo terminals implementation are: +.Pp +.Bl -tag -width ".Pa /dev/tty[p-sP-S][0-9a-v]" -compact .It Pa /dev/pty[p-sP-S][0-9a-v] master pseudo terminals .It Pa /dev/tty[p-sP-S][0-9a-v] slave pseudo terminals - .El -The files used by the pts implementation are : -.Bl -tag -width /dev/pts/[num]x -compact +.Pp +The files used by the pts implementation are: +.Pp +.Bl -tag -width ".Pa /dev/pts/[num]" -compact .It Pa /dev/ptmx control device, returns a file descriptor to a new master pseudo terminal when opened. .It Pa /dev/pty[num] master pseudo terminals .It Pa /dev/pts/[num] slave pseudo terminals .El .Sh DIAGNOSTICS None. .Sh SEE ALSO .Xr tty 4 .Sh HISTORY The .Nm driver appeared in .Bx 4.2 . Index: head/share/man/man4/ral.4 =================================================================== --- head/share/man/man4/ral.4 (revision 162403) +++ head/share/man/man4/ral.4 (revision 162404) @@ -1,224 +1,224 @@ .\" Copyright (c) 2005, 2006 .\" Damien Bergamini .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .\" $FreeBSD$ .\" -.Dd March 05, 2006 +.Dd March 5, 2006 .Os .Dt RAL 4 .Sh NAME .Nm ral .Nd "Ralink Technology IEEE 802.11 wireless network driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device ral" .Cd "device wlan" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent if_ral_load="YES" .Ed .Sh DESCRIPTION The .Nm driver supports PCI/CardBus wireless adapters based on the Ralink Technology RT2500, RT2501, and RT2600 chipsets. .Pp The RT2500 chipset is the first generation of 802.11b/g adapters from Ralink. It consists of two integrated chips, a RT2560 MAC/BBP and a RT2525 radio transceiver. .Pp The RT2501 chipset is the second generation of 802.11b/g adapters from Ralink. It consists of two integrated chips, a RT2561 MAC/BBP and a RT2527 radio transceiver. This chipset provides support for the IEEE 802.11e standard with multiple hardware transmission queues and allows scatter/gather for efficient DMA operations. .Pp The RT2600 chipset consists of two integrated chips, a RT2661 MAC/BBP and a RT2529 radio transceiver. This chipset uses the MIMO (multiple-input multiple-output) technology with multiple antennas to extend the operating range of the adapter and to achieve higher throughput. MIMO is the basis of the forthcoming IEEE 802.11n standard. .Pp The transmit speed is user-selectable or can be adapted automatically by the driver depending on the received signal strength and on the number of hardware transmission retries. .Sh HARDWARE The .Nm driver supports the following adapters: .Pp .Bl -column -compact ".Li Atlantis Land A02-PCM-W54" "RT2561S" "CardBus" .It Em Card Ta Em MAC/BBP Ta Em Bus .It Li "A-Link WL54H" Ta RT2560 Ta PCI .It Li "A-Link WL54PC" Ta RT2560 Ta CardBus .It Li "AirLink101 AWLC5025" Ta RT2661 Ta CardBus .It Li "AirLink101 AWLH5025" Ta RT2661 Ta PCI .It Li "Amigo AWI-914W" Ta RT2560 Ta CardBus .It Li "Amigo AWI-922W" Ta RT2560 Ta mini-PCI .It Li "Amigo AWI-926W" Ta RT2560 Ta PCI .It Li "AMIT WL531C" Ta RT2560 Ta CardBus .It Li "AMIT WL531P" Ta RT2560 Ta PCI .It Li "AOpen AOI-831" Ta RT2560 Ta PCI .It Li "ASUS WL-107G" Ta RT2560 Ta CardBus .It Li "ASUS WL-130g" Ta RT2560 Ta PCI .It Li "Atlantis Land A02-PCI-W54" Ta RT2560 Ta PCI .It Li "Atlantis Land A02-PCM-W54" Ta RT2560 Ta CardBus .It Li "Belkin F5D7000 v3" Ta RT2560 Ta PCI .It Li "Belkin F5D7010 v2" Ta RT2560 Ta CardBus .It Li "Billionton MIWLGRL" Ta RT2560 Ta mini-PCI .It Li "Canyon CN-WF511" Ta RT2560 Ta PCI .It Li "Canyon CN-WF513" Ta RT2560 Ta CardBus .It Li "CC&C WL-2102" Ta RT2560 Ta CardBus .It Li "CNet CWC-854" Ta RT2560 Ta CardBus .It Li "CNet CWP-854" Ta RT2560 Ta PCI .It Li "Compex WL54G" Ta RT2560 Ta CardBus .It Li "Compex WLP54G" Ta RT2560 Ta PCI .It Li "Conceptronic C54RC" Ta RT2560 Ta CardBus .It Li "Conceptronic C54Ri" Ta RT2560 Ta PCI .It Li "Digitus DN-7001G-RA" Ta RT2560 Ta CardBus .It Li "Digitus DN-7006G-RA" Ta RT2560 Ta PCI .It Li "E-Tech WGPC02" Ta RT2560 Ta CardBus .It Li "E-Tech WGPI02" Ta RT2560 Ta PCI .It Li "Edimax EW-7108PCg" Ta RT2560 Ta CardBus .It Li "Edimax EW-7128g" Ta RT2560 Ta PCI .It Li "Eminent EM3036" Ta RT2560 Ta CardBus .It Li "Eminent EM3037" Ta RT2560 Ta PCI .It Li "Encore ENLWI-G-RLAM" Ta RT2560 Ta PCI .It Li "Encore ENPWI-G-RLAM" Ta RT2560 Ta CardBus .It Li "Fiberline WL-400P" Ta RT2560 Ta PCI .It Li "Fibreline WL-400X" Ta RT2560 Ta CardBus .It Li "Gigabyte GN-WI01GS" Ta RT2561S Ta mini-PCI .It Li "Gigabyte GN-WIKG" Ta RT2560 Ta mini-PCI .It Li "Gigabyte GN-WMKG" Ta RT2560 Ta CardBus .It Li "Gigabyte GN-WP01GS" Ta RT2561S Ta PCI .It Li "Gigabyte GN-WPKG" Ta RT2560 Ta PCI .It Li "Hawking HWC54GR" Ta RT2560 Ta CardBus .It Li "Hawking HWP54GR" Ta RT2560 Ta PCI .It Li "iNexQ CR054g-009 (R03)" Ta RT2560 Ta PCI .It Li "JAHT WN-4054P" Ta RT2560 Ta CardBus .It Li "JAHT WN-4054PCI" Ta RT2560 Ta PCI .It Li "LevelOne WNC-0301 v2" Ta RT2560 Ta PCI .It Li "LevelOne WPC-0301 v2" Ta RT2560 Ta CardBus .It Li "Linksys WMP54G v4" Ta RT2560 Ta PCI .It Li "Micronet SP906GK" Ta RT2560 Ta PCI .It Li "Micronet SP908GK V3" Ta RT2560 Ta CardBus .It Li "Minitar MN54GCB-R" Ta RT2560 Ta CardBus .It Li "Minitar MN54GPC-R" Ta RT2560 Ta PCI .It Li "MSI CB54G2" Ta RT2560 Ta CardBus .It Li "MSI MP54G2" Ta RT2560 Ta mini-PCI .It Li "MSI PC54G2" Ta RT2560 Ta PCI .It Li "OvisLink EVO-W54PCI" Ta RT2560 Ta PCI .It Li "PheeNet HWL-PCIG/RA" Ta RT2560 Ta PCI .It Li "Pro-Nets CB80211G" Ta RT2560 Ta CardBus .It Li "Pro-Nets PC80211G" Ta RT2560 Ta PCI .It Li "Repotec RP-WB7108" Ta RT2560 Ta CardBus .It Li "Repotec RP-WP0854" Ta RT2560 Ta PCI .It Li "SATech SN-54C" Ta RT2560 Ta CardBus .It Li "SATech SN-54P" Ta RT2560 Ta PCI .It Li "Sitecom WL-112" Ta RT2560 Ta CardBus .It Li "Sitecom WL-115" Ta RT2560 Ta PCI .It Li "SMC SMCWCB-GM" Ta RT2661 Ta CardBus .It Li "SMC SMCWPCI-GM" Ta RT2661 Ta PCI .It Li "SparkLAN WL-685R" Ta RT2560 Ta CardBus .It Li "Surecom EP-9321-g" Ta RT2560 Ta PCI .It Li "Surecom EP-9321-g1" Ta RT2560 Ta PCI .It Li "Surecom EP-9428-g" Ta RT2560 Ta CardBus .It Li "Sweex LC500050" Ta RT2560 Ta CardBus .It Li "Sweex LC700030" Ta RT2560 Ta PCI .It Li "TekComm NE-9321-g" Ta RT2560 Ta PCI .It Li "TekComm NE-9428-g" Ta RT2560 Ta CardBus .It Li "Unex CR054g-R02" Ta RT2560 Ta PCI .It Li "Unex MR054g-R02" Ta RT2560 Ta CardBus .It Li "Zinwell ZWX-G160" Ta RT2560 Ta CardBus .It Li "Zinwell ZWX-G360" Ta RT2560 Ta mini-PCI .It Li "Zinwell ZWX-G361" Ta RT2560 Ta PCI .It Li "Zonet ZEW1500" Ta RT2560 Ta CardBus .It Li "Zonet ZEW1600" Ta RT2560 Ta PCI .El .Pp An up to date list can be found at .Pa http://damien.bergamini.free.fr/ral/list.html . .Sh EXAMPLES Join an existing BSS network (i.e., connect to an access point): .Pp .Dl "ifconfig ral0 inet 192.168.0.20 netmask 0xffffff00" .Pp Join a specific BSS network with network name .Dq Li my_net : .Pp .Dl "ifconfig ral0 inet 192.168.0.20 netmask 0xffffff00 ssid my_net" .Pp Join a specific BSS network with 40-bit WEP encryption: .Bd -literal -offset indent ifconfig ral0 inet 192.168.0.20 netmask 0xffffff00 ssid my_net \e wepmode on wepkey 0x1234567890 weptxkey 1 .Ed .Pp Join a specific BSS network with 104-bit WEP encryption: .Bd -literal -offset indent ifconfig ral0 inet 192.168.0.20 netmask 0xffffff00 ssid my_net \e wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 .Ed .Sh DIAGNOSTICS .Bl -diag .It "ral%d: could not load 8051 microcode" An error occurred while attempting to upload the microcode to the onboard 8051 microcontroller unit. .It "ral%d: timeout waiting for MCU to initialize" The onboard 8051 microcontroller unit failed to initialize in time. .It "ral%d: device timeout" A frame dispatched to the hardware for transmission did not complete in time. The driver will reset the hardware. This should not happen. .El .Sh SEE ALSO .Xr arp 4 , .Xr cardbus 4 , .Xr netintro 4 , .Xr pci 4 , .Xr wlan 4 , .Xr ifconfig 8 .Rs .%T "Ralink Technology" .%O http://www.ralinktech.com/ .Re .Sh HISTORY The .Nm driver first appeared in .Ox 3.7 . .Sh CAVEATS PCI .Nm adapters seem to require a PCI 2.2 compliant motherboard and will likely not work with PCI 2.1 only motherboard. .Pp The .Nm driver does not implement frame aggregation. .Sh AUTHORS The .Nm driver was written by .An Damien Bergamini Aq damien@FreeBSD.org . Index: head/share/man/man4/random.4 =================================================================== --- head/share/man/man4/random.4 (revision 162403) +++ head/share/man/man4/random.4 (revision 162404) @@ -1,327 +1,327 @@ .\" Copyright (c) 2001 Mark R V Murray. 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 19, 2006 .Dt RANDOM 4 .Os .Sh NAME .Nm random .Nd the entropy device .Sh SYNOPSIS .Cd "device random" .Sh DESCRIPTION The .Nm device returns an endless supply of random bytes when read. It also accepts and reads data as any ordinary (and willing) file, but discards data written to it. The device will probe for certain hardware entropy sources, and use these in preference to the fallback, which is a generator implemented in software. .Pp If the device is using the software generator, writing data to .Nm would perturb the internal state. This perturbation of the internal state is the only userland method of introducing extra entropy into the device. If the writer has superuser privilege, then closing the device after writing will make the software generator reseed itself. This can be used for extra security, as it immediately introduces any/all new entropy into the PRNG. The hardware generators will generate sufficient quantities of entropy, and will therefore ignore user-supplied input. The software .Nm device may be controlled with .Xr sysctl 8 . .Pp To see the current settings of the software .Nm device, use the command line: .Pp .Dl sysctl kern.random .Pp which results in something like: .Pp .Bd -literal -offset indent kern.random.sys.seeded: 1 kern.random.sys.harvest.ethernet: 1 kern.random.sys.harvest.point_to_point: 1 kern.random.sys.harvest.interrupt: 1 kern.random.sys.harvest.swi: 0 kern.random.yarrow.gengateinterval: 10 kern.random.yarrow.bins: 10 kern.random.yarrow.fastthresh: 192 kern.random.yarrow.slowthresh: 256 kern.random.yarrow.slowoverthresh: 2 .Ed .Pp (These would not be seen if a hardware generator is present.) .Pp All settings are read/write. .Pp The .Va kern.random.sys.seeded variable indicates whether or not the .Nm device is in an acceptably secure state as a result of reseeding. If set to 0, the device will block (on read) until the next reseed (which can be from an explicit write, or as a result of entropy harvesting). A reseed will set the value to 1 (non-blocking). .Pp The .Va kern.random.sys.harvest.ethernet variable is used to select LAN traffic as an entropy source. A 0 (zero) value means that LAN traffic is not considered as an entropy source. Set the variable to 1 (one) if you wish to use LAN traffic for entropy harvesting. .Pp The .Va kern.random.sys.harvest.point_to_point variable is used to select serial line traffic as an entropy source. (Serial line traffic includes PPP, SLIP and all tun0 traffic.) A 0 (zero) value means such traffic is not considered as an entropy source. Set the variable to 1 (one) if you wish to use it for entropy harvesting. .Pp The .Va kern.random.sys.harvest.interrupt variable is used to select hardware interrupts as an entropy source. A 0 (zero) value means hardware interrupts are not considered as an entropy source. Set the variable to 1 (one) if you wish to use them for entropy harvesting. -All hardware interrupt harvesting is setup by the +All hardware interrupt harvesting is set up by the individual device drivers. .Pp The .Va kern.random.sys.harvest.swi variable is used to select software interrupts as an entropy source. A 0 (zero) value means software interrupts are not considered as an entropy source. Set the variable to 1 (one) if you wish to use them for entropy harvesting. .Pp The other variables are explained in the paper describing the .Em Yarrow algorithm at .Pa http://www.counterpane.com/yarrow.html . .Pp These variables are all limited in terms of the values they may contain: .Bl -tag -width "kern.random.yarrow.gengateinterval" -compact -offset indent .It Va kern.random.yarrow.gengateinterval .Bq 4..64 .It Va kern.random.yarrow.bins .Bq 2..16 .It Va kern.random.yarrow.fastthresh .Bq 64..256 .It Va kern.random.yarrow.slowthresh .Bq 64..256 .It Va kern.random.yarrow.slowoverthresh .Bq 1..5 .El .Pp Internal .Xr sysctl 3 handlers force the above variables into the stated ranges. .Sh RANDOMNESS The use of randomness in the field of computing is a rather subtle issue because randomness means different things to different people. Consider generating a password randomly, simulating a coin tossing experiment or choosing a random back-off period when a server does not respond. Each of these tasks requires random numbers, but the random numbers in each case have different requirements. .Pp Generation of passwords, session keys and the like requires cryptographic randomness. A cryptographic random number generator should be designed so that its output is difficult to guess, even if a lot of auxiliary information is known (such as when it was seeded, subsequent or previous output, and so on). On .Fx , seeding for cryptographic random number generators is provided by the .Nm device, which provides real randomness. The .Xr arc4random 3 library call provides a pseudo-random sequence which is generally reckoned to be suitable for simple cryptographic use. The OpenSSL library also provides functions for managing randomness via functions such as .Xr RAND_bytes 3 and .Xr RAND_add 3 . Note that OpenSSL uses the .Nm device for seeding automatically. .Pp Randomness for simulation is required in engineering or scientific software and games. The first requirement of these applications is that the random numbers produced conform to some well-known, usually uniform, distribution. The sequence of numbers should also appear numerically uncorrelated, as simulation often assumes independence of its random inputs. Often it is desirable to reproduce the results of a simulation exactly, so that if the generator is seeded in the same way, it should produce the same results. A peripheral concern for simulation is the speed of a random number generator. .Pp Another issue in simulation is the size of the state associated with the random number generator, and how frequently it repeats itself. For example, a program which shuffles a pack of cards should have 52!\& possible outputs, which requires the random number generator to have 52!\& starting states. This means the seed should have at least log_2(52!) ~ 226 bits of state if the program is to stand a chance of outputting all possible sequences, and the program needs some unbiased way of generating these bits. Again, the .Nm device could be used for seeding here, but in practice, smaller seeds are usually considered acceptable. .Pp .Fx provides two families of functions which are considered suitable for simulation. The .Xr random 3 family of functions provides a random integer between 0 to .if t 2\u\s731\s10\d\(mi1. .if n (2**31)\(mi1. The functions .Xr srandom 3 , .Xr initstate 3 and .Xr setstate 3 are provided for deterministically setting the state of the generator and the function .Xr srandomdev 3 is provided for setting the state via the .Nm device. The .Xr drand48 3 family of functions are also provided, which provide random floating point numbers in various ranges. .Pp Randomness that is used for collision avoidance (for example, in certain network protocols) has slightly different semantics again. It is usually expected that the numbers will be uniform, as this produces the lowest chances of collision. Here again, the seeding of the generator is very important, as it is required that different instances of the generator produce independent sequences. However, the guessability or reproducibility of the sequence is unimportant, unlike the previous cases. .Pp One final consideration for the seeding of random number generators is a bootstrapping problem. In some cases, it may be difficult to find enough randomness to seed a random number generator until a system is fully operational, but the system requires random numbers to become fully operational. There is no substitute for careful thought here, but the .Fx .Nm device, which is based on the Yarrow system, should be of some help in this area. .Pp .Fx does also provide the traditional .Xr rand 3 library call, for compatibility purposes. However, it is known to be poor for simulation and absolutely unsuitable for cryptographic purposes, so its use is discouraged. .Sh FILES .Bl -tag -width ".Pa /dev/random" .It Pa /dev/random .El .Sh SEE ALSO .Xr arc4random 3 , .Xr drand48 3 , .Xr rand 3 , .Xr RAND_add 3 , .Xr RAND_bytes 3 , .Xr random 3 , .Xr sysctl 8 .Sh HISTORY A .Nm device appeared in .Fx 2.2 . The early version was taken from Theodore Ts'o's entropy driver for Linux. The current software implementation, introduced in .Fx 5.0 , is a complete rewrite by .An Mark R V Murray , and is an implementation of the .Em Yarrow algorithm by Bruce Schneier, .Em et al . The only hardware implementation currently is for the .Tn VIA C3 Nehemiah (stepping 3 or greater) CPU. More will be added in the future. .Pp The author gratefully acknowledges significant assistance from VIA Technologies, Inc. Index: head/share/man/man4/smp.4 =================================================================== --- head/share/man/man4/smp.4 (revision 162403) +++ head/share/man/man4/smp.4 (revision 162404) @@ -1,109 +1,109 @@ .\" Copyright (c) 1997 .\" Steve Passe . 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. The name of the developer 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 December 17, 2004 .Dt SMP 4 .Os .Sh NAME .Nm SMP .Nd description of the FreeBSD Symmetric Multi-Processor kernel .Sh SYNOPSIS .Cd options SMP .Sh DESCRIPTION The .Nm kernel implements symmetric multi-processor support. .Sh COMPATIBILITY Support for multi-processor systems is present for all Tier-1 architectures on .Fx . Currently, this includes amd64, i386, ia64, and sparc64. Support is enabled using .Cd options SMP . It is permissible to use the SMP kernel configuration on non-SMP equipped motherboards. .Sh I386 NOTES For i386 systems, the .Nm kernel supports motherboards that follow the Intel MP specification, version 1.4. In addition to .Cd options SMP , i386 also requires .Cd device apic . The .Xr mptable 1 command may be used to view the status of multi-processor support. .Pp The number of CPUs detected by the system is available in the read-only sysctl variable .Va hw.ncpu . .Pp .Fx allows specific CPUs on a multi-processor system to be disabled. The sysctl variable .Va machdep.hlt_cpus is an integer bitmask denoting CPUs to halt, counting from 0. Setting a bit to 1 will result in the corresponding CPU being disabled. .Pp .Fx supports hyperthreading on Intel CPU's on the i386 platform. Since using logical CPUs can cause performance penalties under certain loads, the logical CPUs can be disabled by setting the .Va machdep.hlt_logical_cpus sysctl to one. .Sh SEE ALSO .Xr mptable 1 , .Xr sysctl 8 , .Xr condvar 9 , .Xr msleep 9 , .Xr mtx_pool 9 , .Xr mutex 9 , .Xr sema 9 , .Xr sx 9 .Sh HISTORY The .Nm kernel's early history is not (properly) recorded. It was developed in a separate CVS branch until April 26, 1997, at which point it was merged into 3.0-current. By this date 3.0-current had already been merged with Lite2 kernel code. .Pp .Fx 5.0 introduced support for a host of new synchronization primitives, and a move towards fine-grained kernel locking rather than reliance on a Giant kernel lock. The SMPng Project relied heavily on the support of BSDi, who provided reference source code from the fine-grained SMP implementation found in .Bsx . .Pp .Fx 5.0 -also introduced support for SMP on the ia64, and sparc64 architectures. +also introduced support for SMP on the ia64 and sparc64 architectures. .Sh AUTHORS .An Steve Passe Aq fsmp@FreeBSD.org Index: head/share/man/man4/uart.4 =================================================================== --- head/share/man/man4/uart.4 (revision 162403) +++ head/share/man/man4/uart.4 (revision 162404) @@ -1,158 +1,158 @@ .\" .\" Copyright (c) 2003 Marcel Moolenaar .\" 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 March 29, 2006 .Dt UART 4 .Os .\" .Sh NAME .Nm uart .Nd driver for Universal Asynchronous Receiver/Transmitter (UART) devices .\" .Sh SYNOPSIS .Cd "device uart" .Pp .Cd "device puc" .Cd "device uart" .Pp .Cd "device scc" .Cd "device uart" .\" .Sh DESCRIPTION The .Nm device driver provides support for various classes of UARTs implementing the EIA RS-232C (CCITT V.24) serial communications interface. Each such interface is controlled by a separate and independent instance of the .Nm driver. The primary support for devices that contain multiple serial interfaces or that contain other functionality besides one or more serial interfaces is provided by the .Xr puc 4 , or .Xr scc 4 device drivers. However, the serial interfaces of those devices that are managed by the .Xr puc 4 , or .Xr scc 4 driver are each independently controlled by the .Nm driver. As such, the .Xr puc 4 , or .Xr scc 4 driver provides umbrella functionality for the .Nm driver and hides the complexities that are inherent when elementary components are packaged together. .Pp The .Nm driver has a modular design to allow it to be used on differing hardware and for various purposes. In the following sections the components are discussed in detail. Options are described in the section that covers the component to which each option applies. .\" .Ss CORE COMPONENT At the heart of the .Nm driver is the core component. It contains the bus attachments and the low-level interrupt handler. .\" .Ss HARDWARE DRIVERS The core component and the kernel interfaces talk to the hardware through the hardware interface. This interface serves as an abstraction of the hardware and allows varying UARTs to be used for serial communications. .\" .Ss SYSTEM DEVICES System devices are UARTs that have a special purpose by way of hardware design or software setup. For example, Sun UltraSparc machines use UARTs as their keyboard interface. Such an UART cannot be used for general purpose communications. Likewise, when the kernel is configured for a serial console, the corresponding UART will in turn be a system device so that the kernel can output boot messages early on in the boot process. .\" .Ss KERNEL INTERFACES The last but not least of the components is the kernel interface. This component ultimately determines how the UART is made visible to the kernel in particular and to users in general. The default kernel interface is the TTY interface. This allows the UART to be used for terminals, modems and serial line IP applications. System devices, with the notable exception of serial consoles, generally have specialized kernel interfaces. .\" .Sh HARDWARE The .Nm driver supports the following classes of UARTs: .Pp .Bl -bullet -compact .It NS8250: standard hardware based on the 8250, 16450, 16550, 16650, 16750 or the 16950 UARTs. .It SCC: serial communications controllers supported by the .Xr scc 4 device driver. .El .\" .Sh FILES -.Bl -tag -width /dev/ttyu?.init -compact +.Bl -tag -width ".Pa /dev/ttyu?.init" -compact .It Pa /dev/ttyu? for callin ports .It Pa /dev/ttyu?.init .It Pa /dev/ttyu?.lock corresponding callin initial-state and lock-state devices .Pp .It Pa /dev/cuau? for callout ports .It Pa /dev/cuau?.init .It Pa /dev/cuau?.lock corresponding callout initial-state and lock-state devices .El .Sh SEE ALSO .Xr puc 4 , .Xr scc 4 .\" .Sh HISTORY The .Nm device driver first appeared in .Fx 5.2 . .Sh AUTHORS The .Nm device driver and this manual page were written by .An Marcel Moolenaar Aq marcel@xcllnt.net . Index: head/share/man/man4/umass.4 =================================================================== --- head/share/man/man4/umass.4 (revision 162403) +++ head/share/man/man4/umass.4 (revision 162404) @@ -1,244 +1,244 @@ .\" Copyright (c) 1999 .\" Nick Hibma . 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 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 NICK HIBMA 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 NICK HIBMA OR THE VOICES IN HIS 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. .\" .\" $FreeBSD$ .\" .Dd December 17, 2004 .Dt UMASS 4 .Os .Sh NAME .Nm umass .Nd USB Mass Storage Devices driver .Sh SYNOPSIS .Cd "device umass" .Sh DESCRIPTION The .Nm driver provides support for Mass Storage devices that attach to the USB port. .Pp To use the .Nm driver, .Xr usb 4 and one of .Xr uhci 4 or .Xr ohci 4 must be configured in the kernel. Additionally, since .Nm uses the SCSI subsystem and sometimes acts as a SCSI device, it requires .Xr da 4 and .Xr scbus 4 to be included in the kernel. .Sh HARDWARE The .Nm driver supports USB Mass Storage devices, including: .Pp .Bl -bullet -compact .It ADTEC Stick Drive AD-UST32M, 64M, 128M, 256M .It Denno FireWire/USB2 Removable 2.5-inch HDD Case MIFU-25CB20 .It FujiFilm Zip USB Drive ZDR100 USB A .It GREEN HOUSE USB Flash Memory "PicoDrive" GH-UFD32M, 64M, 128M .It IBM 32MB USB Memory Key (P/N 22P5296) .It IBM 256MB USB Drive (MSYSTEM DiskOnKey2) .It IBM ThinkPad USB Portable CD-ROM Drive (P/N 33L5151) .It I-O DATA USB CD/CD-R/CD-RW/DVD-R/DVD-RW/DVD-RAM/DVD-ROM Drive DVR-iUH2 (CDROM, DVD-RAM only) .It I-O DATA USB x6 CD-RW Drive CDRW-i64/USB (CDROM only) .It I-O DATA USB/IEEE1394 Portable HD Drive HDP-i30P/CI, HDP-i40P/CI .It Iomega USB Zip 100/250 drive .It Iomega Zip750 USB2.0 drive .It Keian USB1.1/2.0 3.5-inch HDD Case KU350A .It Kurouto Shikou USB 2.5-inch HDD Case GAWAP2.5PS-USB2.0 .It LaCie P3 HardDrive USB 200GB .It Logitec LDR-H443U2 DVD-RAM/-R/+R/-RW/+RW drive .It Logitec Mobile USB Memory LMC-256UD .It Logitec USB1.1/2.0 HDD Unit SHD-E60U2 .It Logitec USB Double-Speed Floppy Drive LFD-31U2 .It Logitec USB/IEEE1394 DVD-RAM/R/RW Unit LDR-N21FU2 (CDROM only) .It MELCO USB Flash Disk "ClipDrive", RUF-C32M, -C64M, -C128M, -C256M, -C512M .It MELCO USB Flash Disk "PetitDrive", RUF-32M, -64M, -128M, -256Mm .It MELCO USB2.0 Flash Disk "PetitDrive2", RUF-256M/U2, -512M/U2 .It MELCO USB2.0 MO Drive MO-CH640U2 .It Matshita CF-VFDU03 floppy drive .It Merlin SM300 MP3/WMA Player (256Mb) .It Microtech International, Inc.\& USB-SCSI-HD 50 USB to SCSI cable .It Motorola E398 Mobile Phone (TransFlash memory card) .It NOVAC USB2.0 2.5/3.5-inch HDD Case NV-HD351U .It PNY Attache Flash Drive .It Panasonic ("Matshita FDD CF-VFDU03") .It Panasonic KXL-CB20AN Portable DVD-ROM/CD-R/RW .It Panasonic KXL-CB35AN (DVD-ROM & CD-R/RW) .It Panasonic USB2.0 Portable CD-RW Drive KXL-RW40AN (CDROM only) .It Panasonic floppy drive .It -Qware BeatZkey! Pro +Qware BeatZkey!\& Pro .It RATOC Systems USB2.0 Removable HDD Case U2-MDK1, U2-MDK1B .It SanDisk SDDR-31 (Compact Flash) .It SanDisk SDDR-75 (only Compact Flash port works) .It Sitecom CN-300 MultiFlash (MMC/SD, SmartMedia, CF, MemoryStick) .It Sony Portable CD-R/RW Drive CRX10U (CDROM only) .It TEAC Portable USB CD-ROM Unit CD-110PU/210PU .It Time DPA20B MP3 Player (1Gb) .It Trek Thumbdrive 8MB .It VAIO floppy drive (includes Y-E Data Flashbuster-U) .It Y-E Data floppy drive (720/1.44/2.88Mb) .El .Pp Among the supported digital cameras are: .Pp .Bl -bullet -compact .It Asahi Optical (PENTAX) Optio 230 & 330 .El .Sh EXAMPLES .Bd -literal -offset indent device umass device scbus device da device pass .Ed .Pp Add the .Nm driver to the kernel. .Pp .Dl "camcontrol rescan 0" .Pp Rescan a Zip drive that was added after boot. The command above assumes that the Zip drive is on the first SCSI bus in the system. .Bd -literal -offset indent camcontrol rescan 0:0:0 camcontrol rescan 0:0:1 camcontrol rescan 0:0:2 camcontrol rescan 0:0:3 .Ed .Pp Rescan all slots on a multi-slot flash reader, where the slots map to separate LUNs on a single SCSI ID. Typically only the first slot will be enabled at boot time. Again, this assumes that the flash reader is the first SCSI bus in the system. .Bd -literal -offset indent bsdlabel -w da0 zip100 newfs da0c mount -t ufs /dev/da0c /mnt .Ed .Pp Write a disklabel to the Zip drive (see .Xr vpo 4 for the .Xr disktab 5 entry), creates the file system and mounts the new file system on /mnt. .Pp .Dl "newfs_msdos /dev/da0" .Pp Create a new FAT type file system. Care should be taken not to run .Xr newfs 8 on devices that already contain data, as this will result in the information being lost. .Pp Many consumer devices such as digital cameras automatically create .Tn MS-DOS based file systems when storing information such as images and videos. These file systems can be accessed by specifying the file system type as .Cm msdos when using .Xr mount 8 . .Sh SEE ALSO .Xr ehci 4 , .Xr ohci 4 , .Xr uhci 4 , .Xr usb 4 , .Xr vpo 4 , .Xr disktab 5 , .Xr bsdlabel 8 , .Xr camcontrol 8 .\".Sh HISTORY .Sh AUTHORS .An -nosplit The .Nm driver was written by .An MAEKAWA Masahide Aq bishop@rr.iij4u.or.jp and .An Nick Hibma Aq n_hibma@FreeBSD.org . .Pp This manual page was written by .An Nick Hibma Aq n_hibma@FreeBSD.org . Index: head/share/man/man5/devfs.5 =================================================================== --- head/share/man/man5/devfs.5 (revision 162403) +++ head/share/man/man5/devfs.5 (revision 162404) @@ -1,102 +1,102 @@ .\" Copyright (c) 1996 .\" Mike Pritchard . All rights reserved. .\" .\" Copyright (c) 1992, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" All rights reserved. .\" .\" This code is derived from software donated to Berkeley by .\" Jan-Simon Pendry. .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd December 14, 1996 .Dt DEVFS 5 .Os .Sh NAME .Nm devfs .Nd device file system .Sh SYNOPSIS .Bd -literal devfs /dev devfs rw 0 0 .Ed .Sh DESCRIPTION The device file system, or .Nm , provides access to kernel's device namespace in the global file system namespace. The conventional mount point is .Pa /dev . .Pp The file system includes several directories, links, symbolic links and devices, some of which can also be written. In a chroot'ed environment, .Nm can be used to create a new .Pa /dev mount point. .Pp The .Xr mknod 8 tool can be used to recover deleted device entries under .Nm . -.Sh EXAMPLES -To mount a -.Nm -volume located on -.Pa /dev : -.Pp -.Dl "mount -t devfs devfs /dev" .Sh FILES .Bl -tag -width /dev/XXXX -compact .It Pa /dev The normal .Nm mount point. .El +.Sh EXAMPLES +To mount a +.Nm +volume located on +.Pa /dev : +.Pp +.Dl "mount -t devfs devfs /dev" .Sh SEE ALSO .Xr devfs 8 , .Xr mount 8 .Sh HISTORY The .Nm file system first appeared in .Fx 2.0 . The .Nm manual page first appeared in .Fx 2.2 . .Sh AUTHORS The .Nm manual page was written by .An Mike Pritchard Aq mpp@FreeBSD.org . Index: head/share/man/man5/devfs.conf.5 =================================================================== --- head/share/man/man5/devfs.conf.5 (revision 162403) +++ head/share/man/man5/devfs.conf.5 (revision 162404) @@ -1,140 +1,140 @@ .\" Copyright (c) 2004 Roland 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 May 17, 2005 .Dt DEVFS.CONF 5 .Os .Sh NAME .Nm devfs.conf .Nd boot-time devfs configuration information .Sh DESCRIPTION The .Nm file provides an easy way to set ownership and permissions, or create links for devices available at boot. .Pp It does not work for devices plugged in and out after the system is up and running, e.g.\& USB devices. See .Xr devfs.rules 5 for setting ownership and permissions for all device nodes, and .Xr devd.conf 5 for actions to be taken when devices are attached or detached. .Pp Lines starting with a hash sign .Pq Ql # and empty lines are ignored. The lines that specify .Nm rules consist of three parameters separated by whitespace: .Bl -tag -width indent .It Ar action The action to take for the device. The action names are only significant to the first unique character. .It Ar devname The name of the device created by .Xr devfs 5 . .It Ar arg The argument of the .Ar action . .El .Pp The actions currently supported are: .Bl -tag -width indent .It Ic link This action creates a symbolic link named .Ar arg that points to .Ar devname , the name of the device created by .Xr devfs 5 . .It Ic own This action changes the ownership of .Ar devname . The .Ar arg parameter must be in the form of an .Ar owner Ns : Ns Ar group pair, in the same format used by .Xr chown 8 . .It Ic perm This action changes the permissions of .Ar devname . The .Ar arg parameter must be a .Ar mode as explained in .Xr chmod 1 . .El .Sh FILES .Bl -tag -compact .It Pa /etc/devfs.conf .It Pa /usr/share/examples/etc/devfs.conf .El .Sh EXAMPLES To create a .Pa /dev/cdrom link that points to the first .Xr SCSI 4 or .Xr atapicam 4 CD-ROM, the following may be added to .Nm : .Bd -literal -offset indent link cd0 cdrom .Ed .Pp Similarly, to link .Pa /dev/cdrom to the first ATAPI CD-ROM device, the following action may be used: .Bd -literal -offset indent link acd0 cdrom .Ed .Pp To set the owner of a device, the .Ic own action may be specified: .Bd -literal -offset indent own cd0 root:cdrom .Ed .Pp To set the permissions of a device, a .Ic perm action should be used: .Bd -literal -offset indent perm cd0 0660 .Ed .Sh SEE ALSO .Xr chmod 1 , +.Xr devd.conf 5 , .Xr devfs 5 , .Xr devfs.rules 5 , -.Xr devd.conf 5 , .Xr chown 8 .Sh AUTHORS This manual page was written by .An "Roland Smith" Aq rsmith@xs4all.nl . Index: head/share/man/man5/devfs.rules.5 =================================================================== --- head/share/man/man5/devfs.rules.5 (revision 162403) +++ head/share/man/man5/devfs.rules.5 (revision 162404) @@ -1,117 +1,117 @@ .\" Copyright (c) 2004 Roland 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 Jan 30, 2006 +.Dd January 30, 2006 .Dt DEVFS.RULES 5 .Os .Sh NAME .Nm devfs.rules .Nd devfs configuration information .Sh DESCRIPTION The .Nm file provides an easy way to create and apply .Xr devfs 8 rules, even for devices that are not available at boot. .Pp For devices available at boot, see .Xr devfs.conf 5 . .Pp The format of this file is simple. Empty lines and lines beginning with a hash sign .Pq Ql # are ignored. A line between brackets denotes the start of a ruleset. In the brackets should be the name of the ruleset and its number, separated by an equal sign. .Pp Other lines are rule specifications as documented in .Xr devfs 8 , in the section .Sx "Rule Specification" . These lines are prepended with .Dq Li rule and are passed to .Xr devfs 8 by the startup scripts of the system. It is important to put path elements that contain .Xr glob 3 special characters between quotes. .Pp Rulesets should have a unique name and number. .Pp All rules that follow a ruleset declaration belong to that ruleset, until a new ruleset is started. .Pp One custom ruleset has to be enabled in .Pa /etc/rc.conf , otherwise it will not be applied to the .Pa /dev file system by the default system startup process. For example, to enable a .Dq Li localrules ruleset for the .Pa /dev file system, you would have to use something like this in your .Pa rc.conf file: .Bd -literal -offset indent devfs_system_ruleset="localrules" .Ed .Sh FILES .Bl -tag -compact .It Pa /etc/devfs.rules .It Pa /etc/defaults/devfs.rules .El .Sh EXAMPLES To make all the partitions of .Xr da 4 devices readable and writable by their owner and the .Dq Li usb group, the following rule may be used: .Pp .Dl "[localrules=10]" .Dl "add path 'da*s*' mode 0660 group usb" .Pp The first line declares and starts a new ruleset, with the name .Va localrules and the number 10. .Pp To make all the .Xr uscanner 4 devices accessible to their owner and the .Dq Li usb group, a similar rule may be used: .Pp .Dl "add path 'uscanner*' mode 0660 group usb" .Sh SEE ALSO .Xr glob 3 , .Xr devfs 5 , .Xr devfs.conf 5 , .Xr devfs 8 .Sh AUTHORS This manual page was written by .An "Roland Smith" Aq rsmith@xs4all.nl . Index: head/share/man/man5/linprocfs.5 =================================================================== --- head/share/man/man5/linprocfs.5 (revision 162403) +++ head/share/man/man5/linprocfs.5 (revision 162404) @@ -1,99 +1,98 @@ .\" $FreeBSD$ .\" Written by Garrett Wollman .\" This file is in the public domain. .\" .Dd August 10, 1994 .Dt LINPROCFS 5 .Os .Sh NAME .Nm linprocfs .Nd Linux process file system .Sh SYNOPSIS .Bd -literal linproc /compat/linux/proc linprocfs rw 0 0 .Ed -.Pp .Sh DESCRIPTION The Linux process file system, or .Nm , emulates a subset of Linux' process file system and is required for the complete operation of some Linux binaries. .Pp The .Nm provides a two-level view of process space. At the highest level, processes themselves are named, according to their process ids in decimal, with no leading zeros. There is also a special node called .Pa self which always refers to the process making the lookup request. .Pp Each node is a directory containing several files: .Bl -tag -width status .It Pa exe A reference to the vnode from which the process text was read. This can be used to gain access to the process' symbol table, or to start another copy of the process. .It Pa mem The complete virtual memory image of the process. Only those addresses which exist in the process can be accessed. Reads and writes to this file modify the process. Writes to the text segment remain private to the process. .El .Pp Each node is owned by the process's user, and belongs to that user's primary group, except for the .Pa mem node, which belongs to the .Li kmem group. .Sh FILES .Bl -tag -width /compat/linux/proc/self/XXXXXXX -compact .It Pa /compat/linux/proc The normal mount point for the .Nm . .It Pa /compat/linux/proc/cpuinfo CPU vendor and model information in human-readable form. .It Pa /compat/linux/proc/meminfo System memory information in human-readable form. .It Pa /compat/linux/proc/pid A directory containing process information for process .Pa pid . .It Pa /compat/linux/proc/self A directory containing process information for the current process. .It Pa /compat/linux/proc/self/exe The executable image for the current process. .It Pa /compat/linux/proc/self/mem The complete virtual address space of the current process. .El .Sh EXAMPLES To mount a .Nm file system on .Pa /compat/linux/proc : .Pp .Dl "mount -t linprocfs linproc /compat/linux/proc" .Sh SEE ALSO .Xr mount 2 , .Xr unmount 2 , .Xr procfs 5 , .Xr pseudofs 9 .Sh HISTORY The .Nm first appeared in .Fx 4.0 . .Sh AUTHORS .An -nosplit The .Nm was derived from .Nm procfs by .An Pierre Beyssac . This manual page was written by .An Dag-Erling Sm\(/orgrav , based on the .Xr procfs 5 manual page by .An Garrett Wollman . Index: head/share/man/man5/mailer.conf.5 =================================================================== --- head/share/man/man5/mailer.conf.5 (revision 162403) +++ head/share/man/man5/mailer.conf.5 (revision 162404) @@ -1,145 +1,144 @@ .\" $NetBSD: mailer.conf.5,v 1.2 1999/05/29 18:18:30 christos Exp $ .\" .\" Copyright (c) 1998 .\" Perry E. Metzger. 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 acknowledgment: .\" This product includes software developed for the NetBSD Project .\" by Perry E. Metzger. .\" 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 ``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 May 31, 2006 .Dt MAILER.CONF 5 .Os .Sh NAME .Nm mailer.conf .Nd configuration file for .Xr mailwrapper 8 .Sh DESCRIPTION The file .Pa /etc/mail/mailer.conf contains a series of lines of the form .Pp -.Pa name -.Pa program +.Ar name +.Ar program .Op Ar arguments ... .Pp The first word of each line is the -.Pa name +.Ar name of a program invoking .Xr mailwrapper 8 . (For example, on a typical system .Pa /usr/sbin/sendmail would be a symbolic link to .Xr mailwrapper 8 , as would .Xr newaliases 1 and .Xr mailq 1 . Thus, -.Pa name +.Ar name might be -.Dq sendmail +.Dq Li sendmail or -.Dq newaliases +.Dq Li newaliases etc.) .Pp The second word of each line is the name of the -.Pa program +.Ar program to actually execute when the first name is invoked. .Pp The further .Ar arguments , if any, are passed to the -.Pa program , +.Ar program , followed by the arguments .Xr mailwrapper 8 was called with. .Pp The file may also contain comment lines, denoted by a -.Sq # +.Ql # mark in the first column of any line. -first column of any line. .Sh FILES /etc/mail/mailer.conf .Sh EXAMPLES This example shows how to set up .Nm to invoke the traditional .Xr sendmail 8 program: .Bd -literal -offset indent # Execute the "real" sendmail program located in # /usr/libexec/sendmail/sendmail sendmail /usr/libexec/sendmail/sendmail send-mail /usr/libexec/sendmail/sendmail mailq /usr/libexec/sendmail/sendmail newaliases /usr/libexec/sendmail/sendmail .Ed .Pp This example shows how to invoke a sendmail-workalike like Postfix in place of .Xr sendmail 8 : .Bd -literal -offset indent # Emulate sendmail using postfix sendmail /usr/local/sbin/sendmail send-mail /usr/local/sbin/sendmail mailq /usr/local/sbin/sendmail newaliases /usr/local/sbin/sendmail .Ed .Pp -This example shows the use of the mini_sendmail package from ports -in place of -.Xr sendmail 8 : +This example shows the use of the +.Nm mini_sendmail +package from ports in place of +.Xr sendmail 8 . Note the use of additional arguments. .Bd -literal -offset indent # Send outgoing mail to a smart relay using mini_sendmail sendmail /usr/local/bin/mini_sendmail -srelayhost send-mail /usr/local/bin/mini_sendmail -srelayhost .Ed .Sh SEE ALSO .Xr mail 1 , .Xr mailq 1 , .Xr newaliases 1 , .Xr mailwrapper 8 , .Xr sendmail 8 .Pp -.Xr postfix 1 -.Pq Pa ports/mail/postfix , +.Xr postfix 1 Pq Pa ports/mail/postfix , .Xr mini_sendmail 8 Pq Pa ports/mail/mini_sendmail .Sh HISTORY .Nm appeared in .Nx 1.4 . .Sh AUTHORS .An Perry E. Metzger Aq perry@piermont.com .Sh BUGS The entire reason this program exists is a crock. Instead, a command for how to submit mail should be standardized, and all the "behave differently if invoked with a different name" behavior of things like .Xr mailq 1 should go away. Index: head/share/man/man5/make.conf.5 =================================================================== --- head/share/man/man5/make.conf.5 (revision 162403) +++ head/share/man/man5/make.conf.5 (revision 162404) @@ -1,696 +1,693 @@ .\" Copyright (c) 2000 .\" Mike W. Meyer .\" .\" 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 5, 2006 .Dt MAKE.CONF 5 .Os .Sh NAME .Nm make.conf .Nd system build information .Sh DESCRIPTION The file .Nm contains system-wide settings that will apply to every build using .Xr make 1 and the standard .Pa sys.mk file. This is achieved as follows: .Xr make 1 processes the system makefile .Pa sys.mk before any other file by default, and .Pa sys.mk includes .Nm . .Pp The file .Nm uses the standard makefile syntax. However, .Nm should not specify any dependencies to .Xr make 1 . Instead, .Nm is to set .Xr make 1 variables that control the actions of other makefiles. .Pp The default location of .Nm is .Pa /etc/make.conf , though an alternative location can be specified in the .Xr make 1 variable .Va __MAKE_CONF . You may need to override the location of .Nm if the system-wide settings are not suitable for a particular build. For instance, setting .Va __MAKE_CONF to .Pa /dev/null effectively resets all build controls to their defaults. .Pp The primary purpose of .Nm is to control the compilation of the .Fx sources, documentation, and ported applications, which are usually found in .Pa /usr/src , .Pa /usr/doc , and .Pa /usr/ports . As a rule, the system administrator creates .Nm when the values of certain control variables need to be changed from their defaults. .Pp The system build procedures occur in four broad areas: the world, the kernel, documentation and ports. Variables set in .Nm may be applicable in one, two, or all four of these areas. In addition, control variables can be specified for a particular build via the .Fl D option of .Xr make 1 or in .Xr environ 7 . .Pp The following lists provide a name and short description for each variable you can use during the indicated builds. The values of variables flagged as .Vt bool are ignored; the variable being set at all (even to .Dq Li FALSE or .Dq Li NO ) causes it to be treated as if it were set. .Pp The following list provides a name and short description for variables that are used for all builds, or are used by the .Pa makefiles for things other than builds. .Bl -tag -width Ar .It Va ALWAYS_CHECK_MAKE .Pq Vt bool Instructs the top-level makefile in the source tree (normally .Pa /usr/src ) to always check if .Xr make 1 is up-to-date. Normally this is only done for the world and buildworld targets to handle upgrades from older versions of .Fx . .It Va CFLAGS .Pq Vt str Controls the compiler setting when compiling C code. Optimization levels other than .Fl O and .Fl O2 are not supported. .Va BDECFLAGS is provided as a set of .Xr gcc 1 settings suggested by .An "Bruce Evans" Aq bde@FreeBSD.org for developing and testing changes. They can be used, if set, by: .Pp .Bd -literal -offset indent CFLAGS+=${BDECFLAGS} .Ed .It Va CPUTYPE .Pq Vt str Controls which processor should be targeted for generated code. This controls processor-specific optimizations in certain code (currently only OpenSSL) as well as modifying the value of .Va CFLAGS and .Va COPTFLAGS to contain the appropriate optimization directive to .Xr gcc 1 . The automatic setting of .Va CFLAGS and .Va COPTFLAGS may be overridden using the .Va NO_CPU_CFLAGS and .Va NO_CPU_COPTFLAGS variables, respectively. Refer to .Pa /usr/share/examples/etc/make.conf for a list of recognized .Va CPUTYPE options. .It Va CVS_UPDATE .Pq Vt bool Set this to use .Xr cvs 1 to update your ports with .Dq Li "make update" . .It Va CXXFLAGS .Pq Vt str Controls the compiler settings when compiling C++ code. .Va CXXFLAGS is initially set to the value of .Va CFLAGS . If you want to add to the .Va CXXFLAGS value, use .Dq Li += instead of .Dq Li = . .It Va DOCSUPFILE .Pq Vt str The documentation .Ar supfile to use when doing a .Dq Li "make update" . This defaults to .Pa /usr/share/examples/cvsup/doc\-supfile . .It Va INSTALL .Pq Vt str the default install command. To install only files for which the target differs or does not exist, use .Bd -literal -offset indent INSTALL="install -C" .Ed Note that some makefiles (including those in .Pa /usr/share/mk ) may hardcode options for the supplied install command. .It Va LOCAL_DIRS .Pq Vt str List any directories that should be entered when doing make's in .Pa /usr/src in this variable. .It Va MAKE_SHELL .Pq Vt str Controls the shell used internally by .Xr make 1 to process the command scripts in makefiles. .Xr sh 1 , .Xr ksh 1 , and .Xr csh 1 all currently supported. .Pp .Dl "MAKE_SHELL?=sh" .It Va MTREE_FOLLOWS_SYMLINKS .Pq Vt str Set this to .Dq Fl L to cause .Xr mtree 8 to follow symlinks. .It Va NO_CPU_CFLAGS .Pq Vt str Setting this variable will prevent CPU specific compiler flags from being automatically added to .Va CFLAGS during compile time. .It Va NO_CPU_COPTFLAGS .Pq Vt str Setting this variable will prevent CPU specific compiler flags from being automatically added to .Va COPTFLAGS during compile time. .It Va NO_DOCUPDATE .Pq Vt bool Set this to not update the doc tree during .Dq Li "make update" . .It Va NO_PORTSUPDATE .Pq Vt bool Set this to not update the ports tree during .Dq Li "make update" . .It Va PORTSSUPFILE .Pq Vt str The ports .Ar supfile to use when doing a .Dq Li "make update" . This defaults to .Pa /usr/share/examples/cvsup/ports\-supfile . .It Va SUP .Pq Vt str The location of the .Xr csup 1 or .Xr cvsup 1 command for .Dq Li "make update" . .It Va SUPFILE .Pq Vt str The first .Ar supfile to use when doing a .Dq Li "make update" . This defaults to .Pa /usr/share/examples/cvsup/standard\-supfile . .It Va SUPFILE1 .Pq Vt str The second .Ar supfile to use when doing a .Dq Li "make update" . This defaults to .Pa /usr/share/examples/cvsup/secure\-supfile . .It Va SUPFILE2 .Pq Vt str The third .Ar supfile to use when doing a .Dq Li "make update" . This defaults to .Pa /usr/share/examples/cvsup/secure\-supfile . .It Va SUPFLAGS .Pq Vt str The flag for the .Xr sup 1 command when doing .Dq Li "make update" . This defaults to .Op Fl g L Ar 2 . .It Va SUPHOST .Pq Vt str The hostname of the sup server to use when doing .Dq Li "make update" . .It Va SUP_UPDATE .Pq Vt bool Set this to use .Xr cvsup 1 to update your ports with .Dq Li "make update" . .El .Ss "BUILDING THE KERNEL" -.Pp The following list provides a name and short description for variables that are only used doing a kernel build: .Bl -tag -width Ar .It Va BOOTWAIT .Pq Vt int Controls the amount of time the kernel waits for a console keypress before booting the default kernel. The value is approximately milliseconds. Keypresses are accepted by the BIOS before booting from disk, making it possible to give custom boot parameters even when this is set to 0. .It Va COPTFLAGS .Pq Vt str Controls the compiler settings when building the kernel. Optimization levels above .Oo Fl O ( O2 , No ...\& ) Oc are not guaranteed to work. .It Va KERNCONF .Pq Vt str Controls which kernel configurations will be built by .Dq Li "${MAKE} buildkernel" and installed by .Dq Li "${MAKE} installkernel" . For example, .Bd -literal -offset indent KERNCONF=MINE DEBUG GENERIC OTHERMACHINE .Ed .Pp will build the kernels specified by the config files .Pa MINE , DEBUG , GENERIC , and .Pa OTHERMACHINE , and install the kernel specified by the config file .Pa MINE . It defaults to .Pa GENERIC . .It Va MODULES_OVERRIDE .Pq Vt str Set to a list of modules to build instead of all of them. .It Va NO_KERNELCONFIG .Pq Vt bool Set this to skip running .Xr config 8 during .Dq Li "${MAKE} buildkernel" . .It Va NO_KERNELDEPEND .Pq Vt bool Set this to skip running .Dq Li "${MAKE} depend" during .Dq Li "${MAKE} buildkernel" . .It Va NO_MODULES .Pq Vt bool Set to not build modules with the kernel. .It Va PORTS_MODULES Set this to the list of ports you wish to rebuild every time the kernel is built. .It Va WITHOUT_MODULES .Pq Vt str Set to a list of modules to exclude from the build. This provides a somewhat easier way to exclude modules you are certain you will never need than specifying .Va MODULES_OVERRIDE . This is applied .Em after .Va MODULES_OVERRIDE . .El .Ss "BUILDING THE WORLD" -.Pp The following list provides a name and short description for variables that are used during the world build: .Bl -tag -width Ar .It Va BOOT_COMCONSOLE_PORT .Pq Vt str The port address to use for the console if the boot blocks have been configured to use a serial console instead of the keyboard/video card. .It Va BOOT_COMCONSOLE_SPEED .Pq Vt int The baud rate to use for the console if the boot blocks have been configured to use a serial console instead of the keyboard/video card. .It Va BOOT_PXELDR_ALWAYS_SERIAL .Pq Vt bool Compile in the code into .Xr pxeboot 8 that forces the use of a serial console. This is analogous to the .Fl h option in .Xr boot 8 blocks. .It Va BOOT_PXELDR_PROBE_KEYBOARD .Pq Vt bool Compile in the code into .Xr pxeboot 8 that probes the keyboard. If no keyboard is found, boot with the dual console configuration. This is analogous to the .Fl D option in .Xr boot 8 blocks. .It Va ENABLE_SUID_K5SU .Pq Vt bool Set this if you wish to use the ksu utility. Otherwise, it will be installed without the set-user-ID bit set. .It Va ENABLE_SUID_NEWGRP .Pq Vt bool Set this to install .Xr newgrp 1 with the set-user-ID bit set. Otherwise, .Xr newgrp 1 will not be able to change users' groups. .It Va ENABLE_SUID_SSH .Pq Vt bool Set this to install .Xr ssh 1 with the set-user-ID bit turned on. .It Va LOADER_TFTP_SUPPORT .Pq Vt bool By default the .Xr pxeboot 8 loader retrieves the kernel via NFS. Defining this and recompiling .Pa /usr/src/sys/boot will cause it to retrieve the kernel via TFTP. This allows .Xr pxeboot 8 to load a custom BOOTP diskless kernel yet still mount the server's .Pa / rather than load the server's kernel. .It Va MODULES_WITH_WORLD .Pq Vt bool Set to build modules with the system instead of the kernel. .It Va NO_CLEAN .Pq Vt bool Set this to disable cleaning during .Dq Li "make buildworld" . This should not be set unless you know what you are doing. .It Va NO_CLEANDIR .Pq Vt bool Set this to run .Dq Li "${MAKE} clean" instead of .Dq Li "${MAKE} cleandir" . .It Va NO_MANCOMPRESS .Pq Vt bool Set to install manual pages uncompressed. .It Va NO_SHARE .Pq Vt bool Set to not build in the .Pa share subdir. .It Va NO_SHARED .Pq Vt bool Set to build .Pa /bin and .Pa /sbin statically linked, this can be bad. If set, every utility that uses .Pa bsd.prog.mk will be linked statically. .It Va PPP_NO_NAT .Pq Vt bool Build .Xr ppp 8 without support for network address translation (NAT). .It Va PPP_NO_NETGRAPH .Pq Vt bool Set to build .Xr ppp 8 without support for Netgraph. .It Va PPP_NO_RADIUS .Pq Vt bool Set to build .Xr ppp 8 without support for RADIUS. .It Va PPP_NO_SUID .Pq Vt bool Set to disable the installation of .Xr ppp 8 as a set-user-ID root program. .It Va SENDMAIL_ADDITIONAL_MC .Pq Vt str Additional .Pa .mc files which should be built into .Pa .cf files at build time. The value should include the full path to the .Pa .mc file(s), e.g., .Pa /etc/mail/foo.mc .Pa /etc/mail/bar.mc . .It Va SENDMAIL_CFLAGS .Pq Vt str Flags to pass to the compile command when building .Xr sendmail 8 . The .Va SENDMAIL_* flags can be used to provide SASL support with setting such as: .Bd -literal -offset indent SENDMAIL_CFLAGS=-I/usr/local/include -DSASL SENDMAIL_LDFLAGS=-L/usr/local/lib SENDMAIL_LDADD=-lsasl .Ed .It Va SENDMAIL_CF_DIR .Pq Vt str Override the default location for the .Xr m4 1 configuration files used to build a .Pa .cf file from a .Pa .mc file. .It Va SENDMAIL_DPADD .Pq Vt str Extra dependencies to add when building .Xr sendmail 8 . .It Va SENDMAIL_LDADD .Pq Vt str Flags to add to the end of the .Xr ld 1 command when building .Xr sendmail 8 . .It Va SENDMAIL_LDFLAGS .Pq Vt str Flags to pass to the .Xr ld 1 command when building .Xr sendmail 8 . .It Va SENDMAIL_M4_FLAGS .Pq Vt str Flags passed to .Xr m4 1 when building a .Pa .cf file from a .Pa .mc file. .It Va SENDMAIL_MAP_PERMS .Pq Vt str Mode to use when generating alias and map database files using .Pa /etc/mail/Makefile . The default value is 0640. .It Va SENDMAIL_MC .Pq Vt str The default .Xr m4 1 configuration file to use at install time. The value should include the full path to the .Pa .mc file, e.g., .Pa /etc/mail/myconfig.mc . Use with caution as a make install will overwrite any existing .Pa /etc/mail/sendmail.cf . Note that .Va SENDMAIL_CF is now deprecated. .It Va SENDMAIL_SET_USER_ID .Pq Vt bool If set, install .Xr sendmail 8 as a set-user-ID root binary instead of a set-group-ID binary and do not install .Pa /etc/mail/submit.{cf,mc} . Use of this flag is not recommended and the alternative advice in .Pa /etc/mail/README should be followed instead if at all possible. .It Va SENDMAIL_SUBMIT_MC .Pq Vt str The default .Xr m4 1 configuration file for mail submission to use at install time. The value should include the full path to the .Pa .mc file, e.g., .Pa /etc/mail/mysubmit.mc . Use with caution as a make install will overwrite any existing .Pa /etc/mail/submit.cf . .It Va TOP_TABLE_SIZE .Pq Vt int .Xr top 1 uses a hash table for the user names. The size of this hash can be tuned to match the number of local users. The table size should be a prime number approximately twice as large as the number of lines in .Pa /etc/passwd . The default number is 20011. .It Va WANT_FORCE_OPTIMIZATION_DOWNGRADE .Pq Vt int Causes the system compiler to be built such that it forces high optimization levels to a lower one. .Xr gcc 1 .Fl O2 and above is known to trigger known optimizer bugs at various times. The value assigned is the highest optimization value used. .El .Ss "BUILDING DOCUMENTATION" -.Pp The following list provides a name and short description for variables that are used when building documentation. .Bl -tag -width ".Va PRINTERDEVICE" .It Va DISTDIR .Pq Vt str Where distfiles are kept. Normally, this is .Pa distfiles in .Va PORTSDIR . .It Va DOC_LANG .Pq Vt str The list of languages and encodings to build and install. .It Va PRINTERDEVICE .Pq Vt str The default format for system documentation, depends on your printer. This can be set to .Dq Li ascii for simple printers, or .Dq Li ps for postscript or graphics printers with a ghostscript filter, or both. .El .Sh FILES .Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact .It Pa /etc/make.conf .It Pa /usr/doc/Makefile .It Pa /usr/share/examples/etc/make.conf .It Pa /usr/share/mk/sys.mk .It Pa /usr/src/Makefile .It Pa /usr/src/Makefile.inc1 .El .Sh SEE ALSO .Xr gcc 1 , .Xr install 1 , .Xr make 1 , .Xr src.conf 5 , .Xr environ 7 , .Xr ports 7 , .Xr sendmail 8 .Sh HISTORY The .Nm file appeared sometime before .Fx 4.0 . .Sh AUTHORS This manual page was written by .An Mike W. Meyer Aq mwm@mired.org . .Sh BUGS This manual page may occasionally be out of date with respect to the options currently available for use in .Nm . Please check the .Pa /usr/share/examples/etc/make.conf file for the latest options which are available. .Sh CAVEATS Note, that .Ev MAKEOBJDIRPREFIX and .Ev MAKEOBJDIR are environment variables and should not be set in .Nm but in make's environment. Index: head/share/man/man5/portsnap.conf.5 =================================================================== --- head/share/man/man5/portsnap.conf.5 (revision 162403) +++ head/share/man/man5/portsnap.conf.5 (revision 162404) @@ -1,136 +1,136 @@ .\"- .\" Copyright 2004-2005 Colin Percival .\" All rights reserved .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted providing 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 January 30, 2005 .Dt PORTSNAP.CONF 5 .Os FreeBSD .Sh NAME .Nm portsnap.conf -.Nd configuration file for +.Nd configuration file for .Xr portsnap 8 .Sh DESCRIPTION The .Nm file controls where .Xr portsnap 8 fetches ports tree snapshots from, which RSA key should be trusted to sign the updates, and what directories should hold the compressed and live ports trees. .Pp A line of the form .Dl SERVERNAME=portsnap.example.com specifies the source from which snapshots should be fetched. This is equivalent to the .Fl s Ar server -option to +option to .Xr portsnap 8 , and will be ignored if the command-line option is used. .Pp A line of the form .Dl KEYPRINT=0123456789abc ... 456789abcdef (64 characters in total) specifies the SHA-256 hash of the OpenSSL public key file belonging to an RSA keypair which is trusted to sign updates. This is equivalent to the .Fl k Ar KEY -option to +option to .Xr portsnap 8 , and will be ignored if the command-line option is used. .Pp A line of the form .Dl WORKDIR=/path/to/workdir specifies the directory in which portsnap should maintain its compressed snapshot of the ports tree. This is equivalent to the .Fl d Ar workdir option to .Xr portsnap 8 , and will be ignored if the command-line option is used. .Pp A line of the form .Dl PORTSDIR=/path/to/portstree specifies the directory in which portsnap will create the live ports tree from its compressed snapshot via the .Cm extract and .Cm update commands. This is equivalent to the .Fl p Ar portsdir option to .Xr portsnap 8 , and will be ignored if the command-line option is used. .Pp If more than one line of any of the above forms is included in .Nm then only the last one will take effect. .Pp Finally, a line of the form .Dl REFUSE foo bar will instruct .Xr portsnap 8 to ignore parts of the ports tree with paths starting with -.Ar foo +.Ar foo or .Ar bar , which are interpreted as extended regular expressions by .Xr egrep 1 . This will result in those parts of the tree not being updated in the compressed snapshot when the .Cm fetch and .Cm cron commands are used and not being extracted when the .Cm extract command is used (unless a specific .Ar path is passed to .Xr portsnap 8 ) , and if those parts of the ports tree are present they will not be updated when the .Cm update command is used. Unlike the other options, the parameters in REFUSE lines accumulate and all such lines are considered. .Bf Em Note that operating with an incomplete ports tree is not supported and may cause unexpected results. .Ef .Pp Any lines not of the above forms will be ignored. .Sh FILES .Bl -tag -width "/etc/portsnap.conf" .It /etc/portsnap.conf Default location of the portsnap configuration file. .El .Sh SEE ALSO -.Xr egrep 1 -.Xr fetch 1 -.Xr portsnap 8 +.Xr egrep 1 , +.Xr fetch 1 , +.Xr portsnap 8 , .Xr sha256 8 .Sh AUTHORS .An Colin Percival Aq cperciva@FreeBSD.org Index: head/share/man/man5/rc.conf.5 =================================================================== --- head/share/man/man5/rc.conf.5 (revision 162403) +++ head/share/man/man5/rc.conf.5 (revision 162404) @@ -1,3693 +1,3707 @@ .\" Copyright (c) 1995 .\" Jordan K. Hubbard .\" .\" 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 August 17, 2006 .Dt RC.CONF 5 .Os .Sh NAME .Nm rc.conf .Nd system configuration information .Sh DESCRIPTION The file .Nm contains descriptive information about the local host name, configuration details for any potential network interfaces and which services should be started up at system initial boot time. In new installations, the .Nm file is generally initialized by the system installation utility, .Xr sysinstall 8 . .Pp The purpose of .Nm is not to run commands or perform system startup actions directly. Instead, it is included by the various generic startup scripts in .Pa /etc which conditionalize their internal actions according to the settings found there. .Pp The .Pa /etc/rc.conf file is included from the file .Pa /etc/defaults/rc.conf , which specifies the default settings for all the available options. Options need only be specified in .Pa /etc/rc.conf when the system administrator wishes to override these defaults. The file .Pa /etc/rc.conf.local is used to override settings in .Pa /etc/rc.conf for historical reasons. See the .Va rc_conf_files variable below. .Pp Options are set with -.Dq Li name=value +.Dq Ar name Ns Li = Ns Ar value assignments that use .Xr sh 1 syntax. The following list provides a name and short description for each variable that can be set in the .Nm file: .Bl -tag -width indent-two .It Va rc_debug .Pq Vt bool If set to .Dq Li YES , enable output of debug messages from rc scripts. This variable can be helpful in diagnosing mistakes when editing or integrating new scripts. Beware that this produces copious output to the terminal and .Xr syslog 3 . .It Va rc_info .Pq Vt bool If set to .Dq Li NO , disable informational messages from the rc scripts. Informational messages are displayed when a condition that is not serious enough to warrant a warning or an error occurs. .It Va early_late_divider .Pq Vt str The name of the script that should be used as the delimiter between the .Dq early and .Dq late stages of the boot process. The early stage should contain all the services needed to get the disks (local or remote) mounted so that the late stage can include scripts contained in the directories listed in the .Va local_startup variable (see below). Thus, the two likely candidates for this value are -mountcritlocal for the typical system, -and mountcritremote if the system needs remote file +.Pa mountcritlocal +for the typical system, and +.Pa mountcritremote +if the system needs remote file systems mounted to get access to the .Va local_startup directories; for example when .Pa /usr/local is NFS mounted. For .Pa rc.conf within a .Xr jail 8 -NETWORKING is likely to be an appropriate value. +.Pa NETWORKING +is likely to be an appropriate value. Extreme care should be taken when changing this value, and before changing it one should ensure that there are adequate provisions to recover from a failed boot (such as physical contact with the machine, or reliable remote console access). .It Va swapfile .Pq Vt str If set to .Dq Li NO , no swapfile is installed, otherwise the value is used as the full pathname to a file to use for additional swap space. .It Va apm_enable .Pq Vt bool If set to .Dq Li YES , enable support for Automatic Power Management with the .Xr apm 8 command. .It Va apmd_enable .Pq Vt bool Run .Xr apmd 8 to handle APM event from userland. This also enables support for APM. .It Va apmd_flags .Pq Vt str If .Va apmd_enable is set to .Dq Li YES , these are the flags to pass to the .Xr apmd 8 daemon. .It Va devd_enable .Pq Vt bool Run .Xr devd 8 to handle device added, removed or unknown events from the kernel. .It Va kldxref_enable .Pq Vt bool Set to .Dq Li NO by default. Set to .Dq Li YES to automatically rebuild .Pa linker.hints files with .Xr kldxref 8 at boot time. .It Va kldxref_clobber .Pq Vt bool Set to .Dq Li NO by default. If .Va kldxref_enable is true, setting to .Dq Li YES will overwrite existing .Pa linker.hints files at boot time. Otherwise, only missing .Pa linker.hints files are generated. .It Va kldxref_module_path .Pq Vt str Empty by default. A semi-colon .Pq Ql \&; delimited list of paths containing .Xr kld 4 modules. If empty, the contents of the .Va kern.module_path .Xr sysctl 8 are used. .It Va powerd_enable .Pq Vt bool If set to .Dq Li YES , enable the system power control facility with the .Xr powerd 8 daemon. .It Va powerd_flags .Pq Vt str If .Va powerd_enable is set to .Dq Li YES , these are the flags to pass to the .Xr powerd 8 daemon. .It Va tmpmfs Controls the creation of a .Pa /tmp memory file system. Always happens if set to .Dq Li YES and never happens if set to .Dq Li NO . If set to anything else, a memory file system is created if .Pa /tmp is not writable. .It Va tmpsize Controls the size of a created .Pa /tmp memory file system. .It Va tmpmfs_flags Extra options passed to the .Xr mdmfs 8 utility when the memory file system for .Pa /tmp is created. The default is .Dq Li "-S -M" , which inhibits the use of softupdates on .Pa /tmp to waste as little space as possible and creates a pure memory backed disk, which will never be swapped out, for maximum performance and system stability at low memory conditions. See .Xr mdmfs 8 for other options you can use in .Va tmpmfs_flags . .It Va varmfs Controls the creation of a .Pa /var memory file system. Always happens if set to .Dq Li YES and never happens if set to .Dq Li NO . If set to anything else, a memory file system is created if .Pa /var is not writable. .It Va varsize Controls the size of a created .Pa /var memory file system. .It Va varmfs_flags Extra options passed to the .Xr mdmfs 8 utility when the memory file system for .Pa /var is created. The default is .Dq Li "-S -M" , which inhibits the use of softupdates on .Pa /var to waste as little space as possible and creates a pure memory backed disk, which will never be swapped out, for maximum performance and system stability at low memory conditions. See .Xr mdmfs 8 for other options you can use in .Va varmfs_flags . .It Va populate_var Controls the automatic population of the .Pa /var file system. Always happens if set to .Dq Li YES and never happens if set to .Dq Li NO . If set to anything else, a memory file system is created if .Pa /var is not writable. Note that this process requires access to certain commands in .Pa /usr before .Pa /usr is mounted on normal systems. .It Va cleanvar_enable .Pq Vt bool Clean the .Pa /var directory. .It Va local_startup .Pq Vt str List of directories to search for startup script files. .It Va script_name_sep .Pq Vt str The field separator to use for breaking down the list of startup script files into individual filenames. The default is a space. It is not necessary to change this unless there are startup scripts with names containing spaces. .It Va hostapd_enable .Pq Vt bool Set to .Dq Li YES to start .Xr hostapd 8 at system boot time. .It Va hostname .Pq Vt str The fully qualified domain name (FQDN) of this host on the network. This should almost certainly be set to something meaningful, even if there is no network connection. If .Xr dhclient 8 is used to set the hostname via DHCP, this variable should be set to an empty string. .It Va ipv6_enable .Pq Vt bool Enable support for IPv6 networking. Note that this requires that the kernel has been compiled with .Cd "options INET6" . .It Va nisdomainname .Pq Vt str The NIS domain name of this host, or .Dq Li NO if NIS is not used. .It Va dhclient_program .Pq Vt str Path to the DHCP client program .Pa ( /sbin/dhclient , the .Ox DHCP client, is the default). .It Va dhclient_flags .Pq Vt str Additional flags to pass to the DHCP client program. For the .Ox DHCP client, see the .Xr dhclient 8 manpage for a description of the command line options available. -.It Va dhclient_flags_ Ns Va iface +.It Va dhclient_flags_ Ns Aq Ar iface Additional flags to pass to the DHCP client program running on -.Va iface +.Ar iface only. When specified, this variable overrides .Va dhclient_flags . .It Va background_dhclient .Pq Vt bool Set to .Dq Li YES to start the DHCP client in background. This can cause trouble with applications depending on a working network, but it will provide a faster startup in many cases. -.It Va background_dhclient_ Ns Va iface +.It Va background_dhclient_ Ns Aq Ar iface When specified, this variable overrides the .Va background_dhclient variable for interface -.Va iface +.Ar iface only. .It Va synchronous_dhclient .Pq Bt bool Set to .Dq Li NO to start .Xr dhclient 8 only in response to interface events and not synchronously at startup. This behavior can be overridden on a per-interface basis by replacing the .Dq Li DHCP keyword in the .Va ifconfig_ Ns Aq Ar interface variable with .Dq Li SYNCDHCP or .Dq Li NOSYNCDHCP . .It Va firewall_enable .Pq Vt bool Set to .Dq Li YES to load firewall rules at startup. If the kernel was not built with .Cd "options IPFIREWALL" , the .Pa ipfw.ko kernel module will be loaded. See also .Va ipfilter_enable . .It Va ipv6_firewall_enable .Pq Vt bool The IPv6 equivalent of .Va firewall_enable . Set to .Dq Li YES to load IPv6 firewall rules at startup. If the kernel was not built with .Cd "options IPV6FIREWALL" , the .Pa ipfw.ko kernel module will be loaded. .It Va firewall_script .Pq Vt str This variable specifies the full path to the firewall script to run. The default is .Pa /etc/rc.firewall . .It Va ipv6_firewall_script .Pq Vt str The IPv6 equivalent of .Va firewall_script . .It Va firewall_type .Pq Vt str Names the firewall type from the selection in .Pa /etc/rc.firewall , or the file which contains the local firewall ruleset. Valid selections from .Pa /etc/rc.firewall are: .Pp .Bl -tag -width ".Li simple" -compact .It Li open unrestricted IP access .It Li closed all IP services disabled, except via .Dq Li lo0 .It Li client basic protection for a workstation .It Li simple basic protection for a LAN. .El .Pp If a filename is specified, the full path must be given. .It Va ipv6_firewall_type .Pq Vt str The IPv6 equivalent of .Va firewall_type . .It Va firewall_quiet .Pq Vt bool Set to .Dq Li YES to disable the display of firewall rules on the console during boot. .It Va ipv6_firewall_quiet .Pq Vt bool The IPv6 equivalent of .Va firewall_quiet . .It Va firewall_logging .Pq Vt bool Set to .Dq Li YES to enable firewall event logging. This is equivalent to the .Dv IPFIREWALL_VERBOSE kernel option. .It Va ipv6_firewall_logging .Pq Vt bool The IPv6 equivalent of .Va firewall_logging . .It Va firewall_flags .Pq Vt str Flags passed to .Xr ipfw 8 if .Va firewall_type specifies a filename. .It Va ipv6_firewall_flags .Pq Vt str The IPv6 equivalent of .Va firewall_flags . .It Va natd_program .Pq Vt str Path to .Xr natd 8 . .It Va natd_enable .Pq Vt bool Set to .Dq Li YES to enable .Xr natd 8 . .Va firewall_enable must also be set to .Dq Li YES , and .Xr divert 4 sockets must be enabled in the kernel. If the kernel was not built with .Cd "options IPDIVERT" , the .Pa ipdivert.ko kernel module will be loaded. .It Va natd_interface .Pq Vt str This is the name of the public interface on which .Xr natd 8 should run. The interface may be given as an interface name or as an IP address. .It Va natd_flags .Pq Vt str Additional .Xr natd 8 flags should be placed here. The .Fl n or .Fl a flag is automatically added with the above .Va natd_interface as an argument. .\" ----- ipfilter_enable setting -------------------------------- .It Va ipfilter_enable .Pq Vt bool Set to .Dq Li NO by default. Setting this to .Dq Li YES enables .Xr ipf 8 packet filtering. .Pp Typical usage will require putting .Bd -literal ipfilter_enable="YES" ipnat_enable="YES" ipmon_enable="YES" ipfs_enable="YES" .Ed .Pp into .Pa /etc/rc.conf and editing .Pa /etc/ipf.rules and .Pa /etc/ipnat.rules appropriately. .Pp Note that .Va ipfilter_enable and .Va ipnat_enable can be enabled independently. .Va ipmon_enable and .Va ipfs_enable both require at least one of .Va ipfilter_enable and .Va ipnat_enable to be enabled. .Pp Having .Bd -literal options IPFILTER options IPFILTER_LOG options IPFILTER_DEFAULT_BLOCK .Ed .Pp in the kernel configuration file is a good idea, too. .\" ----- ipfilter_program setting ------------------------------ .It Va ipfilter_program .Pq Vt str Path to .Xr ipf 8 (default .Pa /sbin/ipf ) . .\" ----- ipfilter_rules setting -------------------------------- .It Va ipfilter_rules .Pq Vt str Set to .Pa /etc/ipf.rules by default. This variable contains the name of the filter rule definition file. The file is expected to be readable for the .Xr ipf 8 command to execute. .\" ----- ipv6_ipfilter_rules setting --------------------------- .It Va ipv6_ipfilter_rules .Pq Vt str Set to .Pa /etc/ipf6.rules by default. This variable contains the IPv6 filter rule definition file. The file is expected to be readable for the .Xr ipf 8 command to execute. .\" ----- ipfilter_flags setting -------------------------------- .It Va ipfilter_flags .Pq Vt str Empty by default. This variable contains flags passed to the .Xr ipf 8 program. .\" ----- ipnat_enable setting ---------------------------------- .It Va ipnat_enable .Pq Vt bool Set to .Dq Li NO by default. Set it to .Dq Li YES to enable .Xr ipnat 8 network address translation. See .Va ipfilter_enable for a detailed discussion. .\" ----- ipnat_program setting --------------------------------- .It Va ipnat_program .Pq Vt str Path to .Xr ipnat 8 (default .Pa /sbin/ipnat ) . .\" ----- ipnat_rules setting ----------------------------------- .It Va ipnat_rules .Pq Vt str Set to .Pa /etc/ipnat.rules by default. This variable contains the name of the file holding the network address translation definition. This file is expected to be readable for the .Xr ipnat 8 command to execute. .\" ----- ipnat_flags setting ----------------------------------- .It Va ipnat_flags .Pq Vt str Empty by default. This variable contains flags passed to the .Xr ipnat 8 program. .\" ----- ipmon_enable setting ---------------------------------- .It Va ipmon_enable .Pq Vt bool Set to .Dq Li NO by default. Set it to .Dq Li YES to enable .Xr ipmon 8 monitoring (logging .Xr ipf 8 and .Xr ipnat 8 events). Setting this variable needs setting .Va ipfilter_enable or .Va ipnat_enable too. See .Va ipfilter_enable for a detailed discussion. .\" ----- ipmon_program setting --------------------------------- .It Va ipmon_program .Pq Vt str Path to .Xr ipmon 8 (default .Pa /sbin/ipmon ) . .\" ----- ipmon_flags setting ----------------------------------- .It Va ipmon_flags .Pq Vt str Set to .Dq Li -Ds by default. This variable contains flags passed to the .Xr ipmon 8 program. Another typical example would be .Dq Fl D Pa /var/log/ipflog to have .Xr ipmon 8 log directly to a file bypassing .Xr syslogd 8 . Make sure to adjust .Pa /etc/newsyslog.conf in such case like this: .Bd -literal /var/log/ipflog 640 10 100 * Z /var/run/ipmon.pid .Ed .\" ----- ipfs_enable setting ----------------------------------- .It Va ipfs_enable .Pq Vt bool Set to .Dq Li NO by default. Set it to .Dq Li YES to enable .Xr ipfs 8 saving the filter and NAT state tables during shutdown and reloading them during startup again. Setting this variable needs setting .Va ipfilter_enable or .Va ipnat_enable to .Dq Li YES too. See .Va ipfilter_enable for a detailed discussion. Note that if .Va kern_securelevel is set to 3, .Va ipfs_enable cannot be used because the raised securelevel will prevent .Xr ipfs 8 from saving the state tables at shutdown time. .\" ----- ipfs_program setting ---------------------------------- .It Va ipfs_program .Pq Vt str Path to .Xr ipfs 8 (default .Pa /sbin/ipfs ) . .\" ----- ipfs_flags setting ------------------------------------ .It Va ipfs_flags .Pq Vt str Empty by default. This variable contains flags passed to the .Xr ipfs 8 program. .\" ----- end of added ipf hook --------------------------------- .It Va pf_enable .Pq Vt bool Set to .Dq Li NO by default. Setting this to .Dq Li YES enables .Xr pf 4 packet filtering. .Pp Typical usage will require putting .Pp .Dl pf_enable="YES" .Pp into .Pa /etc/rc.conf and editing .Pa /etc/pf.conf appropriately. .Pp .Dl "device pf" .Pp builds .Xr pf 4 into the kernel. Otherwise it is loaded from a module. .It Va pf_rules .Pq Vt str Path to .Xr pf 4 ruleset configuration file (default .Pa /etc/pf.conf ) . .It Va pf_program .Pq Vt str Path to .Xr pfctl 8 (default .Pa /sbin/pfctl ) . .It Va pf_flags .Pq Vt str If .Va pf_enable is set to .Dq Li YES , these flags are passed to the .Xr pfctl 8 program when loading the ruleset. .It Va pflog_enable .Pq Vt bool Set to .Dq Li NO by default. Setting this to .Dq Li YES enables .Xr pflogd 8 which logs packets from the .Xr pf 4 packet filter. .It Va pflog_logfile .Pq Vt str If .Va pflog_enable is set to .Dq Li YES this controls where .Xr pflogd 8 stores the logfile (default .Pa /var/log/pflog ) . Check .Pa /etc/newsyslog.conf to adjust logfile rotation for this. .It Va pflog_program .Pq Vt str Path to .Xr pflogd 8 (default .Pa /sbin/pflogd ) . .It Va pflog_flags .Pq Vt str Empty by default. This variable contains additional flags passed to the .Xr pflogd 8 program. .It Va pfsync_enable .Pq Vt bool Set to .Dq Li NO by default. Setting this to .Dq Li YES enables exposing .Xr pf 4 state changes to other hosts over the network by means of .Xr pfsync 4 . The .Va pfsync_syncdev variable must also be set then. .It Va pfsync_syncdev .Pq Vt str Empty by default. This variable specifies the name of the network interface .Xr pfsync 4 should operate through. It must be set accordingly if .Va pfsync_enable is set to .Dq Li YES . .It Va pfsync_ifconfig .Pq Vt str Empty by default. This variable can contain additional options to be passed to the .Xr ifconfig 8 command used to set up .Xr pfsync 4 . .It Va tcp_extensions .Pq Vt bool Set to .Dq Li YES by default. Setting this to .Dq Li NO disables certain TCP options as described by .Rs .%T "RFC 1323" .Re Setting this to .Dq Li NO might help remedy such problems with connections as randomly hanging or other weird behavior. Some network devices are known to be broken with respect to these options. .It Va log_in_vain .Pq Vt int Set to 0 by default. The .Xr sysctl 8 variables, .Va net.inet.tcp.log_in_vain and .Va net.inet.udp.log_in_vain , as described in .Xr tcp 4 and .Xr udp 4 , are set to the given value. .It Va tcp_keepalive .Pq Vt bool Set to .Dq Li YES by default. Setting to .Dq Li NO will disable probing idle TCP connections to verify that the peer is still up and reachable. .It Va tcp_drop_synfin .Pq Vt bool Set to .Dq Li NO by default. Setting to .Dq Li YES will cause the kernel to ignore TCP frames that have both the SYN and FIN flags set. This prevents OS fingerprinting, but may break some legitimate applications. This option is only available if the kernel was built with the .Dv TCP_DROP_SYNFIN option. .It Va icmp_drop_redirect .Pq Vt bool Set to .Dq Li NO by default. Setting to .Dq Li YES will cause the kernel to ignore ICMP REDIRECT packets. Refer to .Xr icmp 4 for more information. .It Va icmp_log_redirect .Pq Vt bool Set to .Dq Li NO by default. Setting to .Dq Li YES will cause the kernel to log ICMP REDIRECT packets. Note that the log messages are not rate-limited, so this option should only be used for troubleshooting networks. Refer to .Xr icmp 4 for more information. .It Va icmp_bmcastecho .Pq Vt bool Set to .Dq Li YES to respond to broadcast or multicast ICMP ping packets. Refer to .Xr icmp 4 for more information. .It Va ip_portrange_first .Pq Vt int If not set to .Dq Li NO , this is the first port in the default portrange. Refer to .Xr ip 4 for more information. .It Va ip_portrange_last .Pq Vt int If not set to .Dq Li NO , this is the last port in the default portrange. Refer to .Xr ip 4 for more information. .It Va network_interfaces .Pq Vt str Set to the list of network interfaces to configure on this host or .Dq Li AUTO (the default) for all current interfaces. Setting the .Va network_interfaces variable to anything other than the default is deprecated. Interfaces that the administrator wishes to store configration for, but not start at boot should be configured with the .Dq Li NOAUTO keyword in their .Va ifconfig_ Ns Aq Ar interface variables as described below. .Pp An .Va ifconfig_ Ns Aq Ar interface variable is also assumed to exist for each value of .Ar interface . When an interface name contains any of the characters .Dq Li .-/+ they are translated to .Dq Li _ before lookup. The variable can contain arguments to .Xr ifconfig 8 , as well as special case-insensitive keywords described below. Such keywords are removed before passing the value to .Xr ifconfig 8 while the order of the other arguments is preserved. .Pp One can configure more than one IPv4 address with the .Va ipv4_addrs_ Ns Aq Ar interface variable. One or more IP addresses must be provided in Classless Inter-Domain Routing (CIDR) address notation, whose last byte can be a range like 192.168.0.5-23/24. In this case the address 192.168.0.5 will be configured with the netmask /24 and the addresses 192.168.0.6 to 192.168.0.23 with the non-conflicting netmask /32 as explained in the .Xr ifconfig 8 alias section. With the interface in question being .Li ed0 , an example could look like: .Bd -literal ipv4_addrs_ed0="192.168.0.1/24 192.168.1.1-5/28" .Ed .Pp It is also possible to add IP alias entries using .Xr ifconfig 8 syntax. Assuming that the interface in question was .Li ed0 , it might look something like this: .Bd -literal ifconfig_ed0_alias0="inet 127.0.0.253 netmask 0xffffffff" ifconfig_ed0_alias1="inet 127.0.0.254 netmask 0xffffffff" .Ed .Pp And so on. For each .Va ifconfig_ Ns Ao Ar interface Ac Ns Va _alias Ns Aq Ar n entry that is found, its contents are passed to .Xr ifconfig 8 . Execution stops at the first unsuccessful access, so if something like this is present: .Bd -literal ifconfig_ed0_alias0="inet 127.0.0.251 netmask 0xffffffff" ifconfig_ed0_alias1="inet 127.0.0.252 netmask 0xffffffff" ifconfig_ed0_alias2="inet 127.0.0.253 netmask 0xffffffff" ifconfig_ed0_alias4="inet 127.0.0.254 netmask 0xffffffff" .Ed .Pp Then note that alias4 would .Em not be added since the search would stop with the missing .Dq Li alias3 entry. Due to this difficult to manage behavior, the .Va ifconfig_ Ns Ao Ar interface Ac Ns Va _alias Ns Aq Ar n form is deprecated. .Pp If the .Pa /etc/start_if. Ns Aq Ar interface file is present, it is read and executed by the .Xr sh 1 interpreter before configuring the interface as specified in the .Va ifconfig_ Ns Aq Ar interface and .Va ifconfig_ Ns Ao Ar interface Ac Ns Va _alias Ns Aq Ar n variables. .Pp If the .Va ifconfig_ Ns Aq Ar interface contains the keyword .Dq Li NOAUTO then the interface will not be configured at boot or by .Pa /etc/pccard_ether when .Va network_interfaces is set to .Dq Li AUTO . .Pp It is possible to bring up an interface with DHCP by adding .Dq Li DHCP to the .Va ifconfig_ Ns Aq Ar interface variable. For instance, to initialize the .Li ed0 device via DHCP, it is possible to use something like: .Bd -literal ifconfig_ed0="DHCP" .Ed .Pp Also, if your interface needs WPA authentication, it is possible to add .Dq Li WPA to the .Va ifconfig_ Ns Aq Ar interface variable. .Pp Finally, you can add .Xr ifconfig 8 options in this variable, in addition to the .Pa /etc/start_if. Ns Aq Ar interface file. For instance, to initialize the .Li wi0 device via DHCP, using WPA authentication and 802.11b mode, it is possible to use something like: .Bd -literal ifconfig_wi0="DHCP WPA mode 11b" .Ed .Pp In addition to the .Va ifconfig_ Ns Aq Ar interface form, a fallback variable .Va ifconfig_DEFAULT may be configured. It will be used for all interfaces with no .Va ifconfig_ Ns Aq Ar interface variable. This is intended to replace the no longer supported .Va pccard_ifconfig variable. .Pp It is also possible to rename interface by doing: .Bd -literal ifconfig_ed0_name="net0" ifconfig_net0="inet 10.0.0.1 netmask 0xffff0000" .Ed .It Va ipv6_network_interfaces .Pq Vt str This is the IPv6 equivalent of .Va network_interfaces . Instead of setting the ifconfig variables as .Va ifconfig_ Ns Aq Ar interface they should be set as .Va ipv6_ifconfig_ Ns Aq Ar interface . Aliases should be set as .Va ipv6_ifconfig_ Ns Ao Ar interface Ac Ns Va _alias Ns Aq Ar n . .Va ipv6_prefix_ Ns Aq Ar interface does something. Interfaces that do not have a .Va ipv6_ifconfig_ Ns Aq Ar interface setting will be auto configured by .Xr rtsol 8 if the .Va ipv6_gateway_enable is set to .Dq Li NO . Note that the IPv6 networking code does not support the .Pa /etc/start_if. Ns Aq Ar interface files. .It Va ipv6_default_interface .Pq Vt str If not set to .Dq Li NO , this is the default output interface for scoped addresses. Now this works only for IPv6 link local multicast addresses. .It Va cloned_interfaces .Pq Vt str Set to the list of clonable network interfaces to create on this host. Entries in .Va cloned_interfaces are automatically appended to .Va network_interfaces for configuration. .It Va gif_interfaces .Pq Vt str Set to the list of .Xr gif 4 tunnel interfaces to configure on this host. A .Va gifconfig_ Ns Aq Ar interface variable is assumed to exist for each value of .Ar interface . The value of this variable is used to configure the link layer of the tunnel according to the syntax of the .Cm tunnel option to .Xr ifconfig 8 . Additionally, this option ensures that each listed interface is created via the .Cm create option to .Xr ifconfig 8 before attempting to configure it. .It Va sppp_interfaces .Pq Vt str Set to the list of .Xr sppp 4 interfaces to configure on this host. A .Va spppconfig_ Ns Aq Ar interface variable is assumed to exist for each value of .Ar interface . Each interface should also be configured by a general .Va ifconfig_ Ns Aq Ar interface setting. Refer to .Xr spppcontrol 8 for more information about available options. .It Va ppp_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr ppp 8 daemon. .It Va ppp_mode .Pq Vt str Mode in which to run the .Xr ppp 8 daemon. Accepted modes are .Dq Li auto , .Dq Li ddial , .Dq Li direct and .Dq Li dedicated . See the manual for a full description. .It Va ppp_nat .Pq Vt bool If set to .Dq Li YES , enables network address translation. Used in conjunction with .Va gateway_enable allows hosts on private network addresses access to the Internet using this host as a network address translating router. .It Va ppp_profile .Pq Vt str The name of the profile to use from .Pa /etc/ppp/ppp.conf . .It Va ppp_user .Pq Vt str The name of the user under which .Xr ppp 8 should be started. By default, .Xr ppp 8 is started as .Dq Li root . .It Va rc_conf_files .Pq Vt str This option is used to specify a list of files that will override the settings in .Pa /etc/defaults/rc.conf . The files will be read in the order in which they are specified and should include the full path to the file. By default, the files specified are .Pa /etc/rc.conf and .Pa /etc/rc.conf.local .It Va gbde_autoattach_all .Pq Vt bool If set to .Dq Li YES , .Pa /etc/rc.d/gbde will attempt to automatically initialize your .bde devices in .Pa /etc/fstab . .It Va gbde_devices .Pq Vt str List the devices that the script should try to attach, or .Dq Li AUTO . .It Va gbde_lockdir .Pq Vt str The directory where the .Xr gbde 4 lockfiles are located. The default lockfile directory is .Pa /etc . .Pp The lockfile for each individual .Xr gbde 4 device can be overridden by setting the variable .Va gbde_lock_ Ns Aq Ar device , where .Ar device is the encrypted device without the .Dq Pa /dev/ and .Dq Pa .bde parts. .It Va gbde_attach_attempts .Pq Vt int Number of times to attempt attaching to a .Xr gbde 4 device, i.e., how many times the user is asked for the pass-phrase. Default is 3. .It Va geli_devices .Pq Vt str List of devices to automatically attach on boot. Note that .eli devices from .Pa /etc/fstab are automatically appended to this list. .It Va geli_tries .Pq Vt int Number of times user is asked for the pass-phrase. If empty, it will be taken from .Va kern.geom.eli.tries sysctl variable. .It Va geli_default_flags .Pq Vt str Default flags to use by .Xr geli 8 when configuring disk encryption. Flags can be configured for every device separately by defining .Va geli_ Ns Ao Ar device Ac Ns Va _flags variable. .It Va geli_autodetach .Pq Vt str Specifies if GELI devices should be marked for detach on last close after file systems are mounted. Default is .Dq Li YES . This can be changed for every device separately by defining .Va geli_ Ns Ao Ar device Ac Ns Va _autodetach variable. .It Va geli_swap_flags Options passed to the .Xr geli 8 utility when encrypted GEOM providers for swap partitions are created. The default is .Dq Li "-a aes -l 256 -s 4096 -d" . .It Va root_rw_mount .Pq Vt bool Set to .Dq Li YES by default. After the file systems are checked at boot time, the root file system is remounted as read-write if this is set to .Dq Li YES . Diskless systems that mount their root file system from a read-only remote NFS share should set this to .Dq Li NO in their .Pa rc.conf . .It Va fsck_y_enable .Pq Vt bool If set to .Dq Li YES , .Xr fsck 8 will be run with the .Fl y flag if the initial preen of the file systems fails. .It Va background_fsck .Pq Vt bool If set to .Dq Li YES , the system will attempt to run .Xr fsck 8 in the background where possible. .It Va background_fsck_delay .Pq Vt int The amount of time in seconds to sleep before starting a background .Xr fsck 8 . It defaults to sixty seconds to allow large applications such as the X server to start before disk I/O bandwidth is monopolized by .Xr fsck 8 . .It Va netfs_types .Pq Vt str List of file system types that are network-based. This list should generally not be modified by end users. Use .Va extra_netfs_types instead. .It Va extra_netfs_types .Pq Vt str If set to something other than .Dq Li NO (the default), this variable extends the list of file system types for which automatic mounting at startup by .Xr rc 8 should be delayed until the network is initialized. It should contain a whitespace-separated list of network file system descriptor pairs, each consisting of a file system type as passed to .Xr mount 8 and a human-readable, one-word description, joined with a colon .Pq Ql \&: . Extending the default list in this way is only necessary when third party file system types are used. .It Va syslogd_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr syslogd 8 daemon. .It Va syslogd_program .Pq Vt str Path to .Xr syslogd 8 (default .Pa /usr/sbin/syslogd ) . .It Va syslogd_flags .Pq Vt str If .Va syslogd_enable is set to .Dq Li YES , these are the flags to pass to .Xr syslogd 8 . .It Va inetd_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr inetd 8 daemon. .It Va inetd_program .Pq Vt str Path to .Xr inetd 8 (default .Pa /usr/sbin/inetd ) . .It Va inetd_flags .Pq Vt str If .Va inetd_enable is set to .Dq Li YES , these are the flags to pass to .Xr inetd 8 . .It Va named_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr named 8 daemon. .It Va named_program .Pq Vt str Path to .Xr named 8 (default .Pa /usr/sbin/named ) . .It Va named_flags .Pq Vt str If .Va named_enable is set to .Dq Li YES , these are the flags to pass to .Xr named 8 . .It Va named_pidfile .Pq Vt str This is the default path to the .Xr named 8 daemon's PID file. This must match the location in .Xr named.conf 5 . .It Va named_uid .Pq Vt str -The user that the named process should be run as. +The user that the +.Xr named 8 +process should be run as. .It Va named_chrootdir .Pq Vt str The root directory for a name server run in a .Xr chroot 8 environment (default .Pa /var/named ) . If left empty .Xr named 8 will not be run in a .Xr chroot 8 environment. .It Va named_chroot_autoupdate .Pq Vt bool Set to .Dq Li NO to disable automatic update of the .Xr chroot 8 environment. .It Va named_symlink_enable .Pq Vt bool Set to .Dq Li NO to disable symlinking of daemon's PID file into the .Xr chroot 8 environment. .It Va kerberos5_server_enable .Pq Vt bool Set to .Dq Li YES to start a Kerberos 5 authentication server at boot time. .It Va kerberos5_server .Pq Vt str If .Va kerberos5_server_enable is set to .Dq Li YES this is the path to Kerberos 5 Authentication Server. .It Va kerberos5_server_flags .Pq Vt str Empty by default. This variable contains additional flags to be passed to the Kerberos 5 authentication server. .It Va kadmind5_server_enable .Pq Vt bool Set to .Dq Li YES to start .Xr kadmind 8 , the Kerberos 5 Administration Daemon; set to .Dq Li NO on a slave server. .It Va kadmind5_server .Pq Vt str If .Va kadmind5_server_enable is set to .Dq Li YES this is the path to Kerberos 5 Administration Daemon. .It Va kpasswdd_server_enable .Pq Vt bool Set to .Dq Li YES to start .Xr kpasswdd 8 , the Kerberos 5 Password-Changing Daemon; set to .Dq Li NO on a slave server. .It Va kpasswdd_server .Pq Vt str If .Va kpasswdd_server_enable is set to .Dq Li YES this is the path to Kerberos 5 Password-Changing Daemon. .It Va rwhod_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr rwhod 8 daemon at boot time. .It Va rwhod_flags .Pq Vt str If .Va rwhod_enable is set to .Dq Li YES , these are the flags to pass to it. .It Va amd_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr amd 8 daemon at boot time. .It Va amd_flags .Pq Vt str If .Va amd_enable is set to .Dq Li YES , these are the flags to pass to it. See the .Xr amd 8 manpage for more information. .It Va amd_map_program .Pq Vt str If set, the specified program is run to get the list of .Xr amd 8 maps. For example, if the .Xr amd 8 maps are stored in NIS, one can set this to run .Xr ypcat 1 to get a list of .Xr amd 8 maps from the .Pa amd.master NIS map. .It Va update_motd .Pq Vt bool If set to .Dq Li YES , .Pa /etc/motd will be updated at boot time to reflect the kernel release being run. If set to .Dq Li NO , .Pa /etc/motd will not be updated. .It Va nfs_client_enable .Pq Vt bool If set to .Dq Li YES , run the NFS client daemons at boot time. .It Va nfs_access_cache .Pq Vt int If .Va nfs_client_enable is set to .Dq Li YES , this can be set to .Dq Li 0 to disable NFS ACCESS RPC caching, or to the number of seconds for which NFS ACCESS results should be cached. A value of 2-10 seconds will substantially reduce network traffic for many NFS operations. .It Va nfs_server_enable .Pq Vt bool If set to .Dq Li YES , run the NFS server daemons at boot time. .It Va nfs_server_flags .Pq Vt str If .Va nfs_server_enable is set to .Dq Li YES , these are the flags to pass to the .Xr nfsd 8 daemon. .It Va mountd_enable .Pq Vt bool If set to .Dq Li YES , and no .Va nfs_server_enable is set, start .Xr mountd 8 , but not .Xr nfsd 8 daemon. It is commonly needed to run CFS without real NFS used. .It Va mountd_flags .Pq Vt str If .Va mountd_enable is set to .Dq Li YES , these are the flags to pass to the .Xr mountd 8 daemon. .It Va weak_mountd_authentication .Pq Vt bool If set to .Dq Li YES , allow services like PCNFSD to make non-privileged mount requests. .It Va nfs_reserved_port_only .Pq Vt bool If set to .Dq Li YES , provide NFS services only on a secure port. .It Va nfs_bufpackets .Pq Vt int If set to a number, indicates the number of packets worth of socket buffer space to reserve on an NFS client. The kernel default is typically 4. Using a higher number may be useful on gigabit networks to improve performance. The minimum value is 2 and the maximum is 64. .It Va rpc_lockd_enable .Pq Vt bool If set to .Dq Li YES and also an NFS server or client, run .Xr rpc.lockd 8 at boot time. .It Va rpc_statd_enable .Pq Vt bool If set to .Dq Li YES and also an NFS server or client, run .Xr rpc.statd 8 at boot time. .It Va rpcbind_program .Pq Vt str Path to .Xr rpcbind 8 (default .Pa /usr/sbin/rpcbind ) . .It Va rpcbind_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr rpcbind 8 service at boot time. .It Va rpcbind_flags .Pq Vt str If .Va rpcbind_enable is set to .Dq Li YES , these are the flags to pass to the .Xr rpcbind 8 daemon. .It Va keyserv_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr keyserv 8 daemon on boot for running Secure RPC. .It Va keyserv_flags .Pq Vt str If .Va keyserv_enable is set to .Dq Li YES , these are the flags to pass to .Xr keyserv 8 daemon. .It Va pppoed_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr pppoed 8 daemon at boot time to provide PPP over Ethernet services. -.It Va pppoed_ Ns Ar provider +.It Va pppoed_ Ns Aq Ar provider .Pq Vt str .Xr pppoed 8 listens to requests to this .Ar provider and ultimately runs .Xr ppp 8 with a .Ar system argument of the same name. .It Va pppoed_flags .Pq Vt str Additional flags to pass to .Xr pppoed 8 . .It Va pppoed_interface .Pq Vt str The network interface to run .Xr pppoed 8 on. This is mandatory when .Va pppoed_enable is set to .Dq Li YES . .It Va timed_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr timed 8 service at boot time. This command is intended for networks of machines where a consistent .Dq "network time" for all hosts must be established. This is often useful in large NFS environments where time stamps on files are expected to be consistent network-wide. .It Va timed_flags .Pq Vt str If .Va timed_enable is set to .Dq Li YES , these are the flags to pass to the .Xr timed 8 service. .It Va ntpdate_enable .Pq Vt bool If set to .Dq Li YES , run .Xr ntpdate 8 at system startup. This command is intended to synchronize the system clock only .Em once from some standard reference. An option to set this up initially (from a list of known servers) is also provided by the .Xr sysinstall 8 program when the system is first installed. .It Va ntpdate_config +.Pq Vt str Configuration file for .Xr ntpdate 8 . -.Pq Vt str -(default -.Pa /etc/ntp.conf ). +Default +.Pa /etc/ntp.conf . .It Va ntpdate_hosts .Pq Vt str A whitespace-separated list of NTP servers to synchronize with at startup. The default is to use the servers listed in .Va ntpdate_config , if that file exists. .It Va ntpdate_program .Pq Vt str Path to .Xr ntpdate 8 (default .Pa /usr/sbin/ntpdate ) . .It Va ntpdate_flags .Pq Vt str If .Va ntpdate_enable is set to .Dq Li YES , these are the flags to pass to the .Xr ntpdate 8 command (typically a hostname). .It Va ntpd_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr ntpd 8 command at boot time. .It Va ntpd_program .Pq Vt str Path to .Xr ntpd 8 (default .Pa /usr/sbin/ntpd ) . .It Va ntpd_config .Pq Vt str Path to .Xr ntpd 8 configuration file. -(default -.Pa /etc/ntp.conf ) . +Default +.Pa /etc/ntp.conf . .It Va ntpd_flags .Pq Vt str If .Va ntpd_enable is set to .Dq Li YES , these are the flags to pass to the .Xr ntpd 8 daemon. .It Va ntpd_sync_on_start .Pq Vt bool If set to .Dq Li YES , .Xr ntpd 8 is run with the .Fl g flag, which syncs the system's clock on startup. See .Xr ntpd 8 for more information regarding the .Fl g option. This is a preferred alternative to using .Xr ntpdate 8 or specifying the .Va ntpdate_enable variable. .It Va nis_client_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr ypbind 8 service at system boot time. .It Va nis_client_flags .Pq Vt str If .Va nis_client_enable is set to .Dq Li YES , these are the flags to pass to the .Xr ypbind 8 service. .It Va nis_ypset_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr ypset 8 daemon at system boot time. .It Va nis_ypset_flags .Pq Vt str If .Va nis_ypset_enable is set to .Dq Li YES , these are the flags to pass to the .Xr ypset 8 daemon. .It Va nis_server_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr ypserv 8 daemon at system boot time. .It Va nis_server_flags .Pq Vt str If .Va nis_server_enable is set to .Dq Li YES , these are the flags to pass to the .Xr ypserv 8 daemon. .It Va nis_ypxfrd_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr rpc.ypxfrd 8 daemon at system boot time. .It Va nis_ypxfrd_flags .Pq Vt str If .Va nis_ypxfrd_enable is set to .Dq Li YES , these are the flags to pass to the .Xr rpc.ypxfrd 8 daemon. .It Va nis_yppasswdd_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr rpc.yppasswdd 8 daemon at system boot time. .It Va nis_yppasswdd_flags .Pq Vt str If .Va nis_yppasswdd_enable is set to .Dq Li YES , these are the flags to pass to the .Xr rpc.yppasswdd 8 daemon. .It Va rpc_ypupdated_enable .Pq Vt bool If set to .Dq Li YES , run the .Nm rpc.ypupdated daemon at system boot time. .It Va bsnmpd_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr bsnmpd 1 daemon at system boot time. Be sure to understand the security implications of running SNMP daemon on your host. .It Va bsnmpd_flags .Pq Vt str If .Va bsnmpd_enable is set to .Dq Li YES , these are the flags to pass to the .Xr bsnmpd 1 daemon. .It Va defaultrouter .Pq Vt str If not set to .Dq Li NO , create a default route to this host name or IP address (use an IP address if this router is also required to get to the name server!). .It Va ipv6_defaultrouter .Pq Vt str The IPv6 equivalent of .Va defaultrouter . .It Va static_routes .Pq Vt str Set to the list of static routes that are to be added at system boot time. If not set to .Dq Li NO then for each whitespace separated .Ar element in the value, a .Va route_ Ns Aq Ar element variable is assumed to exist whose contents will later be passed to a .Dq Nm route Cm add operation. For example: .Bd -literal static_routes="mcast gif0local" route_mcast="-net 224.0.0.0/4 -iface gif0" route_gif0local="-host 169.254.1.1 -iface lo0" .Ed .It Va ipv6_static_routes .Pq Vt str The IPv6 equivalent of .Va static_routes . If not set to .Dq Li NO then for each whitespace separated .Ar element in the value, a .Va ipv6_route_ Ns Aq Ar element variable is assumed to exist whose contents will later be passed to a .Dq Nm route Cm add Fl inet6 operation. .It Va natm_static_routes .Pq Vt str The .Xr natmip 4 equivalent of .Va static_routes . If not empty then for each whitespace separated .Ar element in the value, a .Va route_ Ns Aq Ar element variable is assumed to exist whose contents will later be passed to a .Dq Nm atmconfig Cm natm Cm add operation. .It Va gateway_enable .Pq Vt bool If set to .Dq Li YES , configure host to act as an IP router, e.g.\& to forward packets between interfaces. .It Va ipv6_gateway_enable .Pq Vt bool The IPv6 equivalent of .Va gateway_enable . .It Va router_enable .Pq Vt bool If set to .Dq Li YES , run a routing daemon of some sort, based on the settings of .Va router and .Va router_flags . .It Va ipv6_router_enable .Pq Vt bool The IPv6 equivalent of .Va router_enable . If set to .Dq Li YES , run a routing daemon of some sort, based on the settings of .Va ipv6_router and .Va ipv6_router_flags . .It Va router .Pq Vt str If .Va router_enable is set to .Dq Li YES , this is the name of the routing daemon to use. .It Va ipv6_router .Pq Vt str The IPv6 equivalent of .Va router . .It Va router_flags .Pq Vt str If .Va router_enable is set to .Dq Li YES , these are the flags to pass to the routing daemon. .It Va ipv6_router_flags .Pq Vt str The IPv6 equivalent of .Va router_flags . .It Va mrouted_enable .Pq Vt bool If set to .Dq Li YES , run the multicast routing daemon, .Xr mrouted 8 . .It Va mroute6d_enable .Pq Vt bool The IPv6 equivalent of .Va mrouted_enable . If set to .Dq Li YES , run the IPv6 multicast routing daemon. Note that no IPv6 multicast routing daemon is included in the .Fx base system but .Xr pim6dd 8 can be installed from the .Fx Ports Collection. .It Va mrouted_flags .Pq Vt str If .Va mrouted_enable is set to .Dq Li YES , these are the flags to pass to the .Xr mrouted 8 daemon. .It Va mroute6d_flags .Pq Vt str The IPv6 equivalent of .Va mrouted_flags . If .Va mroute6d_enable is set to .Dq Li YES , these are the flags passed to the IPv6 multicast routing daemon. .It Va mroute6d_program .Pq Vt str If .Va mroute6d_enable is set to .Dq Li YES , this is the path to the IPv6 multicast routing daemon. .It Va rtadvd_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr rtadvd 8 daemon at boot time. .Xr rtadvd 8 will only run if .Va ipv6_gateway_enable is also set to .Dq Li YES . The .Xr rtadvd 8 utility sends router advertisement packets to the interfaces specified in .Va rtadvd_interfaces and should only be enabled with great care. You may want to fine-tune .Xr rtadvd.conf 5 . .It Va rtadvd_interfaces .Pq Vt str If .Va rtadvd_enable is set to .Dq Li YES this is the list of interfaces to use. .It Va ipxgateway_enable .Pq Vt bool If set to .Dq Li YES , enable the routing of IPX traffic. .It Va ipxrouted_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr IPXrouted 8 daemon at system boot time. .It Va ipxrouted_flags .Pq Vt str If .Va ipxrouted_enable is set to .Dq Li YES , these are the flags to pass to the .Xr IPXrouted 8 daemon. .It Va arpproxy_all .Pq Vt bool If set to .Dq Li YES , enable global proxy ARP. .It Va forward_sourceroute .Pq Vt bool If set to .Dq Li YES and .Va gateway_enable is also set to .Dq Li YES , source-routed packets are forwarded. .It Va accept_sourceroute .Pq Vt bool If set to .Dq Li YES , the system will accept source-routed packets directed at it. .It Va rarpd_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr rarpd 8 daemon at system boot time. .It Va rarpd_flags .Pq Vt str If .Va rarpd_enable is set to .Dq Li YES , these are the flags to pass to the .Xr rarpd 8 daemon. .It Va bootparamd_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr bootparamd 8 daemon at system boot time. .It Va bootparamd_flags .Pq Vt str If .Va bootparamd_enable is set to .Dq Li YES , these are the flags to pass to the .Xr bootparamd 8 daemon. .It Va stf_interface_ipv4addr .Pq Vt str If not set to .Dq Li NO , this is the local IPv4 address for 6to4 (IPv6 over IPv4 tunneling interface). Specify this entry to enable the 6to4 interface. .It Va stf_interface_ipv4plen .Pq Vt int Prefix length for 6to4 IPv4 addresses, to limit peer address range. An effective value is 0-31. .It Va stf_interface_ipv6_ifid .Pq Vt str IPv6 interface ID for .Xr stf 4 . This can be set to .Dq Li AUTO . .It Va stf_interface_ipv6_slaid .Pq Vt str IPv6 Site Level Aggregator for .Xr stf 4 . .It Va ipv6_faith_prefix .Pq Vt str If not set to .Dq Li NO , this is the faith prefix to enable a FAITH IPv6-to-IPv4 TCP translator. You also need .Xr faithd 8 setup. .It Va ipv6_ipv4mapping .Pq Vt bool If set to .Dq Li YES this enables IPv4 mapped IPv6 address communication (like .Li ::ffff:a.b.c.d ) . .It Va atm_enable .Pq Vt bool Set to .Dq Li YES to enable the configuration of ATM interfaces at system boot time. For all of the ATM variables described below, please refer to the .Xr atm 8 manual page for further details on the available command parameters. Also refer to the files in .Pa /usr/share/examples/atm for more detailed configuration information. .It Va atm_load .Pq Vt str This is a list of physical ATM interface drivers to load. Typical values are .Dq Li hfa_pci and/or .Dq Li hea_pci . .It Va atm_netif_ Ns Aq Ar intf .Pq Vt str For the ATM physical interface .Ar intf , this variable defines the name prefix and count for the ATM network interfaces to be created. The value will be passed as the parameters of an .Dq Nm atm Cm "set netif" Ar intf command. .It Va atm_sigmgr_ Ns Aq Ar intf .Pq Vt str For the ATM physical interface .Ar intf , this variable defines the ATM signalling manager to be used. The value will be passed as the parameters of an .Dq Nm atm Cm attach Ar intf command. .It Va atm_prefix_ Ns Aq Ar intf .Pq Vt str For the ATM physical interface .Ar intf , this variable defines the NSAP prefix for interfaces using a UNI signalling manager. If set to .Dq Li ILMI , the prefix will automatically be set via the .Xr ilmid 8 daemon. Otherwise, the value will be passed as the parameters of an .Dq Nm atm Cm "set prefix" Ar intf command. .It Va atm_macaddr_ Ns Aq Ar intf .Pq Vt str For the ATM physical interface .Ar intf , this variable defines the MAC address for interfaces using a UNI signalling manager. If set to .Dq Li NO , the hardware MAC address contained in the ATM interface card will be used. Otherwise, the value will be passed as the parameters of an .Dq Nm atm Cm "set mac" Ar intf command. .It Va atm_arpserver_ Ns Aq Ar netif .Pq Vt str For the ATM network interface .Ar netif , this variable defines the ATM address for a host which is to provide ATMARP service. This variable is only applicable to interfaces using a UNI signalling manager. If set to .Dq Li local , this host will become an ATMARP server. The value will be passed as the parameters of an .Dq Nm atm Cm "set arpserver" Ar netif command. .It Va atm_scsparp_ Ns Aq Ar netif .Pq Vt bool If set to .Dq Li YES , SCSP/ATMARP service for the network interface .Ar netif will be initiated using the .Xr scspd 8 and .Xr atmarpd 8 daemons. This variable is only applicable if .Va atm_arpserver_ Ns Aq Ar netif is set to .Dq Li local . .It Va atm_pvcs .Pq Vt str Set to the list of ATM PVCs to be added at system boot time. For each whitespace separated .Ar element in the value, an .Va atm_pvc_ Ns Aq Ar element variable is assumed to exist. The value of each of these variables will be passed as the parameters of an .Dq Nm atm Cm "add pvc" command. .It Va atm_arps .Pq Vt str Set to the list of permanent ATM ARP entries to be added at system boot time. For each whitespace separated .Ar element in the value, an .Va atm_arp_ Ns Aq Ar element variable is assumed to exist. The value of each of these variables will be passed as the parameters of an .Dq Nm atm Cm "add arp" command. .It Va natm_interfaces .Pq Vt str Set to the list of .Xr natm 4 interfaces that will also be used for HARP through .Xr harp 4 . If this list is not empty all interfaces in the list will be brought up with .Xr ifconfig 8 and .Xr harp 4 will be loaded. For this to work the interface drivers must be either compiled into the kernel or must reside on the root partition. .It Va keybell .Pq Vt str The keyboard bell sound. Set to .Dq Li normal , .Dq Li visual , .Dq Li off , or .Dq Li NO if the default behavior is desired. For details, refer to the .Xr kbdcontrol 1 manpage. .It Va keyboard .Pq Vt str If set to a non-null string, the virtual console's keyboard input is set to this device. .It Va keymap .Pq Vt str If set to .Dq Li NO , no keymap is installed, otherwise the value is used to install the keymap file in .Pa /usr/share/syscons/keymaps/ Ns Ao Ar value Ac Ns Pa .kbd . .It Va keyrate .Pq Vt str The keyboard repeat speed. Set to .Dq Li slow , .Dq Li normal , .Dq Li fast , or .Dq Li NO if the default behavior is desired. .It Va keychange .Pq Vt str If not set to .Dq Li NO , attempt to program the function keys with the value. The value should be a single string of the form: .Dq Ar funkey_number new_value Op Ar funkey_number new_value ... . .It Va cursor .Pq Vt str Can be set to the value of .Dq Li normal , .Dq Li blink , .Dq Li destructive , or .Dq Li NO to set the cursor behavior explicitly or choose the default behavior. .It Va scrnmap .Pq Vt str If set to .Dq Li NO , no screen map is installed, otherwise the value is used to install the screen map file in .Pa /usr/share/syscons/scrnmaps/ Ns Aq Ar value . .It Va font8x16 .Pq Vt str If set to .Dq Li NO , the default 8x16 font value is used for screen size requests, otherwise the value in .Pa /usr/share/syscons/fonts/ Ns Aq Ar value is used. .It Va font8x14 .Pq Vt str If set to .Dq Li NO , the default 8x14 font value is used for screen size requests, otherwise the value in .Pa /usr/share/syscons/fonts/ Ns Aq Ar value is used. .It Va font8x8 .Pq Vt str If set to .Dq Li NO , the default 8x8 font value is used for screen size requests, otherwise the value in .Pa /usr/share/syscons/fonts/ Ns Aq Ar value is used. .It Va blanktime .Pq Vt int If set to .Dq Li NO , the default screen blanking interval is used, otherwise it is set to .Ar value seconds. .It Va saver .Pq Vt str If not set to .Dq Li NO , this is the actual screen saver to use .Li ( blank , snake , daemon , etc). .It Va moused_nondefault_enable .Pq Vt str If set to .Dq Li NO , the mouse device specified on the command line is not automatically treated as enabled by the .Pa /etc/rc.d/moused script. Having this variable set to .Dq Li YES allows a .Xr usb 4 mouse, for example, to be enabled as soon as it is plugged in. .It Va moused_enable .Pq Vt str If set to .Dq Li YES , the .Xr moused 8 daemon is started for doing cut/paste selection on the console. .It Va moused_type .Pq Vt str This is the protocol type of the mouse connected to this host. This variable must be set if .Va moused_enable is set to .Dq Li YES . The .Xr moused 8 daemon is able to detect the appropriate mouse type automatically in many cases. Set this variable to .Dq Li auto to let the daemon detect it, or select one from the following list if the automatic detection fails. .Pp If the mouse is attached to the PS/2 mouse port, choose .Dq Li auto or .Dq Li ps/2 , regardless of the brand and model of the mouse. Likewise, if the mouse is attached to the bus mouse port, choose .Dq Li auto or .Dq Li busmouse . All other protocols are for serial mice and will not work with the PS/2 and bus mice. If this is a USB mouse, .Dq Li auto is the only protocol type which will work. .Pp .Bl -tag -width ".Li x10mouseremote" -compact .It Li microsoft Microsoft mouse (serial) .It Li intellimouse Microsoft IntelliMouse (serial) .It Li mousesystems Mouse systems Corp.\& mouse (serial) .It Li mmseries MM Series mouse (serial) .It Li logitech Logitech mouse (serial) .It Li busmouse A bus mouse .It Li mouseman Logitech MouseMan and TrackMan (serial) .It Li glidepoint ALPS GlidePoint (serial) .It Li thinkingmouse Kensington ThinkingMouse (serial) .It Li ps/2 PS/2 mouse .It Li mmhittab MM HitTablet (serial) .It Li x10mouseremote X10 MouseRemote (serial) .It Li versapad Interlink VersaPad (serial) .El .Pp Even if the mouse is not in the above list, it may be compatible with one in the list. Refer to the manual page for .Xr moused 8 for compatibility information. .Pp It should also be noted that while this is enabled, any other client of the mouse (such as an X server) should access the mouse through the virtual mouse device, .Pa /dev/sysmouse , and configure it as a .Dq Li sysmouse type mouse, since all mouse data is converted to this single canonical format when using .Xr moused 8 . If the client program does not support the .Dq Li sysmouse type, specify the .Dq Li mousesystems type. It is the second preferred type. .It Va moused_port .Pq Vt str If .Va moused_enable is set to .Dq Li YES , this is the actual port the mouse is on. It might be .Pa /dev/cuad0 for a COM1 serial mouse, .Pa /dev/psm0 for a PS/2 mouse or .Pa /dev/mse0 for a bus mouse, for example. .It Va moused_flags .Pq Vt str If .Va moused_type is set, these are the additional flags to pass to the .Xr moused 8 daemon. .It Va mousechar_start .Pq Vt int If set to .Dq Li NO , the default mouse cursor character range .Li 0xd0 Ns - Ns Li 0xd3 is used, otherwise the range start is set to .Ar value character, see .Xr vidcontrol 1 . Use if the default range is occupied in the language code table. .It Va allscreens_flags .Pq Vt str If set, .Xr vidcontrol 1 is run with these options for each of the virtual terminals .Pq Pa /dev/ttyv* . For example, .Dq Fl m Cm on will enable the mouse pointer on all virtual terminals if .Va moused_enable is set to .Dq Li YES . .It Va allscreens_kbdflags .Pq Vt str If set, .Xr kbdcontrol 1 is run with these options for each of the virtual terminals .Pq Pa /dev/ttyv* . For example, .Dq Fl h Li 200 will set the .Xr syscons 4 scrollback (history) buffer to 200 lines. .It Va cron_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr cron 8 daemon at system boot time. .It Va cron_program .Pq Vt str Path to .Xr cron 8 (default .Pa /usr/sbin/cron ) . .It Va cron_flags .Pq Vt str If .Va cron_enable is set to .Dq Li YES , these are the flags to pass to .Xr cron 8 . .It Va cron_dst .Pq Vt bool If set to .Dq Li YES , enable the special handling of transitions to and from the Daylight Saving Time in .Xr cron 8 (equivalent to using the flag .Fl s ) . .It Va lpd_program .Pq Vt str Path to .Xr lpd 8 (default .Pa /usr/sbin/lpd ) . .It Va lpd_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr lpd 8 daemon at system boot time. .It Va lpd_flags .Pq Vt str If .Va lpd_enable is set to .Dq Li YES , these are the flags to pass to the .Xr lpd 8 daemon. .It Va chkprintcap_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr chkprintcap 8 command before starting the .Xr lpd 8 daemon. .It Va chkprintcap_flags .Pq Vt str If .Va lpd_enable and .Va chkprintcap_enable are set to .Dq Li YES , these are the flags to pass to the .Xr chkprintcap 8 program. The default is .Dq Li -d , which causes missing directories to be created. .It Va mta_start_script .Pq Vt str This variable specifies the full path to the script to run to start a mail transfer agent. The default is .Pa /etc/rc.sendmail . The .Va sendmail_* variables which .Pa /etc/rc.sendmail uses are documented in the .Xr rc.sendmail 8 manual page. .It Va dumpdev .Pq Vt str Indicates the device (usually a swap partition) to which a crash dump should be written in the event of a system crash. If the value of this variable is .Dq Li AUTO , the first suitable swap device listed in .Pa /etc/fstab will be used as dump device. Otherwise, the value of this variable is passed as the argument to .Xr dumpon 8 . To disable crash dumps, set this variable to .Dq Li NO . .It Va dumpdir .Pq Vt str When the system reboots after a crash and a crash dump is found on the device specified by the .Va dumpdev variable, .Xr savecore 8 will save that crash dump and a copy of the kernel to the directory specified by the .Va dumpdir variable. The default value is .Pa /var/crash . Set to .Dq Li NO to not run .Xr savecore 8 at boot time when .Va dumpdir is set. .It Va savecore_flags .Pq Vt str If crash dumps are enabled, these are the flags to pass to the .Xr savecore 8 utility. .It Va enable_quotas .Pq Vt bool Set to .Dq Li YES to turn on user disk quotas on system startup via the .Xr quotaon 8 command. .It Va check_quotas .Pq Vt bool Set to .Dq Li YES to enable user disk quota checking via the .Xr quotacheck 8 command. .It Va accounting_enable .Pq Vt bool Set to .Dq Li YES to enable system accounting through the .Xr accton 8 facility. .It Va ibcs2_enable .Pq Vt bool Set to .Dq Li YES to enable iBCS2 (SCO) binary emulation at system initial boot time. .It Va ibcs2_loaders .Pq Vt str If not set to .Dq Li NO and if .Va ibcs2_enable is set to .Dq Li YES , this specifies a list of additional iBCS2 loaders to enable. .It Va linux_enable .Pq Vt bool Set to .Dq Li YES to enable Linux/ELF binary emulation at system initial boot time. .It Va svr4_enable .Pq Vt bool If set to .Dq Li YES , enable SysVR4 emulation at boot time. .It Va sysvipc_enable .Pq Vt bool If set to .Dq Li YES , load System V IPC primitives at boot time. .It Va clear_tmp_enable .Pq Vt bool Set to .Dq Li YES to have .Pa /tmp cleaned at startup. .It Va clear_tmp_X .Pq Vt bool Set to .Dq Li NO to disable removing of X11 lock files, and the removal and (secure) recreation of the various socket directories for X11 related programs. .It Va ldconfig_paths .Pq Vt str Set to the list of shared library paths to use with .Xr ldconfig 8 . NOTE: .Pa /usr/lib will always be added first, so it need not appear in this list. .It Va ldconfig32_paths .Pq Vt str Set to the list of 32-bit compatibility shared library paths to use with .Xr ldconfig 8 . .It Va ldconfig_paths_aout .Pq Vt str Set to the list of shared library paths to use with .Xr ldconfig 8 legacy .Xr a.out 5 support. .It Va ldconfig_insecure .Pq Vt bool The .Xr ldconfig 8 utility normally refuses to use directories which are writable by anyone except root. Set this variable to .Dq Li YES to disable that security check during system startup. .It Va ldconfig_local_dirs .Pq Vt str Set to the list of local .Xr ldconfig 8 directories. The names of all files in the directories listed will be passed as arguments to .Xr ldconfig 8 . .It Va ldconfig_local32_dirs .Pq Vt str Set to the list of local 32-bit compatibility .Xr ldconfig 8 directories. The names of all files in the directories listed will be passed as arguments to -.Xr ldconfig 8 -.Fl 32 . +.Dq Nm ldconfig Fl 32 . .It Va kern_securelevel_enable .Pq Vt bool Set to .Dq Li YES to set the kernel security level at system startup. .It Va kern_securelevel .Pq Vt int The kernel security level to set at startup. The allowed range of .Ar value ranges from \-1 (the compile time default) to 3 (the most secure). See .Xr init 8 for the list of possible security levels and their effect on system operation. .It Va sshd_program .Pq Vt str Path to the SSH server program .Pa ( /usr/sbin/sshd is the default). .It Va sshd_enable .Pq Vt bool Set to .Dq Li YES to start .Xr sshd 8 at system boot time. .It Va sshd_flags .Pq Vt str If .Va sshd_enable is set to .Dq Li YES , these are the flags to pass to the .Xr sshd 8 daemon. .It Va ftpd_program .Pq Vt str Path to the FTP server program .Pa ( /usr/libexec/ftpd is the default). .It Va ftpd_enable .Pq Vt bool Set to .Dq Li YES to start .Xr ftpd 8 as a stand-alone daemon at system boot time. .It Va ftpd_flags .Pq Vt str If .Va ftpd_enable is set to .Dq Li YES , these are the additional flags to pass to the .Xr ftpd 8 daemon. .It Va watchdogd_enable .Pq Vt bool If set to .Dq Li YES , start the .Xr watchdogd 8 daemon at boot time. This requires that the kernel have been compiled with a .Xr watchdog 4 compatible device. .It Va watchdogd_flags .Pq Vt str If .Va watchdogd_enable is set to .Dq Li YES , these are the flags passed to the .Xr watchdogd 8 daemon. .It Va performance_cx_lowest .Pq Vt str CPU idle state to use while on AC power. The string .Dq Li LOW indicates that .Xr acpi 4 should use the lowest power state available while .Dq Li HIGH indicates that the lowest latency state (less power savings) should be used. .It Va performance_cpu_freq .Pq Vt str CPU clock frequency to use while on AC power. The string .Dq Li LOW indicates that .Xr cpufreq 4 should use the lowest frequency available while .Dq Li HIGH indicates that the highest frequency (less power savings) should be used. .It Va economy_cx_lowest .Pq Vt str CPU idle state to use when off AC power. The string .Dq Li LOW indicates that .Xr acpi 4 should use the lowest power state available while .Dq Li HIGH indicates that the lowest latency state (less power savings) should be used. .It Va economy_cpu_freq .Pq Vt str CPU clock frequency to use when off AC power. The string .Dq Li LOW indicates that .Xr cpufreq 4 should use the lowest frequency available while .Dq Li HIGH indicates that the highest frequency (less power savings) should be used. .It Va jail_enable .Pq Vt bool If set to .Dq Li NO , any configured jails will not be started. .It Va jail_list .Pq Vt str A space separated list of names for jails. This is purely a configuration aid to help identify and configure multiple jails. The names specified in this list will be used to identify settings common to an instance of a jail. Assuming that the jail in question was named .Li vjail , you would have the following dependent variables: .Bd -literal jail_vjail_hostname="jail.example.com" jail_vjail_ip="192.168.1.100" jail_vjail_rootdir="/var/jails/vjail/root" .Ed .Pp .It Va jail_flags .Pq Vt str Unset by default. When set, use as default value for .Va jail_ Ns Ao Ar jname Ac Ns Va _flags for every jail in .Va jail_list . .It Va jail_interface .Pq Vt str Unset by default. When set, use as default value for .Va jail_ Ns Ao Ar jname Ac Ns Va _interface for every jail in .Va jail_list . .It Va jail_fstab .Pq Vt str Unset by default. When set, use as default value for .Va jail_ Ns Ao Ar jname Ac Ns Va _fstab for every jail in .Va jail_list . .It Va jail_mount_enable .Pq Vt bool Set to .Dq Li NO by default. When set to .Dq Li YES , sets .Va jail_ Ns Ao Ar jname Ac Ns Va _mount_enable -to YES by default for every jail in +to +.Dq Li YES +by default for every jail in .Va jail_list . .It Va jail_devfs_ruleset .Pq Vt str Unset by default. When set, sets .Va jail_ Ns Ao Ar jname Ac Ns Va _devfs_ruleset to given value for every jail in .Va jail_list . .It Va jail_devfs_enable .Pq Vt bool Set to .Dq Li NO by default. When set to .Dq Li YES , sets .Va jail_ Ns Ao Ar jname Ac Ns Va _devfs_enable -to YES by default for every jail in +to +.Dq Li YES +by default for every jail in .Va jail_list . .It Va jail_fdescfs_enable .Pq Vt bool Set to .Dq Li NO by default. When set to .Dq Li YES , sets .Va jail_ Ns Ao Ar jname Ac Ns Va _fdescfs_enable -to YES by default for every jail in +to +.Dq Li YES +by default for every jail in .Va jail_list . .It Va jail_procfs_enable .Pq Vt bool Set to .Dq Li NO by default. When set to .Dq Li YES , sets .Va jail_ Ns Ao Ar jname Ac Ns Va _fdescfs_enable -to YES by default for every jail in +to +.Dq Li YES +by default for every jail in .Va jail_list . .It Va jail_exec_start .Pq Vt str Unset by default. When set, use as default value for .Va jail_ Ns Ao Ar jname Ac Ns Va _exec_start -for every jail in +for every jail in .Va jail_list . .It Va jail_exec_afterstart Ns Aq Ar N .Pq Vt str Unset by default. When set, use as default value for .Va jail_ Ns Ao Ar jname Ac Ns Va _exec_afterstart Ns Aq Ar N for every jail in .Va jail_list . .It Va jail_exec_stop Unset by default. When set, use as default value for .Va jail_ Ns Ao Ar jname Ac Ns Va _exec_stop for every jail in .Va jail_list . .It Va jail_ Ns Ao Ar jname Ac Ns Va _rootdir .Pq Vt str Unset by default. Set to the root directory used by jail .Va jname . .It Va jail_ Ns Ao Ar jname Ac Ns Va _hostname .Pq Vt str Unset by default. Set to the fully qualified domain name (FQDN) assigned to jail .Va jname . .It Va jail_ Ns Ao Ar jname Ac Ns Va _ip .Pq Vt str Unset by default. Set to the IP address assigned to jail .Va jname . .It Va jail_ Ns Ao Ar jname Ac Ns Va _flags .Pq Vt str Set to .Dq Li -l -U root by default. These are flags to pass to .Xr jail . .It Va jail_ Ns Ao Ar jname Ac Ns Va _interface .Pq Vt str Unset by default. When set, sets the interface to use when setting IP address alias. Note that the alias is created at jail startup and removed at jail shutdown. .It Va jail_ Ns Ao Ar jname Ac Ns Va _fstab .Pq Vt str Set to -.Pa /etc/fstab. Ns Ao Ar jname Ac +.Pa /etc/fstab. Ns Aq Ar jname by default. This is the file system information file to use for jail .Va jname . .It Va jail_ Ns Ao Ar jname Ac Ns Va _mount_enable .Pq Vt bool Set to .Dq Li NO by default. When set to .Dq Li YES , mount all file systems from .Va jail_ Ns Ao Ar jname Ac Ns Va _fstab at jail startup. .It Va jail_ Ns Ao Ar jname Ac Ns Va _devfs_ruleset .Pq Vt str Unset by default. When set, defines the device file system ruleset file to use for jail .Va jname . .It Va jail_ Ns Ao Ar jname Ac Ns Va _devfs_enable .Pq Vt bool Set to .Dq Li NO by default. When set to .Dq Li YES , mount the device file system inside jail .Ar jname at jail startup. .It Va jail_ Ns Ao Ar jname Ac Ns Va _fdescfs_enable .Pq Vt bool Set to .Dq Li NO by default. When set to .Dq Li YES , mount the file-descriptor file system inside jail .Ar jname at jail startup. .It Va jail_ Ns Ao Ar jname Ac Ns Va _procfs_enable .Pq Vt bool Set to .Dq Li NO by default. When set to .Dq Li YES , mount the process file system inside jail .Ar jname at jail startup. .It Va jail_ Ns Ao Ar jname Ac Ns Va _exec_start .Pq Vt str Set to .Dq Li /bin/sh /etc/rc by default. This is the command executed at jail startup. .It Va jail_ Ns Ao Ar jname Ac Ns Va _exec_afterstart Ns Aq Ar N .Pq Vt str Unset by default. This is the command run as -.Ar N Ns +.Ar N Ns th command -after jail startup, where +after jail startup, where .Ar N is 1, 2, and so on. .It Va jail_ Ns Ao Ar jname Ac Ns Va _exec_stop .Pq Vt str Set to .Dq Li /bin/sh /etc/rc.shutdown by default. This is the command executed at jail shutdown. .It Va jail_set_hostname_allow .Pq Vt bool If set to .Dq Li NO , do not allow the root user in a jail to set its hostname. .It Va jail_socket_unixiproute_only .Pq Vt bool If set to .Dq Li YES , do not allow any sockets, besides UNIX/IP/route sockets, to be used within a jail. .It Va jail_sysvipc_allow .Pq Vt bool If set to .Dq Li YES , allow applications within a jail to use System V IPC. .\" ----- ISDN settings --------------------------------- .It Va isdn_enable .Pq Vt bool Set to .Dq Li NO by default. When set to .Dq Li YES , starts the .Xr isdnd 8 daemon at system boot time. .It Va isdn_flags .Pq Vt str Set to .Dq Fl d Ns Cm n Fl d Ns Li 0x1f9 by default. Additional flags to pass to .Xr isdnd 8 (but see .Va isdn_fsdev and .Va isdn_ttype for certain tunable parameters). .It Va isdn_ttype .Pq Vt str Set to .Dq Li cons25 by default. The terminal type of the output device when .Xr isdnd 8 operates in full-screen mode. .It Va isdn_screenflags .Pq Vt str Set to .Dq Li NO by default. The video mode for full-screen mode (only for .Xr syscons 4 console driver, see .Xr vidcontrol 1 for valid modes). .It Va isdn_fsdev .Pq Vt str Set to .Dq Li NO by default. The output device for .Xr isdnd 8 in full-screen mode (or .Dq Li NO for daemon mode). .It Va isdn_trace .Pq Vt bool Set to .Dq Li NO by default. When set to .Dq Li YES , enables the ISDN protocol trace utility .Xr isdntrace 8 at system boot time. .It Va isdn_traceflags .Pq Vt str Set to .Dq Fl f Pa /var/tmp/isdntrace0 by default. Flags for .Xr isdntrace 8 . .\" ----------------------------------------------------- .It Va harvest_interrupt .Pq Vt bool Set to .Dq Li YES to use hardware interrupts as an entropy source. Refer to .Xr random 4 for more information. .It Va harvest_ethernet .Pq Vt bool Set to .Dq Li YES to use LAN traffic as an entropy source. Refer to .Xr random 4 for more information. .It Va harvest_p_to_p .Pq Vt bool Set to .Dq Li YES to use serial line traffic as an entropy source. Refer to .Xr random 4 for more information. .It Va entropy_dir .Pq Vt str Set to .Dq Li NO to disable caching entropy via .Xr cron 8 . Otherwise set to the directory used to store entropy files in. .It Va entropy_file .Pq Vt str Set to .Dq Li NO to disable caching entropy through reboots. Otherwise set to the filename used to store cached entropy through reboots. This file should be located on the root file system to seed the .Xr random 4 device as early as possible in the boot process. .It Va entropy_save_sz .Pq Vt int Size of the entropy cache files saved by .Nm save-entropy periodically. .It Va entropy_save_num .Pq Vt int Number of entropy cache files to save by .Nm save-entropy periodically. .It Va ipsec_enable .Pq Vt bool Set to .Dq Li YES to run .Xr setkey 8 on .Va ipsec_file at boot time. .It Va ipsec_file .Pq Vt str Configuration file for .Xr setkey 8 . .It Va dmesg_enable .Pq Vt bool Set to .Dq Li YES to save .Xr dmesg 8 to .Pa /var/run/dmesg.boot on boot. .It Va rcshutdown_timeout .Pq Vt int If set, start a watchdog timer in the background which will terminate .Pa rc.shutdown if .Xr shutdown 8 has not completed within the specified time (in seconds). Notice that in addition to this soft timeout, .Xr init 8 also applies a hard timeout for the execution of .Pa rc.shutdown . This is configured via .Xr sysctl 8 variable .Va kern.init_shutdown_timeout and defaults to 120 seconds. Setting the value of .Va rcshutdown_timeout to more than 120 seconds will have no effect until the .Xr sysctl 8 variable .Va kern.init_shutdown_timeout is also increased. .It Va virecover_enable .Pq Vt bool Set to .Dq Li NO to prevent the system from trying to recover pre-maturely terminated .Xr vi 1 sessions. .It Va ugidfw_enable .Pq Vt bool Set to .Dq Li YES to load the .Xr mac_bsdextended 4 module upon system initialization and load a default ruleset file. .It Va bsdextended_script .Pq Vt str The default .Xr mac_bsdextended 4 ruleset file to load. The default value of this variable is .Pa /etc/rc.bsdextended . .It Va newsyslog_enable .Pq Vt bool If set to .Dq Li YES , run .Xr newsyslog 8 command at startup. .It Va newsyslog_flags .Pq Vt str If .Va newsyslog_enable is set to .Dq Li YES , these are the flags to pass to the .Xr newsyslog 8 program. The default is .Dq Li -CN , which causes log files flagged with a .Cm C to be created. -.It Va mdconfig_md Ns Ao Ar X Ac +.It Va mdconfig_md Ns Aq Ar X .Pq Vt str Arguments to .Xr mdconfig 8 for .Xr md 4 device .Ar X . At minimum a .Fl t Ar type must be specified and either a .Fl s Ar size for malloc or swap backed .Xr md 4 devices or a .Fl f Ar file for vnode backed .Xr md 4 devices. Note that -.Va mdconfig_md Ns Ao Ar X Ac +.Va mdconfig_md Ns Aq Ar X variables are evaluated until one variable is unset or null. .It Va mdconfig_md Ns Ao Ar X Ac Ns Va _newfs .Pq Vt str Optional arguments passed to .Xr newfs 8 to initialize .Xr md 4 device .Ar X . .It Va mdconfig_md Ns Ao Ar X Ac Ns Va _owner .Pq Vt str An ownership specification passed to .Xr chown 8 after the specified .Xr md 4 device .Ar X has been mounted. Both the .Xr md 4 device and the mount point will be changed. .It Va mdconfig_md Ns Ao Ar X Ac Ns Va _perms .Pq Vt str A mode string passed to .Xr chmod 1 after the specified .Xr md 4 device .Ar X has been mounted. Both the .Xr md 4 device and the mount point will be changed. .It Va mdconfig_md Ns Ao Ar X Ac Ns Va _files .Pq Vt str Files to be copied to the mount point of the .Xr md 4 device .Ar X after it has been mounted. .It Va mdconfig_md Ns Ao Ar X Ac Ns Va _cmd .Pq Vt str Command to execute after the specified .Xr md 4 device .Ar X has been mounted. Note that the command is passed to -.Li eval +.Ic eval and that both -.Li _dev +.Va _dev and -.Li _mp +.Va _mp variables can be used to reference respectively the .Xr md 4 device and the mount point. Assuming that the .Xr md 4 device is .Li md0 , one could set the following: .Bd -literal -mdconfig_md0_cmd="tar xfzC /var/file.tgz \\${_mp}" +mdconfig_md0_cmd="tar xfzC /var/file.tgz \e${_mp}" .Ed .It Va ramdisk_units .Pq Vt str A list of one or more ramdisk units to configure with .Xr mdconfig 8 and .Xr newfs 8 in time to be mounted from .Xr fstab 5 . Each listed unit .Ar X must specify at least a .Ar type in a .Va ramdisk_ Ns Ao Ar X Ac Ns Va _config variable. Note that this way to configure ramdisks has been deprecated -in favor of new mdconfig variables (see above). +in favor of new +.Va mdconfig_md* +variables (see above). .It Va ramdisk_ Ns Ao Ar X Ac Ns Va _config .Pq Vt str Arguments to .Xr mdconfig 8 for ramdisk .Ar X . At minimum a .Fl t Ar type must be specified, where .Ar type must be one of .Cm malloc or .Cm swap . .It Va ramdisk_ Ns Ao Ar X Ac Ns Va _newfs .Pq Vt str Optional arguments passed to .Xr newfs 8 to initialize ramdisk .Ar X . .It Va ramdisk_ Ns Ao Ar X Ac Ns Va _owner .Pq Vt str An ownership specification passed to .Xr chown 8 after the specified ramdisk unit .Ar X has been mounted. Both the .Xr md 4 device and the mount point will be changed. .It Va ramdisk_ Ns Ao Ar X Ac Ns Va _perms .Pq Vt str A mode string passed to .Xr chmod 1 after the specified ramdisk unit .Ar X has been mounted. Both the .Xr md 4 device and the mount point will be changed. .It Va autobridge_interfaces .Pq Vt str Set to the list of bridge interfaces that will have newly arriving interfaces checked against to be automatically added. If not set to .Dq Li NO then for each whitespace separated .Ar element in the value, a .Va autobridge_ Ns Aq Ar element variable is assumed to exist which has a whitespace separated list of interface names to match, these names can use wildcards. For example: .Bd -literal autobridge_interfaces="bridge0" autobridge_bridge0="tap* dc0 vlan[345]" .Ed .El .Sh FILES .Bl -tag -width ".Pa /etc/defaults/rc.conf" -compact .It Pa /etc/defaults/rc.conf .It Pa /etc/rc.conf .It Pa /etc/rc.conf.local .El .Sh SEE ALSO .Xr catman 1 , .Xr chmod 1 , .Xr gdb 1 , .Xr info 1 , .Xr kbdcontrol 1 , .Xr makewhatis 1 , .Xr sh 1 , .Xr vi 1 , .Xr vidcontrol 1 , .Xr bridge 4 , .Xr ip 4 , .Xr ipf 4 , .Xr ipfw 4 , .Xr ipnat 4 , .Xr kld 4 , .Xr pf 4 , .Xr pflog 4 , .Xr pfsync 4 , .Xr tcp 4 , .Xr udp 4 , .Xr exports 5 , .Xr ipf 5 , .Xr ipnat 5 , .Xr motd 5 , .Xr newsyslog.conf 5 , .Xr pf.conf 5 , .Xr accton 8 , .Xr amd 8 , .Xr apm 8 , .Xr atm 8 , .Xr chkprintcap 8 , .Xr chown 8 , .Xr cron 8 , .Xr dhclient 8 , .Xr ftpd 8 , .Xr geli 8 , .Xr ifconfig 8 , .Xr inetd 8 , .Xr ipf 8 , .Xr ipfw 8 , .Xr ipnat 8 , .Xr isdnd 8 , .Xr isdntrace 8 , .Xr jail 8 , .Xr kldxref 8 , .Xr lpd 8 , .Xr mdconfig 8 , .Xr mdmfs 8 , .Xr mountd 8 , .Xr moused 8 , .Xr mrouted 8 , .Xr named 8 , .Xr newfs 8 , .Xr newsyslog 8 , .Xr nfsd 8 , .Xr ntpd 8 , .Xr ntpdate 8 , .Xr pcnfsd 8 , .Xr pfctl 8 , .Xr pflogd 8 , .Xr powerd 8 , .Xr quotacheck 8 , .Xr quotaon 8 , .Xr rc 8 , .Xr rc.sendmail 8 , .Xr route 8 , .Xr routed 8 , .Xr rpcbind 8 , .Xr rpc.lockd 8 , .Xr rpc.statd 8 , .Xr rwhod 8 , .Xr savecore 8 , .Xr sshd 8 , .Xr swapon 8 , .Xr sysctl 8 , .Xr syslogd 8 , .Xr timed 8 , .Xr yp 8 , .Xr ypbind 8 , .Xr ypserv 8 , .Xr ypset 8 .Sh HISTORY The .Nm file appeared in .Fx 2.2.2 . .Sh AUTHORS .An Jordan K. Hubbard . Index: head/share/man/man8/picobsd.8 =================================================================== --- head/share/man/man8/picobsd.8 (revision 162403) +++ head/share/man/man8/picobsd.8 (revision 162404) @@ -1,644 +1,645 @@ .\" -*- nroff-fill -*- .\" $FreeBSD$ .Dd January 31, 2006 .Os .Dt PICOBSD 8 .Sh NAME .Nm picobsd .Nd building small FreeBSD disk images .Sh SYNOPSIS .Nm .Op Ar options .Op Ar config-name Op Ar site-name .Sh DESCRIPTION The .Nm utility is a script which produces a minimal implementation of .Fx (historically called .Nm PicoBSD ) which typically fits on a small media such as a floppy disk, or can be downloaded as a single image file from some media such as CDROM, flash memory, or through .Xr etherboot . .Pp The .Nm utility was originally created to build simple standalone systems such as firewalls or bridges, but because of the ability to cross-build images with different source trees than the one in the server, it can be extremely useful to developers to test their code without having to reinstall the system. .Pp The boot media (historically a floppy disk, but also small CDROM or USB keys) contains a boot loader and a compressed kernel which includes a memory file system. Depending on the media, it might also contain a number of additional files, which can be updated at run time, and are used to override/update those in the memory file system. .Pp The system loads the kernel in the normal way, uncompresses the memory file system and mounts it as root. It then updates the memory file system with files from the boot media (if present), and executes a specialized version of .Pa /etc/rc . The boot media (floppy, etc.) is required for loading only, and typically used read-only. After the boot phase, the system runs entirely from RAM. .Pp The following options are available (but also check the .Nm script for more details): .Pp .Bl -tag -width indent .It Fl -src Ar SRC_PATH Use the source tree at .Ar SRC_PATH instead the one at .Pa /usr/src . This can be useful for cross-building .Nm images. When using this option, you must also create and initialize the subtree at .Ao Ar SRC_PATH Ac Ns Pa /../usr with the correct header files, libraries, and tools (such as the .Xr config 8 program) that are necessary for the cross-build (see the .Fl -init option below). The source files are unmodified by the .Nm script. However the source tree is not completely read-only, because .Xr config 8 expects the kernel configuration file to be in one of its subdirectories, and also the process of initializing the .Pa usr subtree touches some parts of the source tree (this is a bug in the release build scripts which might go away with time). .It Fl -init When used together with the .Fl -src option, this initializes the .Ao Ar SRC_PATH Ac Ns Pa /../usr subtree as necessary to subsequently build .Nm images. .It Fl -modules Also build kernel modules. These are not stored on the .Nm image but are left available in the build directory. .It Fl n Make the script non-interactive, skipping the initial menu and proceeding with the build process without requiring user input. .It Fl v Make the script verbose, showing commands to be executed and waiting for user input before executing each of them. Useful for debugging. .It Fl -all_in_mfs Put the entire contents of the file system in the memory file system image which is contained in the kernel. This is the default behaviour, and is extremely useful as the kernel itself can be loaded, using .Xr etherboot or .Xr pxeboot 8 , as a fully functional system. .It Fl -no_all_in_mfs Leaves files contained in the .Pa floppy.tree on the .Nm image, so they can be loaded separately from the kernel (and updated individually to customize the image). .It Fl -floppy_size Ar size Set the size of the disk image. Typical values for a floppy disk are 1440 or 2880, but other values can be used for other media (flash memories, CDROM, network booted kernels). .It Fl c , clean Clean the product of previous builds. .El .Sh ENVIRONMENT As a result of extreme size limitations, the .Nm environment differs from the normal .Fx in a number of ways: .Bl -bullet .It There are no dynamic libraries, and there is no directory .Pa /usr/lib . As a result, only static executables may be executed. .It In order to reduce the size of the executables, all executables on a specific floppy are joined together as a single executable built with .Xr crunchgen 1 . .It Some programs are supplied in minimalistic versions, specifically .Nm ns , a cut-down version of .Xr netstat 1 , and .Nm vm , a cut-down version of .Xr vmstat 8 . .El .Sh BUILDING PicoBSD The .Nm sources reside in the hierarchy .Pa /usr/src/release/picobsd . In the following discussion, all relative path names are relative to this directory. .Pp The supported build script is .Pa /usr/src/release/picobsd/build/picobsd which can be run from anywhere, and relies on the .Xr sysutils/makefs port to build a filesystem without requiring .Xr mdconfig or root privileges to mount a filesystem. When run in interactive mode (the default without the .Fl n option), the script will let you configure the various parameters -used to build the PicoBSD image. An image is configured +used to build the PicoBSD image. +An image is configured using the files and directories described below. The base system contains a template, called .Pa bridge -for historical reasons, +for historical reasons, that can be used as a base for building various kinds of network appliances. .Pp You can define your own PicoBSD configuration, by creating a directory with a name of your choice (e.g.\& .Pa FOO ) which contains some of the following files and directories. For more information on how to construct these files, look at one of the standard .Nm configurations as a reference. .Bl -tag -width indent .It Pa PICOBSD The kernel configuration file (required). This is a mostly standard kernel configuration file, possibly stripped down by removing unnecessary drivers and options to reduce the kernel's size. .Pp To be recognised as a .Nm kernel config file, the file must also contain the line beginning with .Dq Li #PicoBSD below, and a matching .Dv MD_ROOT_SIZE option: .Bd -literal -offset indent #marker def_sz init MFS_inodes floppy_inodes #PicoBSD 4200 init 8192 32768 options MD_ROOT_SIZE=4200 # same as def_sz .Ed .Pp This informs the script of the size of the memory file system and provides a few other details on how to build the image. .It Pa crunch.conf .Xr crunchgen 1 configuration (required). It contains the list of directories containing program sources, the list of binaries to be built, and the list of libraries that these programs use. See the .Xr crunchgen 1 manpage for the exact details on the syntax of this file. .Pp The following issues are particularly important when dealing with .Nm configurations: .Bl -bullet .It We can pass build options to those makefiles which understand that, in order to reduce the size of the programs. This is achieved with a line of the form .Pp .Dl "buildopts -DNO_PAM -DRELEASE_CRUNCH ..." .It When providing the list of directories where source files are, it is convenient to list the following entry first: .Pp .Dl "srcdirs /usr/src/release/picobsd/tinyware" .Pp so that .Nm Ns -specific versions of the programs will be found there. .It The string .Dq Li @__CWD__@ is replaced with the full pathname of the directory where the .Nm configuration resides (i.e., the one where we find .Pa PICOBSD , crunch.conf , and so on). This can be useful to refer source code that resides within a configuration, e.g.\& .Pp .Dl "srcdirs @__CWD__@/src" .El .It Pa config Shell variables, sourced by the .Nm script (optional). The most important variables here are: .Bl -tag -width ".Va MY_DEVS" .It Va MY_DEVS (Not used in .Fx 5.0 where we have .Xr devfs 5 ) . Should be set to the list of devices to be created in the .Pa /dev directory of the image (it is really the argument passed to .Xr MAKEDEV 8 , so refer to that manpage for the names). .It Va fd_size Size (in kilobytes) of the .Nm image. By default, .Va fd_size is set to 1440 which produces an image suitable for a standard floppy. .Pp If you plan to store the image on a CDROM (e.g.\& using the .Dq "El Torito" floppy emulation), you can set .Va fd_size equal to 2880. If you are planning to dump the image onto a hard disk (either in a partition or on the whole disk), you are not restricted to one of the standard floppy sizes. Using a large image size per se does not waste RAM at runtime, because only the files that are actually loaded from the image contribute to the memory usage. .It Va import_files Contains a list of files to be imported in the floppy tree. Absolute names refer to the standard file system, relative names refer to the root of the source tree being used (i.e.\& .Va SRC_PATH/.. ) . You can normally use this option if you want to import files such as shared libraries, or databases, without having to replicate them first in your configuration under the .Pa floppy.tree/ directory. .El .It Pa floppy.tree.exclude List of files from the standard floppy tree which we do not want to be copied (optional). .It Pa floppy.tree/ Local additions to the standard floppy tree (optional). The content of this subtree will be copied as-is into the floppy image. .It Pa floppy.tree. Ns Aq Ar site-name Same as above, but site-specific (optional). .El .Pp More information on the build process can be found in the comments in the .Nm script. .Sh USING ALTERNATE SOURCE TREES The build script can be instructed to use an alternate source tree using the .Fl -src Ar SRC_PATH option. The tree that you specify must contain full sources for the kernel and for all programs that you want to include in your image. As an example, to cross-build the .Pa bridge floppy using RELENG_4 sources, you can do the following: .Bd -literal -offset indent cd mkdir FOO (cd FOO; cvs -d co -rRELENG_4 src) picobsd --src FOO/src --init # this is needed only once picobsd --src FOO/src -n -v bridge .Ed .Pp If the build is successful, the directory .Pa build_dir-bridge/ will contain a .Pa kernel that can be downloaded with .Xr etherboot , a floppy image called .Pa picobsd.bin , plus the products of the compilation in other directories. If you want to modify the source tree in .Pa FOO/src , a new image can be produced by simply running .Pp .Dl "picobsd --src FOO/src -n -v bridge" .Pp whereas if the change affects include files or libraries you first need to update them, e.g.\& by re-running .Pp .Dl "picobsd --src FOO/src --init # this is needed only once" .Pp as you would normally do for any change of this kind. .Sh INSTALLING PicoBSD .Ss Floppy Install Historically, .Nm is run from a floppy disk, where it can be installed with a simple .Pp .Dl "dd if=picobsd.bin of=/dev/rfd0" .Pp and the floppy is ready to boot. .Ss Hard Disk Install The same process can be used to store the image on a hard disk (entire volume or one of the slices): .Bd -literal -offset indent dd if=picobsd.bin of=/dev/ad2 dd if=picobsd.bin of=/dev/ad2s3 dd if=picobsd.bin of=/dev/ad2 oseek=NN .Ed .Pp The first form will install the image on the entire disk, and it should work in the same way as for a floppy. .Pp The second form will install the image on slice number 3 (which should be large enough to store the contents of the image). However, the process will only have success if the partition does not contain a valid disklabel, otherwise the kernel will likely prevent overwriting the label. In this case you can use the third form, replacing .Ar NN with the actual start of the partition (which you can determine using .Xr fdisk 8 ) . Note that after saving the image to the slice, it will not yet be recognised. You have to use the .Xr disklabel 8 command to properly initialize the label (do not ask why!). One way to do this is .Bd -literal -offset indent disklabel -w ad0s2 auto disklabel -e ad0s2 .Ed .Pp and from the editor enter a line corresponding to the actual partition, e.g.\& if the image has 2.88MB (5760 sectors) you need to enter the following line for the partition: .Pp .Dl "a: 5760 0 4.2BSD 512 4096" .Pp At this point the partition is bootable. Note that the image size can be smaller than the slice size (indicated as partition .Dq Li c: ) . .Ss CDROM Install Another option is to put the image on a CDROM. Assuming your image for disk type .Pa foo is in the directory .Pa build_dir-foo then you can produce a bootable .Dq "El Torito" image (and burn it) with the following command: .Bd -literal -offset indent mkisofs -b picobsd.bin -c boot.catalog -d -N -D -R -T \\ -o cd.img build_dir-foo burncd -f /dev/acd0c -s 4 data cd.img fixate .Ed .Pp Note that the image size is restricted to 1.44MB or 2.88MB, other sizes most likely will not work. .Ss Booting From The Network Yet another way to use .Nm is to boot the image off the network. For this purpose you should use the uncompressed kernel which is available as a byproduct of the compilation. Refer to the documentation for network booting for more details, the .Nm kernel is bootable as a standard .Fx kernel. .Sh BOOTING PicoBSD To boot .Nm , insert the floppy and reset the machine. The boot procedure is similar to the standard .Fx boot. Booting from a floppy is normally rather slow (in the order of 1-2 minutes), things are much faster if you store your image on a hard disk, Compact Flash, or CDROM. .Pp You can also use .Xr etherboot to load the preloaded, uncompressed kernel image which is a byproduct of the .Nm build. In this case the load time is a matter of a few seconds, even on a 10Mbit/s ethernet. .Pp After booting, .Nm loads the root file system from the memory file system, starts .Pa /sbin/init , and passes control to a first startup script, .Pa /etc/rc . The latter populates the .Pa /etc and .Pa /root directories with the default files, then tries to identify the boot device (floppy, hard disk partition) and possibly override the contents of the root file system with files read from the boot device. This allows you to store local configuration on the same media. After this phase the boot device is no longer used, unless the user specifically does it. .Pp After this, control is transferred to a second script, .Pa /etc/rc1 (which can be overridden from the boot device). This script tries to associate a hostname to the system by using the MAC address of the first ethernet interface as a key, and .Pa /etc/hosts as a lookup table. Then control is passed to the main user configuration script, .Pa /etc/rc.conf , which is supposed to override the value of a number of configuration variables which have been pre-set in .Pa /etc/rc.conf.defaults . You can use the .Va hostname variable to create different configurations from the same file. After taking control back, .Pa /etc/rc1 completes the initializations, and as part of this it configures network interfaces and optionally calls the firewall configuration script, .Pa /etc/rc.firewall , where the user can store his own firewall configuration. .Pp Note that by default .Nm runs entirely from main memory, and has no swap space, unless you explicitly request it. The boot device is also not used anymore after .Pa /etc/rc1 takes control, again, unless you explicitly request it. .Sh CONFIGURING a PicoBSD system The operation of a .Nm system can be configured through a few files which are read at boot time, very much like a standard .Fx system. There are, however, some minor differences to reduce the number of files to store and/or customize, thus saving space. Among the files to configure we have the following: .Bl -tag -width indent .It Pa /etc/hosts Traditionally, this file contains the IP-to-hostname mappings. In addition to this, the .Nm version of this file also contains a mapping between Ethernet (MAC) addresses and hostnames, as follows: .Bd -literal -offset indent #ethertable start of the ethernet->hostname mapping # mac_address hostname # 00:12:34:56:78:9a pinco # 12:34:56:* pallino # * this-matches-all .Ed .Pp where the line containing .Dq Li #ethertable marks the start of the table. .Pp If the MAC address is not found, the script will prompt you to enter a hostname and IP address for the system, and this information will be stored in the .Pa /etc/hosts file (in memory) so you can simply store them on disk later. .Pp Note that you can use wildcards in the address part, so a line like the last one in the example will match any MAC address and avoid the request. .It Pa /etc/rc.conf This file contains a number of variables which control the operation of the system, such as interface configuration, router setup, network service startup, etc. For the exact list and meaning of these variables see .Pa /etc/rc.conf.defaults . .Pp It is worth mentioning that some of the variables let you overwrite the contents of some files in .Pa /etc . This option is available at the moment for .Pa /etc/host.conf and .Pa /etc/resolv.conf , whose contents are generally very short and suitable for this type of updating. In case you use these variables, remember to use newlines as appropriate, e.g.\& .Bd -literal -offset indent host_conf="# this goes into /etc/host.conf hosts bind" .Ed .Pp Although not mandatory, in this file you should only set the variables indicated in .Pa /etc/rc.conf.defaults , and avoid starting services which depend on having the network running. This can be done at a later time: if you set .Va firewall_enable Ns = Ns Qq Li YES , the .Pa /etc/rc.firewall script will be run after configuring the network interfaces, so you can set up your firewall and safely start network services or enable things such as routing and bridging. .It Pa /etc/rc.firewall This script can be used to configure the .Xr ipfw 4 firewall. On entry, the .Va fwcmd variable is set to the pathname of the firewall command, .Va firewall_type contains the value set in .Pa /etc/rc.conf , and .Va hostname contains the name assigned to the host. .El .Pp There is a small script called .Nm update which can be used to edit and/or save to disk a copy of the files you have modified after booting. The script takes one or more absolute pathnames, runs the editor on the files passed as arguments, and then saves a compressed copy of the files on the disk (mounting and unmounting the latter around the operation). .Pp If invoked without arguments, .Nm update edits and saves .Pa rc.conf , rc.firewall , and .Pa master.passwd . .Pp If one of the arguments is .Pa /etc (the directory name alone), then the command saves to disk (without editing) all the files in the directory for which a copy already exists on disk (e.g.\& as a result of a previous update). .Sh SEE ALSO .Xr crunchgen 1 , .Xr mdconfig 8 , .Xr swapon 8 .Sh AUTHORS .An -nosplit .An Andrzej Bialecki Aq abial@FreeBSD.org , with subsequent work on the scripts by .An Luigi Rizzo Aq luigi@iet.unipi.it and others. Man page and .Pa Makefiles created by .An Greg Lehey Aq grog@lemis.com . .Sh BUGS Building .Nm is still a black art. The biggest problem is determining what will fit on the floppies, and the only practical method is trial and error. Index: head/share/man/man8/rc.8 =================================================================== --- head/share/man/man8/rc.8 (revision 162403) +++ head/share/man/man8/rc.8 (revision 162404) @@ -1,563 +1,563 @@ .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Portions of this manual page are Copyrighted by .\" The NetBSD 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. .\" 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. .\" .\" @(#)rc.8 8.2 (Berkeley) 12/11/93 .\" $FreeBSD$ .\" .Dd December 19, 2005 .Dt RC 8 .Os .Sh NAME .Nm rc .Nd command scripts for auto-reboot and daemon startup .Sh SYNOPSIS .Nm .Nm rc.conf .Nm rc.conf.local .Nm rc.d/ .Nm rc.firewall .Nm rc.local .Nm rc.shutdown .Nm rc.subr .Sh DESCRIPTION The .Nm utility is the command script which controls the automatic boot process after being called by .Xr init 8 . The .Nm rc.local script contains commands which are pertinent only to a specific site. Typically, the .Pa /usr/local/etc/rc.d/ mechanism is used instead of .Nm rc.local these days but if you want to use .Nm rc.local , it is still supported. In this case, it should source .Pa /etc/rc.conf and contain additional custom startup code for your system. The best way to handle .Nm rc.local , however, is to separate it out into .Nm rc.d/ style scripts and place them under .Pa /usr/local/etc/rc.d/ . The .Nm rc.conf file contains the global system configuration information referenced by the startup scripts, while .Nm rc.conf.local contains the local system configuration. See .Xr rc.conf 5 for more information. .Pp The .Nm rc.d/ directories contain scripts which will be automatically executed at boot time and shutdown time. .Ss Operation of Nm .Bl -enum .It If autobooting, set .Va autoboot Ns = Ns Li yes and enable a flag .Pq Va rc_fast Ns = Ns Li yes , which prevents the .Nm rc.d/ scripts from performing the check for already running processes (thus speeding up the boot process). This .Va rc_fast Ns = Ns Li yes speedup will not occur when .Nm is started up after exiting the single-user shell. .It Determine whether the system is booting diskless, and if so run the .Pa /etc/rc.initdiskless script. .It Source .Pa /etc/rc.subr to load various .Xr rc.subr 8 shell functions to use. .It Load the configuration files. .It Determine if booting in a jail, and add -.Dq nojail +.Dq Li nojail to the list of KEYWORDS to skip in .Xr rcorder 8 . .It Invoke .Xr rcorder 8 to order the files in .Pa /etc/rc.d/ that do not have a .Dq Li nostart KEYWORD (refer to .Xr rcorder 8 Ns 's .Fl s flag). .It Call each script in turn using .Fn run_rc_script (from .Xr rc.subr 8 ) , which sets .Va $1 to .Dq Li start , and sources the script in a subshell. If the script has a .Pa .sh suffix then it is sourced directly into the current shell. Stop processing when the script that is the value of the .Va $early_late_divider has been run. .It Re-run .Xr rcorder 8 , this time including the scripts in the .Va $local_startup directories. Ignore everything up to the .Va $early_late_divider , then start executing the scripts as described above. .El .Ss Operation of Nm rc.shutdown .Bl -enum .It Source .Pa /etc/rc.subr to load various .Xr rc.subr 8 shell functions to use. .It Load the configuration files. .It Invoke .Xr rcorder 8 to order the files in .Pa /etc/rc.d/ and the .Va $local_startup directories that have a .Dq Li shutdown KEYWORD (refer to .Xr rcorder 8 Ns 's .Fl k flag), reverse that order, and assign the result to a variable. .It Call each script in turn using .Fn run_rc_script (from .Xr rc.subr 8 ) , which sets .Va $1 to .Dq Li stop , and sources the script in a subshell. If the script has a .Pa .sh suffix then it is sourced directly into the current shell. .El .Ss Contents of Nm rc.d/ .Nm rc.d/ is located in .Pa /etc/rc.d/ . The following file naming conventions are currently used in .Nm rc.d/ : .Bl -tag -width ".Pa ALLUPPERCASE" -offset indent .It Pa ALLUPPERCASE Scripts that are .Dq placeholders to ensure that certain operations are performed before others. In order of startup, these are: .Bl -tag -width ".Pa NETWORKING" .It Pa NETWORKING Ensure basic network services are running, including general network configuration. .It Pa SERVERS Ensure basic services exist for services that start early (such as .Pa named ) , because they are required by .Pa DAEMON below. .It Pa DAEMON Check-point before all general purpose daemons such as .Pa lpd and .Pa ntpd . .It Pa LOGIN Check-point before user login services .Pa ( inetd and .Pa sshd ) , as well as services which might run commands as users .Pa ( cron and .Pa sendmail ) . .El .It Pa foo.sh Scripts that are to be sourced into the current shell rather than a subshell have a .Pa .sh suffix. Extreme care must be taken in using this, as the startup sequence will terminate if the script does. .It Pa bar Scripts that are sourced in a subshell. These can stop the boot if necessary with the following shell commands: .Bd -literal -offset indent if [ "$autoboot" = yes ]; then kill -TERM $$ fi exit 1 .Ed .Pp Note that this should be used extremely sparingly! .El .Pp Each script should contain .Xr rcorder 8 keywords, especially an appropriate .Dq Li PROVIDE entry, and if necessary .Dq Li REQUIRE and .Dq Li BEFORE keywords. .Pp Each script is expected to support at least the following arguments, which are automatically supported if it uses the .Fn run_rc_command function: .Bl -tag -width ".Cm restart" -offset indent .It Cm start Start the service. This should check that the service is to be started as specified by .Xr rc.conf 5 . Also checks if the service is already running and refuses to start if it is. This latter check is not performed by standard .Fx scripts if the system is starting directly to multi-user mode, to speed up the boot process. If .Cm forcestart is given, ignore the .Xr rc.conf 5 check and start anyway. .It Cm stop If the service is to be started as specified by .Xr rc.conf 5 , stop the service. This should check that the service is running and complain if it is not. If .Cm forcestop is given, ignore the .Xr rc.conf 5 check and attempt to stop. .It Cm restart Perform a .Cm stop then a .Cm start . .It Cm status If the script starts a process (rather than performing a one-off operation), show the status of the process. Otherwise it is not necessary to support this argument. Defaults to displaying the process ID of the program (if running). .It Cm poll If the script starts a process (rather than performing a one-off operation), wait for the command to exit. Otherwise it is not necessary to support this argument. .It Cm rcvar Display which .Xr rc.conf 5 variables are used to control the startup of the service (if any). .El .Pp If a script must implement additional commands it can list them in the .Va extra_commands variable, and define their actions in a variable constructed from the command name (see the .Sx EXAMPLES section). .Pp The following key points apply to old-style scripts in .Pa /usr/local/etc/rc.d/ : .Pp .Bl -bullet .It Scripts are only executed if their .Xr basename 1 matches the shell globbing pattern .Pa *.sh , and they are executable. Any other files or directories present within the directory are silently ignored. .It When a script is executed at boot time, it is passed the string .Dq Li start as its first and only argument. At shutdown time, it is passed the string .Dq Li stop as its first and only argument. All .Nm rc.d/ scripts are expected to handle these arguments appropriately. If no action needs to be taken at a given time (either boot time or shutdown time), the script should exit successfully and without producing an error message. .It The scripts within each directory are executed in lexicographical order. If a specific order is required, numbers may be used as a prefix to the existing filenames, so for example .Pa 100.foo would be executed before .Pa 200.bar ; without the numeric prefixes the opposite would be true. .It The output from each script is traditionally a space character, followed by the name of the software package being started or shut down, .Em without a trailing newline character (see the .Sx EXAMPLES section). .El .Sh SCRIPTS OF INTEREST When an automatic reboot is in progress, .Nm is invoked with the argument .Cm autoboot . One of the scripts run from .Pa /etc/rc.d/ is .Pa /etc/rc.d/fsck . This script runs .Xr fsck 8 with option .Fl p and .Fl F to .Dq preen all the disks of minor inconsistencies resulting from the last system shutdown. If this fails, then checks/repairs of serious inconsistencies caused by hardware or software failure will be performed in the background at the end of the booting process. If .Cm autoboot is not set, when going from single-user to multi-user mode for example, the script does not do anything. .Pp The .Nm rc.early script is run very early in the startup process, immediately before the file system check. The .Nm rc.early script is deprecated. Any commands in this file should be separated out into .Nm rc.d/ style scripts and integrated into the .Nm system. .Pp The .Pa /etc/rc.d/local script can execute scripts from multiple .Nm rc.d/ directories. The default locations are .Pa /usr/local/etc/rc.d/ and .Pa /usr/X11R6/etc/rc.d/ , but these may be overridden with the .Va local_startup .Xr rc.conf 5 variable. .Pp The .Pa /etc/rc.d/serial script is used to set any special configurations for serial devices. .Pp The .Nm rc.firewall script is used to configure rules for the kernel based firewall service. It has several possible options: .Pp .Bl -tag -width ".Ar filename" -compact -offset indent .It Cm open will allow anyone in .It Cm client will try to protect just this machine .It Cm simple will try to protect a whole network .It Cm closed totally disables IP services except via .Pa lo0 interface .It Cm UNKNOWN disables the loading of firewall rules .It Ar filename will load the rules in the given filename (full path required). .El .Pp The .Pa /etc/rc.d/atm* scripts are used to configure ATM network interfaces. The interfaces are configured in three passes. The first pass performs the initial interface configuration. The second pass completes the interface configuration and defines PVCs and permanent ATMARP entries. The third pass starts any ATM daemons. .Pp Most daemons, including network related daemons, have their own script in .Pa /etc/rc.d/ , which can be used to start, stop, and check the status of the service. .Pp Any architecture specific scripts, such as .Pa /etc/rc.d/apm for example, specifically check that they are on that architecture before starting the daemon. .Pp Following tradition, all startup files reside in .Pa /etc . .Sh FILES .Bl -tag -compact .It Pa /etc/rc .It Pa /etc/rc.conf .It Pa /etc/rc.conf.local .It Pa /etc/rc.d/ .It Pa /etc/rc.firewall .It Pa /etc/rc.local .It Pa /etc/rc.shutdown .It Pa /etc/rc.subr .It Pa /var/run/dmesg.boot .Xr dmesg 8 results soon after the .Nm process begins. Useful when .Xr dmesg 8 buffer in the kernel no longer has this information. .El .Sh EXAMPLES The following is a minimal .Nm rc.d/ style script. Most scripts require little more than the following. .Bd -literal -offset indent #!/bin/sh # # PROVIDE: foo # REQUIRE: bar_service_required_to_precede_foo \&. /etc/rc.subr name="foo" rcvar=`set_rcvar` command="/usr/local/bin/foo" load_rc_config $name run_rc_command "$1" .Ed .Pp Certain scripts may want to provide enhanced functionality. The user may access this functionality through additional commands. The script may list and define as many commands at it needs. .Bd -literal -offset indent #!/bin/sh # # PROVIDE: foo # REQUIRE: bar_service_required_to_precede_foo # BEFORE: baz_service_requiring_foo_to_precede_it \&. /etc/rc.subr name="foo" rcvar=`set_rcvar` command="/usr/local/bin/foo" extra_commands="nop hello" hello_cmd="echo Hello World." nop_cmd="do_nop" do_nop() { echo "I do nothing." } load_rc_config $name run_rc_command "$1" .Ed .Pp As all processes are killed by .Xr init 8 at shutdown, the explicit .Xr kill 1 is unnecessary, but is often included. .Sh SEE ALSO .Xr kill 1 , .Xr rc.conf 5 , .Xr init 8 , .Xr rcorder 8 , .Xr rc.subr 8 , .Xr reboot 8 , .Xr savecore 8 .Sh HISTORY The .Nm utility appeared in .Bx 4.0 . Index: head/share/man/man9/VFS_ROOT.9 =================================================================== --- head/share/man/man9/VFS_ROOT.9 (revision 162403) +++ head/share/man/man9/VFS_ROOT.9 (revision 162404) @@ -1,68 +1,69 @@ .\" -*- 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 August 26, 2006 .Os .Dt VFS_ROOT 9 .Sh NAME .Nm VFS_ROOT .Nd return the root vnode of a file system .Sh SYNOPSIS .In sys/param.h .In sys/mount.h .In sys/vnode.h .Ft int .Fn VFS_ROOT "struct mount *mp" "int flags" "struct vnode **vpp" "struct thread *td" .Sh DESCRIPTION Return a locked vnode for the root directory of the file system. .Pp Its arguments are: .Bl -tag -width flags .It Fa mp The file system. .It Fa flags -The lock type. Could be +The lock type. +Could be .Dv LK_EXCLUSIVE or .Dv LK_SHARED . File system is free to ignore the .Fa flags argument and instead acquire an exclusive lock. .It Fa vpp Return parameter for the root vnode. .It Fa td The calling thread. .El .Sh SEE ALSO .Xr VFS 9 , .Xr vnode 9 .Sh AUTHORS This manual page was written by .An Doug Rabson . Index: head/share/man/man9/bus_dma.9 =================================================================== --- head/share/man/man9/bus_dma.9 (revision 162403) +++ head/share/man/man9/bus_dma.9 (revision 162404) @@ -1,928 +1,951 @@ .\" 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 August 31, 2006 .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 +.Bl -tag -width indent .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 +.Bl -tag -width indent .It Ft int .Fn "client_filter" "void *filtarg" "bus_addr_t testaddr" .El -.sp +.Pp 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 +.Pp 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. One map is used for each memory allocation that will be loaded. Maps can be reused once they have been unloaded. Multiple maps can be associated with one DMA tag. -While the value of the map may evaluate to NULL on some platforms under -certain conditions, it should never be assumed that it will be NULL in all -cases. +While the value of the map may evaluate to +.Dv NULL +on some platforms under certain conditions, +it should never be assumed that it will be +.Dv NULL +in all cases. .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 +.Bl -tag -width indent .It Ft void .Fn "client_callback" "void *callback_arg" "bus_dma_segment_t *segs" \ "int nseg" "int error" .El -.sp +.Pp 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 +.Pp Callback2s are of the format: -.Bl -tag -width compact +.Bl -tag -width indent .It Ft void .Fn "client_callback2" "void *callback_arg" "bus_dma_segment_t *segs" \ "int nseg" "bus_size_t mapsize" "int error" .El -.sp +.Pp 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. The operations are represented as bitfield flags that can be combined together, though it only makes sense to combine PRE flags or POST flags, not both. See the .Fn bus_dmamap_sync description below for more details on how to use these operations. .Pp All operations specified below are performed from the host memory point of view, where a read implies data coming from the device to the host memory, and a write implies data going from the host memory to the device. Alternatively, the operations can be thought of in terms of driver operations, where reading a network packet or storage sector corresponds to a read operation in .Nm . .Bl -tag -width ".Dv BUS_DMASYNC_POSTWRITE" .It Dv BUS_DMASYNC_PREREAD Perform any synchronization required prior to an update of host memory by the device. .It Dv BUS_DMASYNC_PREWRITE Perform any synchronization required after an update of host memory by the CPU and prior to device access to host memory. .It Dv BUS_DMASYNC_POSTREAD Perform any synchronization required after an update of host memory by the device and prior to CPU access to host memory. .It Dv BUS_DMASYNC_POSTWRITE Perform any synchronization required after the device access to host memory. .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 +.Bl -tag -width indent .It Ft void .Fn "lockfunc" "void *lockfunc_arg" "bus_dma_lock_op_t op" .El -.sp +.Pp 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 +is passed as +.Dv 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 +.Bl -tag -width ".Dv 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 +.Bl -tag -width indent .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 +.Bl -tag -width ".Fa filtfuncarg" .It Fa parent Indicates restrictions between the parent bridge, CPU memory, and the device. Each device must use a master parent tag by calling .Fn bus_get_dma_tag . .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 +.It Fa lowaddr , 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 +Optional filter function (may be +.Dv 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. +May be +.Dv 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 +.Bl -tag -width ".Dv BUS_DMA_ALLOCNOW" .It Dv BUS_DMA_ALLOCNOW Pre-allocate enough resources to handle at least one map load operation on this tag. If sufficient resources are not available, .Er ENOMEM is returned. This should not be used for tags that only describe buffers that will be allocated with .Fn bus_dmamem_alloc . Also, due to resource sharing with other tags, this flag does not guarantee that resources will be allocated or reserved exclusively for this tag. It should be treated only as a minor optimization. .El .It Fa lockfunc -Optional lock manipulation function (may be NULL) to be called when busdma +Optional lock manipulation function (may be +.Dv NULL ) +to be called when busdma needs to manipulate a lock on behalf of the client. -If NULL is specified, +If +.Dv 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 +.Bl -tag -width ".Fa nsegments" .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 +.Bl -tag -width ".Fa dmat" .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 . This call will always return immediately and will not block for any reason. Arguments are as follows: -.Bl -tag -width buflen -compact +.Bl -tag -width ".Fa buflen" .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. This function is called once sufficient mapping resources are available for the DMA operation. If resources are temporarily unavailable, this function will be deferred until later, but the load operation will still return immediately to the caller. Thus, callers should not assume that the callback will be called before the load returns, and code should be structured appropriately to handle this. See below for specific flags and error codes that control this behavior. .It Fa flags Are as follows: -.Bl -tag -width BUS_DMA_NOWAIT -compact -.It Er BUS_DMA_NOWAIT +.Bl -tag -width ".Dv BUS_DMA_NOWAIT" +.It Dv BUS_DMA_NOWAIT The load should not be deferred in case of insufficient mapping resources, and instead should return immediately with an appropriate error. .El .El .Pp Return values to the caller are as follows: -.Bl -tag -width EINPROGRESS -compact +.Bl -tag -width ".Er EINPROGRESS" .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 ENOMEM The load request has failed due to insufficient resources, and the caller specifically used the -.Fa BUS_DMA_NOWAIT +.Dv BUS_DMA_NOWAIT flag. .It Er EINVAL The load request was invalid. The callback has been called and has been provided the same error. This error value may indicate that .Fa dmat , .Fa map , .Fa buf , or .Fa callback were invalid, or .Fa buflen 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 +.Bl -tag -width ".Er EINPROGRESS" .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. The -.Fa BUS_DMA_NOWAIT +.Dv BUS_DMA_NOWAIT flag is implied, thus no callback deferral will happen. .Pp Mbuf chains are assumed to be in kernel virtual address space. .Pp Beside the error values listed for .Fn bus_dmamap_load , .Er EINVAL will be returned 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. 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 . The -.Fa BUS_DMA_NOWAIT +.Dv BUS_DMA_NOWAIT flag is implied, thus no callback deferral will happen. Returns the same errors as .Fn bus_dmamap_load . .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 +.Bl -tag -width ".Fa dmam" .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 +.Bl -tag -width ".Fa dmat" .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 The .Fn bus_dmamap_sync function is the method used to ensure that CPU's and device's direct memory access (DMA) to shared memory is coherent. For example, the CPU might be used to set up the contents of a buffer that is to be made available to 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_PREWRITE must be performed. If later CPU modifies this buffer again, another .Dv BUS_DMASYNC_PREWRITE sync operation must be performed before an additional access to this memory by a device. Conversely, a device updates the memory that is to be read by a CPU. In this case, the buffer must be loaded, and a DMA sync operation of .Dv BUS_DMASYNC_PREREAD must be performed. The CPU will only be able to see the results of this memory update once the DMA operation has completed and a .Dv BUS_DMASYNC_POSTREAD sync operation has been performed. .Pp If 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 +.Bl -tag -width ".Fa alignment" .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 +.Bl -tag -width ".Dv BUS_DMA_NOWAIT" .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. -The BUS_DMA_COHERENT flag is currently implemented on sparc64 and arm. +The +.Dv BUS_DMA_COHERENT +flag is currently implemented on sparc64 and arm. .It Dv BUS_DMA_ZERO Causes the allocated memory to be set to all zeros. .El .It Fa mapp Pointer to a .Vt bus_dmamap_t where the resulting DMA map will be stored. .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 An initial load operation is required to obtain the bus address of the allocated memory, and an unload operation is required before freeing the memory, as described below in .Fn bus_dmamem_free . Maps are automatically handled by this function and should not be explicitly allocated or destroyed. .Pp Although an explicit load is not required for each access to the memory referenced by the returned map, the synchronization requirements as described in the .Fn bus_dmamap_sync section still apply and should be used to achieve portability on architecutures without coherent buses. .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 +.Bl -tag -width ".Fa vaddr" .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 LOCKING Two locking protocols are used by .Nm . The first is a private global lock that is used to synchronize access to the bounce buffer pool on the architectures that make use of them. This lock is strictly a leaf lock that is only used internally to .Nm and is not exposed to clients of the API. .Pp The second protocol involves protecting various resources stored in the tag. Since almost all .Nm operations are done through requests from the driver that created the tag, the most efficient way to protect the tag resources is through the lock that the driver uses. In cases where .Nm acts on its own without being called by the driver, the lock primitive specified in the tag is acquired and released automatically. An example of this is when the .Fn bus_dmamap_load callback function is called from a deferred context instead of the driver context. This means that certain .Nm -functions must always be called with same lock held that is specified in the -tag. These functions include: +functions must always be called with the same lock held that is specified in the +tag. +These functions include: .Pp -.Bl -inset -offset indent -compact -.It bus_dmamap_load -.It bus_dmamap_load_uio -.It bus_dmamap_load_mbuf -.It bus_dmamap_load_mbuf_sg -.It bus_dmamap_unload -.It bus_dmamap_sync +.Bl -item -offset indent -compact +.It +.Fn bus_dmamap_load +.It +.Fn bus_dmamap_load_uio +.It +.Fn bus_dmamap_load_mbuf +.It +.Fn bus_dmamap_load_mbuf_sg +.It +.Fn bus_dmamap_unload +.It +.Fn bus_dmamap_sync .El .Pp There is one exception to this rule. It is common practice to call some of these functions during driver start-up without any locks held. So long as there is a guarantee of no possible concurrent use of the tag by different threads during this operation, it is safe to not hold a lock for these functions. .Pp Certain .Nm operations should not be called with the driver lock held, either because they are already protected by an internal lock, or because they might sleep -due to memory or resource allocation. The following functions must not be +due to memory or resource allocation. +The following functions must not be called with any non-sleepable locks held: .Pp -.Bl -inset -offset indent -compact -.It bus_dma_tag_create -.It bus_dmamap_create -.It bus_dmamem_alloc +.Bl -item -offset indent -compact +.It +.Fn bus_dma_tag_create +.It +.Fn bus_dmamap_create +.It +.Fn bus_dmamem_alloc .El .Pp All other functions do not have a locking protocol and can thus be called with or without and system or driver locks held. .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/crypto.9 =================================================================== --- head/share/man/man9/crypto.9 (revision 162403) +++ head/share/man/man9/crypto.9 (revision 162404) @@ -1,662 +1,664 @@ .\" $OpenBSD: crypto.9,v 1.19 2002/07/16 06:31:57 angelos Exp $ .\" .\" The author of this manual page is Angelos D. Keromytis (angelos@cis.upenn.edu) .\" .\" Copyright (c) 2000, 2001 Angelos D. Keromytis .\" .\" Permission to use, copy, and modify this software with or without fee .\" is hereby granted, provided that this entire notice is included in .\" all source code copies of any software which is or includes a copy or .\" modification of this software. .\" .\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR .\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY .\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE .\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR .\" PURPOSE. .\" .\" $FreeBSD$ .\" .Dd June 4, 2006 .Dt CRYPTO 9 .Os .Sh NAME .Nm crypto .Nd API for cryptographic services in the kernel .Sh SYNOPSIS .In opencrypto/cryptodev.h .Ft int32_t .Fn crypto_get_driverid u_int8_t .Ft int .Fn crypto_register u_int32_t int u_int16_t u_int32_t "int \*[lp]*\*[rp]\*[lp]void *, u_int32_t *, struct cryptoini *\*[rp]" "int \*[lp]*\*[rp]\*[lp]void *, u_int64_t\*[rp]" "int \*[lp]*\*[rp]\*[lp]void *, struct cryptop *\*[rp]" "void *" .Ft int .Fn crypto_kregister u_int32_t int u_int32_t "int \*[lp]*\*[rp]\*[lp]void *, struct cryptkop *\*[rp]" "void *" .Ft int .Fn crypto_unregister u_int32_t int .Ft int .Fn crypto_unregister_all u_int32_t .Ft void .Fn crypto_done "struct cryptop *" .Ft void .Fn crypto_kdone "struct cryptkop *" .Ft int .Fn crypto_newsession "u_int64_t *" "struct cryptoini *" int .Ft int .Fn crypto_freesession u_int64_t .Ft int .Fn crypto_dispatch "struct cryptop *" .Ft int .Fn crypto_kdispatch "struct cryptkop *" .Ft int .Fn crypto_unblock u_int32_t int .Ft "struct cryptop *" .Fn crypto_getreq int .Ft void .Fn crypto_freereq void .Bd -literal #define CRYPTO_SYMQ 0x1 #define CRYPTO_ASYMQ 0x2 #define EALG_MAX_BLOCK_LEN 16 struct cryptoini { int cri_alg; int cri_klen; int cri_mlen; caddr_t cri_key; u_int8_t cri_iv[EALG_MAX_BLOCK_LEN]; struct cryptoini *cri_next; }; struct cryptodesc { int crd_skip; int crd_len; int crd_inject; int crd_flags; struct cryptoini CRD_INI; #define crd_iv CRD_INI.cri_iv #define crd_key CRD_INI.cri_key #define crd_alg CRD_INI.cri_alg #define crd_klen CRD_INI.cri_klen struct cryptodesc *crd_next; }; struct cryptop { TAILQ_ENTRY(cryptop) crp_next; u_int64_t crp_sid; int crp_ilen; int crp_olen; int crp_etype; int crp_flags; caddr_t crp_buf; caddr_t crp_opaque; struct cryptodesc *crp_desc; int (*crp_callback) (struct cryptop *); caddr_t crp_mac; }; struct crparam { caddr_t crp_p; u_int crp_nbits; }; #define CRK_MAXPARAM 8 struct cryptkop { TAILQ_ENTRY(cryptkop) krp_next; u_int krp_op; /* ie. CRK_MOD_EXP or other */ u_int krp_status; /* return status */ u_short krp_iparams; /* # of input parameters */ u_short krp_oparams; /* # of output parameters */ u_int32_t krp_hid; struct crparam krp_param[CRK_MAXPARAM]; int (*krp_callback)(struct cryptkop *); }; .Ed .Sh DESCRIPTION .Nm is a framework for drivers of cryptographic hardware to register with the kernel so .Dq consumers (other kernel subsystems, and users through the .Pa /dev/crypto device) are able to make use of it. Drivers register with the framework the algorithms they support, and provide entry points (functions) the framework may call to establish, use, and tear down sessions. Sessions are used to cache cryptographic information in a particular driver (or associated hardware), so initialization is not needed with every request. Consumers of cryptographic services pass a set of descriptors that instruct the framework (and the drivers registered with it) of the operations that should be applied on the data (more than one cryptographic operation can be requested). .Pp Keying operations are supported as well. Unlike the symmetric operators described above, these sessionless commands perform mathematical operations using input and output parameters. .Pp Since the consumers may not be associated with a process, drivers may not .Xr sleep 9 . The same holds for the framework. Thus, a callback mechanism is used to notify a consumer that a request has been completed (the callback is specified by the consumer on an per-request basis). The callback is invoked by the framework whether the request was successfully completed or not. An error indication is provided in the latter case. A specific error code, .Er EAGAIN , is used to indicate that a session number has changed and that the request may be re-submitted immediately with the new session number. Errors are only returned to the invoking function if not enough information to call the callback is available (meaning, there was a fatal error in verifying the arguments). For session initialization and teardown there is no callback mechanism used. .Pp The .Fn crypto_newsession routine is called by consumers of cryptographic services (such as the .Xr ipsec 4 stack) that wish to establish a new session with the framework. On success, the first argument will contain the Session Identifier (SID). The second argument contains all the necessary information for the driver to establish the session. The third argument indicates whether a hardware driver (1) should be used or not (0). The various fields in the .Vt cryptoini structure are: .Bl -tag -width ".Va cri_next" .It Va cri_alg Contains an algorithm identifier. Currently supported algorithms are: .Pp .Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -compact .It Dv CRYPTO_DES_CBC .It Dv CRYPTO_3DES_CBC .It Dv CRYPTO_BLF_CBC .It Dv CRYPTO_CAST_CBC .It Dv CRYPTO_SKIPJACK_CBC .It Dv CRYPTO_MD5_HMAC .It Dv CRYPTO_SHA1_HMAC .It Dv CRYPTO_RIPEMD160_HMAC .It Dv CRYPTO_MD5_KPDK .It Dv CRYPTO_SHA1_KPDK .It Dv CRYPTO_AES_CBC .It Dv CRYPTO_ARC4 .It Dv CRYPTO_MD5 .It Dv CRYPTO_SHA1 .It Dv CRYPTO_SHA2_256_HMAC .It Dv CRYPTO_SHA2_384_HMAC .It Dv CRYPTO_SHA2_512_HMAC .It Dv CRYPTO_NULL_HMAC .It Dv CRYPTO_NULL_CBC .El .It Va cri_klen Specifies the length of the key in bits, for variable-size key algorithms. .It Va cri_mlen Specifies how many bytes from the calculated hash should be copied back. 0 means entire hash. .It Va cri_key Contains the key to be used with the algorithm. .It Va cri_iv Contains an explicit initialization vector (IV), if it does not prefix the data. This field is ignored during initialization. If no IV is explicitly passed (see below on details), a random IV is used by the device driver processing the request. .It Va cri_next Contains a pointer to another .Vt cryptoini structure. Multiple such structures may be linked to establish multi-algorithm sessions .Xr ( ipsec 4 is an example consumer of such a feature). .El .Pp The .Vt cryptoini structure and its contents will not be modified by the framework (or the drivers used). Subsequent requests for processing that use the SID returned will avoid the cost of re-initializing the hardware (in essence, SID acts as an index in the session cache of the driver). .Pp .Fn crypto_freesession is called with the SID returned by .Fn crypto_newsession to disestablish the session. .Pp .Fn crypto_dispatch is called to process a request. The various fields in the .Vt cryptop structure are: .Bl -tag -width ".Va crp_callback" .It Va crp_sid Contains the SID. .It Va crp_ilen Indicates the total length in bytes of the buffer to be processed. .It Va crp_olen On return, contains the total length of the result. For symmetric crypto operations, this will be the same as the input length. This will be used if the framework needs to allocate a new buffer for the result (or for re-formatting the input). .It Va crp_callback This routine is invoked upon completion of the request, whether successful or not. It is invoked through the .Fn crypto_done routine. If the request was not successful, an error code is set in the .Va crp_etype field. It is the responsibility of the callback routine to set the appropriate .Xr spl 9 level. .It Va crp_etype Contains the error type, if any errors were encountered, or zero if the request was successfully processed. If the .Er EAGAIN error code is returned, the SID has changed (and has been recorded in the .Va crp_sid field). The consumer should record the new SID and use it in all subsequent requests. In this case, the request may be re-submitted immediately. This mechanism is used by the framework to perform session migration (move a session from one driver to another, because of availability, performance, or other considerations). .Pp Note that this field only makes sense when examined by the callback routine specified in .Va crp_callback . Errors are returned to the invoker of .Fn crypto_process only when enough information is not present to call the callback routine (i.e., if the pointer passed is .Dv NULL or if no callback routine was specified). .It Va crp_flags Is a bitmask of flags associated with this request. Currently defined flags are: .Bl -tag -width ".Dv CRYPTO_F_CBIFSYNC" .It Dv CRYPTO_F_IMBUF The buffer pointed to by .Va crp_buf is an mbuf chain. .It Dv CRYPTO_F_IOV The buffer pointed to by .Va crp_buf -is an uio structure. +is an +.Vt uio +structure. .It Dv CRYPTO_F_REL Must return data in the same place. .It Dv CRYPTO_F_BATCH Batch operation if possible. .It Dv CRYPTO_F_CBIMM Do callback immediatelly instead of doing it from a dedicated kernel thread. .It Dv CRYPTO_F_DONE Operation completed. .It Dv CRYPTO_F_CBIFSYNC Do callback immediatelly if operation is synchronous. .El .It Va crp_buf Points to the input buffer. On return (when the callback is invoked), it contains the result of the request. The input buffer may be an mbuf chain or a contiguous buffer, depending on .Va crp_flags . .It Va crp_opaque This is passed through the crypto framework untouched and is intended for the invoking application's use. .It Va crp_desc This is a linked list of descriptors. Each descriptor provides information about what type of cryptographic operation should be done on the input buffer. The various fields are: .Bl -tag -width ".Va crd_inject" .It Va crd_iv The field where IV should be provided when the .Dv CRD_F_IV_EXPLICIT flag is given. .It Va crd_key When the .Dv CRD_F_KEY_EXPLICIT flag is given, the .Va crd_key points to a buffer with encryption or authentication key. .It Va crd_alg An algorithm to use. Must be the same as the one given at newsession time. .It Va crd_klen The .Va crd_key key length. .It Va crd_skip The offset in the input buffer where processing should start. .It Va crd_len How many bytes, after .Va crd_skip , should be processed. .It Va crd_inject Offset from the beginning of the buffer to insert any results. For encryption algorithms, this is where the initialization vector (IV) will be inserted when encrypting or where it can be found when decrypting (subject to .Va crd_flags ) . For MAC algorithms, this is where the result of the keyed hash will be inserted. .It Va crd_flags The following flags are defined: -.Bl -tag -width ".Dv CRD" +.Bl -tag -width 3n .It Dv CRD_F_ENCRYPT For encryption algorithms, this bit is set when encryption is required (when not set, decryption is performed). .It Dv CRD_F_IV_PRESENT For encryption algorithms, this bit is set when the IV already precedes the data, so the .Va crd_inject value will be ignored and no IV will be written in the buffer. Otherwise, the IV used to encrypt the packet will be written at the location pointed to by .Va crd_inject . The IV length is assumed to be equal to the blocksize of the encryption algorithm. Some applications that do special .Dq "IV cooking" , such as the half-IV mode in .Xr ipsec 4 , can use this flag to indicate that the IV should not be written on the packet. This flag is typically used in conjunction with the .Dv CRD_F_IV_EXPLICIT flag. .It Dv CRD_F_IV_EXPLICIT For encryption algorithms, this bit is set when the IV is explicitly provided by the consumer in the .Va crd_iv field. Otherwise, for encryption operations the IV is provided for by the driver used to perform the operation, whereas for decryption operations it is pointed to by the .Va crd_inject field. This flag is typically used when the IV is calculated .Dq "on the fly" by the consumer, and does not precede the data (some .Xr ipsec 4 configurations, and the encrypted swap are two such examples). .It Dv CRD_F_KEY_EXPLICIT For encryption and authentication (MAC) algorithms, this bit is set when the key is explicitly provided by the consumer in the .Va crd_key field for the given operation. Otherwise, the key is taken at newsession time from the .Va cri_key field. .It Dv CRD_F_COMP For compression algorithms, this bit is set when compression is required (when not set, decompression is performed). .El .It Va CRD_INI This .Vt cryptoini structure will not be modified by the framework or the device drivers. Since this information accompanies every cryptographic operation request, drivers may re-initialize state on-demand (typically an expensive operation). Furthermore, the cryptographic framework may re-route requests as a result of full queues or hardware failure, as described above. .It Va crd_next Point to the next descriptor. Linked operations are useful in protocols such as .Xr ipsec 4 , where multiple cryptographic transforms may be applied on the same block of data. .El .El .Pp .Fn crypto_getreq allocates a .Vt cryptop structure with a linked list of as many .Vt cryptodesc structures as were specified in the argument passed to it. .Pp .Fn crypto_freereq deallocates a structure .Vt cryptop and any .Vt cryptodesc structures linked to it. Note that it is the responsibility of the callback routine to do the necessary cleanups associated with the opaque field in the .Vt cryptop structure. .Pp .Fn crypto_kdispatch is called to perform a keying operation. The various fields in the .Vt cryptkop structure are: .Bl -tag -width ".Va krp_callback' .It Va krp_op Operation code, such as .Dv CRK_MOD_EXP . .It Va krp_status Return code. This .Va errno Ns -style variable indicates whether lower level reasons for operation failure. .It Va krp_iparams Number if input parameters to the specified operation. Note that each operation has a (typically hardwired) number of such parameters. .It Va krp_oparams Number if output parameters from the specified operation. Note that each operation has a (typically hardwired) number of such parameters. .It Va krp_kvp An array of kernel memory blocks containing the parameters. .It Va krp_hid Identifier specifying which low-level driver is being used. .It Va krp_callback Callback called on completion of a keying operation. .El .Sh DRIVER-SIDE API The .Fn crypto_get_driverid , .Fn crypto_register , .Fn crypto_kregister , .Fn crypto_unregister , .Fn crypto_unblock , and .Fn crypto_done routines are used by drivers that provide support for cryptographic primitives to register and unregister with the kernel crypto services framework. Drivers must first use the .Fn crypto_get_driverid function to acquire a driver identifier, specifying the .Fa cc_flags as an argument (normally 0, but software-only drivers should specify .Dv CRYPTOCAP_F_SOFTWARE ) . For each algorithm the driver supports, it must then call .Fn crypto_register . The first two arguments are the driver and algorithm identifiers. The next two arguments specify the largest possible operator length (in bits, important for public key operations) and flags for this algorithm. The last four arguments must be provided in the first call to .Fn crypto_register and are ignored in all subsequent calls. They are pointers to three driver-provided functions that the framework may call to establish new cryptographic context with the driver, free already established context, and ask for a request to be processed (encrypt, decrypt, etc.); and an opaque parameter to pass when calling each of these routines. .Fn crypto_unregister is called by drivers that wish to withdraw support for an algorithm. The two arguments are the driver and algorithm identifiers, respectively. Typically, drivers for PCMCIA crypto cards that are being ejected will invoke this routine for all algorithms supported by the card. .Fn crypto_unregister_all will unregister all algorithms registered by a driver and the driver will be disabled (no new sessions will be allocated on that driver, and any existing sessions will be migrated to other drivers). The same will be done if all algorithms associated with a driver are unregistered one by one. .Pp The calling convention for the three driver-supplied routines is: .Pp .Bl -item -compact .It .Ft int .Fn \*[lp]*newsession\*[rp] "void *" "u_int32_t *" "struct cryptoini *" ; .It .Ft int .Fn \*[lp]*freesession\*[rp] "void *" "u_int64_t" ; .It .Ft int .Fn \*[lp]*process\*[rp] "void *" "struct cryptop *" ; .It .Ft int .Fn \*[lp]*kprocess\*[rp] "void *" "struct cryptkop *" ; .El .Pp On invocation, the first argument to all routines is an opaque data value supplied when the algorithm is registered with .Fn crypto_register . The second argument to .Fn newsession contains the driver identifier obtained via .Fn crypto_get_driverid . On successful return, it should contain a driver-specific session identifier. The third argument is identical to that of .Fn crypto_newsession . .Pp The .Fn freesession routine takes as arguments the opaque data value and the SID (which is the concatenation of the driver identifier and the driver-specific session identifier). It should clear any context associated with the session (clear hardware registers, memory, etc.). .Pp The .Fn process routine is invoked with a request to perform crypto processing. This routine must not block, but should queue the request and return immediately. Upon processing the request, the callback routine should be invoked. In case of an unrecoverable error, the error indication must be placed in the .Va crp_etype field of the .Vt cryptop structure. When the request is completed, or an error is detected, the .Fn process routine should invoke .Fn crypto_done . Session migration may be performed, as mentioned previously. .Pp In case of a temporary resource exhaustion, the .Fn process routine may return .Er ERESTART in which case the crypto services will requeue the request, mark the driver as .Dq blocked , and stop submitting requests for processing. The driver is then responsible for notifying the crypto services when it is again able to process requests through the .Fn crypto_unblock routine. This simple flow control mechanism should only be used for short-lived resource exhaustion as it causes operations to be queued in the crypto layer. Doing so is preferable to returning an error in such cases as it can cause network protocols to degrade performance by treating the failure much like a lost packet. .Pp The .Fn kprocess routine is invoked with a request to perform crypto key processing. This routine must not block, but should queue the request and return immediately. Upon processing the request, the callback routine should be invoked. In case of an unrecoverable error, the error indication must be placed in the .Va krp_status field of the .Vt cryptkop structure. When the request is completed, or an error is detected, the .Fn kprocess routine should invoked .Fn crypto_kdone . .Sh RETURN VALUES .Fn crypto_register , .Fn crypto_kregister , .Fn crypto_unregister , .Fn crypto_newsession , .Fn crypto_freesession , and .Fn crypto_unblock return 0 on success, or an error code on failure. .Fn crypto_get_driverid returns a non-negative value on error, and \-1 on failure. .Fn crypto_getreq returns a pointer to a .Vt cryptop structure and .Dv NULL on failure. .Fn crypto_dispatch returns .Er EINVAL if its argument or the callback function was .Dv NULL , and 0 otherwise. The callback is provided with an error code in case of failure, in the .Va crp_etype field. .Sh FILES .Bl -tag -width ".Pa sys/opencrypto/crypto.c" .It Pa sys/opencrypto/crypto.c most of the framework code .El .Sh SEE ALSO .Xr ipsec 4 , .Xr malloc 9 , .Xr sleep 9 .Sh HISTORY The cryptographic framework first appeared in .Ox 2.7 and was written by .An "Angelos D. Keromytis" Aq angelos@openbsd.org . .Sh BUGS The framework currently assumes that all the algorithms in a .Fn crypto_newsession operation must be available by the same driver. If that is not the case, session initialization will fail. .Pp The framework also needs a mechanism for determining which driver is best for a specific set of algorithms associated with a session. Some type of benchmarking is in order here. .Pp Multiple instances of the same algorithm in the same session are not supported. Note that 3DES is considered one algorithm (and not three instances of DES). Thus, 3DES and DES could be mixed in the same request. Index: head/share/man/man9/ktr.9 =================================================================== --- head/share/man/man9/ktr.9 (revision 162403) +++ head/share/man/man9/ktr.9 (revision 162404) @@ -1,147 +1,147 @@ .\" 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 +.Dd December 27, 2005 .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" .Ft void .Fn CTR6 "u_int mask" "char *format" "arg1" "arg2" "arg3" "arg4" "arg5" "arg6" .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 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/memguard.9 =================================================================== --- head/share/man/man9/memguard.9 (revision 162403) +++ head/share/man/man9/memguard.9 (revision 162404) @@ -1,106 +1,112 @@ .\" Copyright (c) 2005 Christian Brueffer .\" 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 31, 2006 .Dt MEMGUARD 9 .Os .Sh NAME .Nm MemGuard .Nd "memory allocator for debugging purposes" .Sh SYNOPSIS .Cd "options DEBUG_MEMGUARD" .Sh DESCRIPTION .Nm is a simple and small replacement memory allocator designed to help detect tamper-after-free scenarios. These problems are more and more common and likely with multithreaded kernels where race conditions are more prevalent. .Pp Currently, .Nm can only take over .Fn malloc , .Fn realloc and .Fn free for a particular malloc type. .Sh EXAMPLES -To use memguard for memory type compiled into the kernel, one has to add the +To use +.Nm +for memory type compiled into the kernel, one has to add the following line to the .Pa /boot/loader.conf : .Bd -literal -offset indent vm.memguard.desc= .Ed .Pp -Where memory_type is a short description of memory type to monitor. +Where +.Ar memory_type +is a short description of memory type to monitor. The short description of memory type is the second argument to .Xr MALLOC_DEFINE 9 , so one has to find it in the kernel source. .Pp -To use memguard for memory type defined in a kernel module, one has to set +To use +.Nm +for memory type defined in a kernel module, one has to set .Va vm.memguard.desc .Xr sysctl 8 variable before loading the module: .Bd -literal -offset indent sysctl vm.memguard.desc= .Ed .Pp The .Va vm.memguard.divisor boot-time tunable is used to scale how much of .Va kmem_map one wants to allocate for .Nm . The default is 10, so .Va kmem_size Ns /10 bytes will be used. The .Va kmem_size value can be obtained via the .Va vm.kmem_size .Xr sysctl 8 variable. .Sh SEE ALSO .Xr sysctl 8 , .Xr vmstat 8 , .Xr contigmalloc 9 , .Xr malloc 9 , .Xr redzone 9 .Sh HISTORY .Nm first appeared in .Fx 6.0 . .Sh AUTHORS .An -nosplit .Nm was written by .An Bosko Milekic Aq bmilekic@FreeBSD.org . This manual page was written by .An Christian Brueffer Aq brueffer@FreeBSD.org . .Sh BUGS Currently, it is not possible to override UMA .Xr zone 9 allocations. Index: head/share/man/man9/pfil.9 =================================================================== --- head/share/man/man9/pfil.9 (revision 162403) +++ head/share/man/man9/pfil.9 (revision 162404) @@ -1,216 +1,216 @@ .\" $NetBSD: pfil.9,v 1.22 2003/07/01 13:04:06 wiz Exp $ .\" .\" Copyright (c) 1996 Matthew R. Green .\" 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 ``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 29, 2004 .Dt PFIL 9 .Os .Sh NAME .Nm pfil , .Nm pfil_head_register , .Nm pfil_head_unregister , .Nm pfil_head_get , .Nm pfil_hook_get , .Nm pfil_add_hook , .Nm pfil_remove_hook , .Nm pfil_run_hooks .Nd packet filter interface .Sh SYNOPSIS .In sys/param.h .In sys/mbuf.h .In net/if.h .In net/pfil.h .Ft int .Fn pfil_head_register "struct pfil_head *head" .Ft int .Fn pfil_head_unregister "struct pfil_head *head" .Ft "struct pfil_head *" .Fn pfil_head_get "int af" "u_long dlt" .Ft "struct packet_filter_hook *" .Fn pfil_hook_get "int dir" "struct pfil_head *head" .Ft void .Fn pfil_add_hook "int (*func)()" "void *arg" "int flags" "struct pfil_head *" .Ft void .Fn pfil_remove_hook "int (*func)()" "void *arg" "int flags" "struct pfil_head *" .Ft int .Fn (*func) "void *arg" "struct mbuf **mp" "struct ifnet *" "int dir" "struct inpcb *" .Ft int .Fn pfil_run_hooks "struct pfil_head *head" "struct mbuf **mp" "struct ifnet *" "int dir" "struct inpcb *" .Sh DESCRIPTION The .Nm framework allows for a specified function to be invoked for every incoming or outgoing packet for a particular network I/O stream. These hooks may be used to implement a firewall or perform packet transformations. .Pp Packet filtering points are registered with .Fn pfil_head_register . Filtering points are identified by a key .Pq Vt "void *" and a data link type .Pq Vt int in the .Vt pfil_head structure. Packet filters use the key and data link type to look up the filtering point with which they register themselves. The key is unique to the filtering point. The data link type is a .Xr bpf 4 DLT constant indicating what kind of header is present on the packet at the filtering point. Filtering points may be unregistered with the .Fn pfil_head_unregister function. .Pp Packet filters register/unregister themselves with a filtering point with the .Fn pfil_add_hook and .Fn pfil_remove_hook functions, respectively. The head is looked up using the .Fn pfil_head_get function, which takes the key and data link type that the packet filter expects. Filters may provide an argument to be passed to the filter when invoked on a packet. .Pp When a filter is invoked, the packet appears just as if it .Dq came off the wire . That is, all protocol fields are in network byte order. The filter is called with its specified argument, the pointer to the pointer to the .Vt mbuf containing the packet, the pointer to the network interface that the packet is traversing, and the direction .Dv ( PFIL_IN or .Dv PFIL_OUT ) that the packet is traveling. The filter may change which mbuf the .Vt "mbuf\ **" argument references. The filter returns an error (errno) if the packet processing is to stop, or 0 if the processing is to continue. If the packet processing is to stop, it is the responsibility of the filter to free the packet. .Sh RETURN VALUES If successful, .Fn pfil_head_get returns the .Vt pfil_head structure for the given key/dlt. The .Fn pfil_add_hook and .Fn pfil_remove_hook functions return 0 if successful. If called with flag .Dv PFIL_WAITOK , .Fn pfil_remove_hook is expected to always succeed. .Pp The .Fn pfil_head_unregister function might sleep! .Sh SEE ALSO .Xr bpf 4 , .Xr if_bridge 4 .Sh HISTORY The .Nm interface first appeared in .Nx 1.3 . The .Nm input and output lists were originally implemented as .In sys/queue.h .Dv LIST structures; however this was changed in .Nx 1.4 to .Dv TAILQ structures. This change was to allow the input and output filters to be processed in reverse order, to allow the same path to be taken, in or out of the kernel. .Pp The .Nm interface was changed in 1.4T to accept a 3rd parameter to both .Fn pfil_add_hook and .Fn pfil_remove_hook , introducing the capability of per-protocol filtering. This was done primarily in order to support filtering of IPv6. .Pp In 1.5K, the .Nm framework was changed to work with an arbitrary number of filtering points, as well as be less IP-centric. .Pp Fine-grained locking was added in .Fx 5.2 . .Sh BUGS The .Fn pfil_hook_get function is only safe for internal use. .Pp .Fx implements only hooks for .Dv AF_INET and .Dv AF_INET6 . Packets diverted through these hooks have data in host byte order contrary to the above statements. .Pp The .Xr if_bridge 4 diverts .Dv AF_INET and -.DV AF_INET6 -traffic according to it's sysctl settings, but contrary to the above +.Dv AF_INET6 +traffic according to its sysctl settings, but contrary to the above statements, the data is provided in host byte order. .Pp When a .Vt pfil_head is being modified, no traffic is diverted (to avoid deadlock). This means that traffic may be dropped unconditionally for a short period of time. .Fn pfil_run_hooks will return .Er ENOBUFS to indicate this. Index: head/share/man/man9/sbuf.9 =================================================================== --- head/share/man/man9/sbuf.9 (revision 162403) +++ head/share/man/man9/sbuf.9 (revision 162404) @@ -1,370 +1,380 @@ .\"- .\" Copyright (c) 2000 Poul Henning Kamp and Dag-Erling Coïdan Smørgrav .\" 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 9, 2004 .Dt SBUF 9 .Os .Sh NAME +.Nm sbuf , .Nm sbuf_new , .Nm sbuf_clear , .Nm sbuf_setpos , .Nm sbuf_bcat , .Nm sbuf_bcopyin , .Nm sbuf_bcpy , .Nm sbuf_cat , .Nm sbuf_copyin , .Nm sbuf_cpy , .Nm sbuf_printf , .Nm sbuf_vprintf , .Nm sbuf_putc , .Nm sbuf_trim , .Nm sbuf_overflowed , .Nm sbuf_finish , .Nm sbuf_data , .Nm sbuf_len , .Nm sbuf_done , .Nm sbuf_delete .Nd safe string formatting .Sh SYNOPSIS .In sys/types.h .In sys/sbuf.h .Ft struct sbuf * .Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags" .Ft void .Fn sbuf_clear "struct sbuf *s" .Ft int .Fn sbuf_setpos "struct sbuf *s" "int pos" .Ft int .Fn sbuf_bcat "struct sbuf *s" "const void *buf" "size_t len" .Ft int .Fn sbuf_bcopyin "struct sbuf *s" "const void *uaddr" "size_t len" .Ft int .Fn sbuf_bcpy "struct sbuf *s" "const void *buf" "size_t len" .Ft int .Fn sbuf_cat "struct sbuf *s" "const char *str" .Ft int .Fn sbuf_copyin "struct sbuf *s" "const void *uaddr" "size_t len" .Ft int .Fn sbuf_cpy "struct sbuf *s" "const char *str" .Ft int .Fn sbuf_printf "struct sbuf *s" "const char *fmt" "..." .Ft int .Fn sbuf_vprintf "struct sbuf *s" "const char *fmt" "va_list ap" .Ft int .Fn sbuf_putc "struct sbuf *s" "int c" .Ft int .Fn sbuf_trim "struct sbuf *s" .Ft int .Fn sbuf_overflowed "struct sbuf *s" .Ft void .Fn sbuf_finish "struct sbuf *s" .Ft char * .Fn sbuf_data "struct sbuf *s" .Ft int .Fn sbuf_len "struct sbuf *s" .Ft int .Fn sbuf_done "struct sbuf *s" .Ft void .Fn sbuf_delete "struct sbuf *s" .Sh DESCRIPTION The -.Nm sbuf +.Nm family of functions allows one to safely allocate, construct and release bounded null-terminated strings in kernel space. Instead of arrays of characters, these functions operate on structures called .Fa sbufs , defined in .In sys/sbuf.h . .Pp The .Fn sbuf_new function initializes the .Fa sbuf pointed to by its first argument. If that pointer is .Dv NULL , .Fn sbuf_new allocates a .Vt struct sbuf using .Xr malloc 9 . The .Fa buf argument is a pointer to a buffer in which to store the actual string; if it is .Dv NULL , .Fn sbuf_new will allocate one using .Xr malloc 9 . The .Fa length is the initial size of the storage buffer. The fourth argument, .Fa flags , may be comprised of the following flags: .Bl -tag -width ".Dv SBUF_AUTOEXTEND" .It Dv SBUF_FIXEDLEN The storage buffer is fixed at its initial size. Attempting to extend the sbuf beyond this size results in an overflow condition. .It Dv SBUF_AUTOEXTEND This indicates that the storage buffer may be extended as necessary, so long as resources allow, to hold additional data. .El .Pp Note that if .Fa buf is not .Dv NULL , it must point to an array of at least .Fa length characters. The result of accessing that array directly while it is in use by the sbuf is undefined. .Pp The .Fn sbuf_delete function clears the .Fa sbuf and frees any memory allocated for it. There must be a call to .Fn sbuf_delete for every call to .Fn sbuf_new . Any attempt to access the sbuf after it has been deleted will fail. .Pp The .Fn sbuf_clear function invalidates the contents of the .Fa sbuf and resets its position to zero. .Pp The .Fn sbuf_setpos function sets the .Fa sbuf Ns 's end position to .Fa pos , which is a value between zero and one less than the size of the storage buffer. This effectively truncates the sbuf at the new position. .Pp The .Fn sbuf_bcat function appends the first .Fa len bytes from the buffer .Fa buf to the .Fa sbuf . .Pp The .Fn sbuf_bcopyin function copies .Fa len bytes from the specified userland address into the .Fa sbuf . .Pp The .Fn sbuf_bcpy function replaces the contents of the .Fa sbuf with the first .Fa len bytes from the buffer .Fa buf . .Pp The .Fn sbuf_cat function appends the NUL-terminated string .Fa str to the .Fa sbuf at the current position. .Pp The .Fn sbuf_copyin function copies a NUL-terminated string from the specified userland address into the .Fa sbuf . If the .Fa len argument is non-zero, no more than .Fa len characters (not counting the terminating NUL) are copied; otherwise the entire string, or as much of it as can fit in the .Fa sbuf , is copied. .Pp The .Fn sbuf_cpy function replaces the contents of the .Fa sbuf with those of the NUL-terminated string .Fa str . This is equivalent to calling .Fn sbuf_cat with a fresh .Fa sbuf or one which position has been reset to zero with .Fn sbuf_clear or .Fn sbuf_setpos . .Pp The .Fn sbuf_printf function formats its arguments according to the format string pointed to by .Fa fmt and appends the resulting string to the .Fa sbuf at the current position. .Pp The .Fn sbuf_vprintf function behaves the same as .Fn sbuf_printf except that the arguments are obtained from the variable-length argument list .Fa ap . .Pp The .Fn sbuf_putc function appends the character .Fa c to the .Fa sbuf at the current position. .Pp The .Fn sbuf_trim function removes trailing whitespace from the .Fa sbuf . .Pp The .Fn sbuf_overflowed function returns a non-zero value if the .Fa sbuf overflowed. .Pp The .Fn sbuf_finish function null-terminates the .Fa sbuf and marks it as finished, which means that it may no longer be modified using .Fn sbuf_setpos , .Fn sbuf_cat , .Fn sbuf_cpy , .Fn sbuf_printf or .Fn sbuf_putc . .Pp The .Fn sbuf_data and .Fn sbuf_len functions return the actual string and its length, respectively; .Fn sbuf_data only works on a finished .Fa sbuf . .Fn sbuf_done returns non-zero if the sbuf is finished. .Sh NOTES If an operation caused an .Fa sbuf to overflow, most subsequent operations on it will fail until the .Fa sbuf is finished using .Fn sbuf_finish or reset using .Fn sbuf_clear , or its position is reset to a value between 0 and one less than the size of its storage buffer using .Fn sbuf_setpos , or it is reinitialized to a sufficiently short string using .Fn sbuf_cpy . .Sh RETURN VALUES +The .Fn sbuf_new -returns +function returns .Dv NULL if it failed to allocate a storage buffer, and a pointer to the new .Fa sbuf otherwise. .Pp +The .Fn sbuf_setpos -returns \-1 if +function returns \-1 if .Fa pos was invalid, and zero otherwise. .Pp +The .Fn sbuf_cat , .Fn sbuf_cpy , .Fn sbuf_printf , .Fn sbuf_putc , and .Fn sbuf_trim +functions all return \-1 if the buffer overflowed, and zero otherwise. .Pp +The .Fn sbuf_overflowed +function returns a non-zero value if the buffer overflowed, and zero otherwise. .Pp +The .Fn sbuf_data and .Fn sbuf_len -return +functions return .Dv NULL and \-1, respectively, if the buffer overflowed. .Pp +The .Fn sbuf_copyin +function returns \-1 if copying string from userland failed, and number of bytes copied otherwise. .Sh SEE ALSO .Xr printf 3 , .Xr strcat 3 , .Xr strcpy 3 , .Xr copyin 9 , .Xr copyinstr 9 , .Xr printf 9 .Sh HISTORY The -.Nm sbuf +.Nm family of functions first appeared in .Fx 4.4 . .Sh AUTHORS .An -nosplit The -.Nm sbuf +.Nm family of functions was designed by .An Poul-Henning Kamp Aq phk@FreeBSD.org and implemented by .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org . Additional improvements were suggested by .An Justin T. Gibbs Aq gibbs@FreeBSD.org . Auto-extend support added by .An Kelly Yancey Aq kbyanc@FreeBSD.org . .Pp This manual page was written by .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org . Index: head/share/man/man9/sleep.9 =================================================================== --- head/share/man/man9/sleep.9 (revision 162403) +++ head/share/man/man9/sleep.9 (revision 162404) @@ -1,225 +1,225 @@ .\" .\" Copyright (c) 1996 Joerg Wunsch .\" .\" 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 December 17, 1998 +.Dd April 17, 2006 .Os .Dt SLEEP 9 .Sh NAME .Nm msleep , .Nm msleep_spin , .Nm tsleep , .Nm wakeup .Nd wait for events .Sh SYNOPSIS .In sys/param.h .In sys/systm.h .In sys/proc.h .Ft int .Fn tsleep "void *chan" "int priority" "const char *wmesg" "int timo" .Ft int .Fn msleep "void *chan" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo" .Ft int .Fn msleep_spin "void *chan" "struct mtx *mtx" "const char *wmesg" "int timo" .Ft void .Fn wakeup "void *chan" .Ft void .Fn wakeup_one "void *chan" .Sh DESCRIPTION The functions .Fn tsleep , .Fn msleep , .Fn msleep_spin , .Fn wakeup , and .Fn wakeup_one handle event-based thread blocking. If a thread must wait for an external event, it is put to sleep by .Fn tsleep , .Fn msleep , or .Fn msleep_spin . The parameter .Fa chan is an arbitrary address that uniquely identifies the event on which the thread is being asleep. All threads sleeping on a single .Fa chan are woken up later by .Fn wakeup , often called from inside an interrupt routine, to indicate that the resource the thread was blocking on is available now. .Pp The parameter .Fa wmesg is a string describing the sleep condition for tools like .Xr ps 1 . Due to the limited space of those programs to display arbitrary strings, this message should not be longer than 6 characters. .Pp The .Fn wakeup_one function is used to make the first thread in the queue that is sleeping on the parameter .Fa chan runnable. This can prevent the system from becoming saturated when a large number of threads are sleeping on the same address, but only one of them can actually do any useful work when made runnable. .Pp The .Fn msleep function is the general sleep call. It suspends the current thread until a wakeup is performed on the specified identifier. The .Fa mtx parameter is a mutex which will be released before sleeping and reacquired before .Fn msleep returns. If .Fa priority includes the .Dv PDROP flag, the .Fa mtx parameter will not be reacquired before returning. The mutex is used to ensure that a condition can be checked atomically, and that the current thread can be suspended without missing a change to the condition, or an associated wakeup. If .Fa priority is not 0, then the thread will be made runnable with the specified .Fa priority when it resumes. If .Fa timo is not 0, then the thread will sleep for at most -.Fa timo -\&/ hz seconds. +.Fa timo No / Va hz +seconds. If the .Va Giant lock is not held and .Fa mtx is .Dv NULL , then .Fa timo must be non-zero. If .Fa priority includes the .Dv PCATCH flag, signals are checked before and after sleeping, otherwise signals are not checked. The .Fn msleep function returns 0 if awakened, .Er EWOULDBLOCK if the timeout expires. If .Dv PCATCH is set and a signal needs to be delivered, .Er ERESTART is returned if the current system call should be restarted if possible, and .Er EINTR is returned if the system call should be interrupted by the signal (return .Er EINTR ) . .Pp The .Fn tsleep function is a variation on .Fn msleep . It is identical to invoking .Fn msleep with a .Dv NULL .Fa mtx parameter. .Pp The .Fn msleep_spin function is another variation on .Fn msleep . This function accepts a spin mutex rather than a default mutex for its .Fa mtx parameter. It is also more limited in that it does not accept a .Fa priority parameter. Thus, it will not change the priority of a sleeping thread, and it does not support the .Dv PDROP and .Dv PCATCH flags. .Sh RETURN VALUES See above. .Sh SEE ALSO .Xr ps 1 , .Xr malloc 9 , .Xr mi_switch 9 .Sh HISTORY The sleep/wakeup thread synchronization mechanism is very old. It appeared in a very early version of .Ux . .Pp The .Fn tsleep function appeared in .Bx 4.4 . The .Fn wakeup_one function appeared in .Fx 2.2 . The .Fn msleep function appeared in .Fx 5.0 , and the .Fn msleep_spin function appeared in .Fx 7.0 . .Pp The .Fn sleep function used to be the traditional form. It did not let you specify a timeout or a .Fa wmesg , hence it was discontinued. .Sh AUTHORS .An -nosplit This manual page was written by .An J\(:org Wunsch Aq joerg@FreeBSD.org .