Module Name: src Committed By: jruoho Date: Fri Jul 30 09:13:00 UTC 2010
Modified Files: src/distrib/sets/lists/comp: mi src/share/man/man9: Makefile Added Files: src/share/man/man9: STACK.9 Log Message: Document the stack macros from <sys/param.h>. To generate a diff of this commit: cvs rdiff -u -r1.1486 -r1.1487 src/distrib/sets/lists/comp/mi cvs rdiff -u -r1.336 -r1.337 src/share/man/man9/Makefile cvs rdiff -u -r0 -r1.1 src/share/man/man9/STACK.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Modified files: Index: src/distrib/sets/lists/comp/mi diff -u src/distrib/sets/lists/comp/mi:1.1486 src/distrib/sets/lists/comp/mi:1.1487 --- src/distrib/sets/lists/comp/mi:1.1486 Mon Jul 26 16:23:31 2010 +++ src/distrib/sets/lists/comp/mi Fri Jul 30 09:12:58 2010 @@ -1,4 +1,4 @@ -# $NetBSD: mi,v 1.1486 2010/07/26 16:23:31 pooka Exp $ +# $NetBSD: mi,v 1.1487 2010/07/30 09:12:58 jruoho Exp $ # # Note: don't delete entries from here - mark them as "obsolete" instead. # @@ -8635,6 +8635,12 @@ ./usr/share/man/cat9/SCHED_LOCK.0 comp-obsolete obsolete ./usr/share/man/cat9/SCHED_UNLOCK.0 comp-obsolete obsolete ./usr/share/man/cat9/SET.0 comp-sys-catman .cat +./usr/share/man/cat9/STACK.0 comp-sys-catman .cat +./usr/share/man/cat9/STACK_ALIGN.0 comp-sys-catman .cat +./usr/share/man/cat9/STACK_ALLOC.0 comp-sys-catman .cat +./usr/share/man/cat9/STACK_GROW.0 comp-sys-catman .cat +./usr/share/man/cat9/STACK_MAX.0 comp-sys-catman .cat +./usr/share/man/cat9/STACK_SHRINK.0 comp-sys-catman .cat ./usr/share/man/cat9/TC_DENSE_TO_SPARSE.0 comp-sys-catman .cat ./usr/share/man/cat9/TC_PHYS_TO_UNCACHED.0 comp-sys-catman .cat ./usr/share/man/cat9/VATTR_NULL.0 comp-obsolete obsolete @@ -14435,6 +14441,12 @@ ./usr/share/man/html9/PMC_ENABLED.html comp-sys-htmlman html ./usr/share/man/html9/RUN_ONCE.html comp-sys-htmlman html ./usr/share/man/html9/SET.html comp-sys-htmlman html +./usr/share/man/html9/STACK.html comp-sys-htmlman html +./usr/share/man/html9/STACK_ALIGN.html comp-sys-htmlman html +./usr/share/man/html9/STACK_ALLOC.html comp-sys-htmlman html +./usr/share/man/html9/STACK_GROW.html comp-sys-htmlman html +./usr/share/man/html9/STACK_MAX.html comp-sys-htmlman html +./usr/share/man/html9/STACK_SHRINK.html comp-sys-htmlman html ./usr/share/man/html9/TC_DENSE_TO_SPARSE.html comp-sys-htmlman html ./usr/share/man/html9/TC_PHYS_TO_UNCACHED.html comp-sys-htmlman html ./usr/share/man/html9/VATTR_NULL.html comp-obsolete obsolete @@ -20328,6 +20340,12 @@ ./usr/share/man/man9/SCHED_LOCK.9 comp-obsolete obsolete ./usr/share/man/man9/SCHED_UNLOCK.9 comp-obsolete obsolete ./usr/share/man/man9/SET.9 comp-sys-man .man +./usr/share/man/man9/STACK.9 comp-sys-man .man +./usr/share/man/man9/STACK_ALIGN.9 comp-sys-man .man +./usr/share/man/man9/STACK_ALLOC.9 comp-sys-man .man +./usr/share/man/man9/STACK_GROW.9 comp-sys-man .man +./usr/share/man/man9/STACK_MAX.9 comp-sys-man .man +./usr/share/man/man9/STACK_SHRINK.9 comp-sys-man .man ./usr/share/man/man9/TC_DENSE_TO_SPARSE.9 comp-sys-man .man ./usr/share/man/man9/TC_PHYS_TO_UNCACHED.9 comp-sys-man .man ./usr/share/man/man9/VATTR_NULL.9 comp-obsolete obsolete Index: src/share/man/man9/Makefile diff -u src/share/man/man9/Makefile:1.336 src/share/man/man9/Makefile:1.337 --- src/share/man/man9/Makefile:1.336 Sun Jul 25 21:05:14 2010 +++ src/share/man/man9/Makefile Fri Jul 30 09:13:00 2010 @@ -1,4 +1,4 @@ -# $NetBSD: Makefile,v 1.336 2010/07/25 21:05:14 jruoho Exp $ +# $NetBSD: Makefile,v 1.337 2010/07/30 09:13:00 jruoho Exp $ # Makefile for section 9 (kernel function and variable) manual pages. @@ -42,7 +42,7 @@ pmc.9 pmf.9 pool.9 pool_cache.9 powerhook_establish.9 ppsratecheck.9 \ preempt.9 proc_find.9 putter.9 \ radio.9 ras.9 rasops.9 ratecheck.9 resettodr.9 rnd.9 roundup.9 \ - rssadapt.9 rt_timer.9 rwlock.9 RUN_ONCE.9 \ + rssadapt.9 rt_timer.9 rwlock.9 RUN_ONCE.9 STACK.9 \ sched_4bsd.9 sched_m2.9 scsipi.9 \ secmodel.9 secmodel_bsd44.9 secmodel_overlay.9 secmodel_securelevel.9 \ secmodel_suser.9 SET.9 setbit.9 setjmp.9 shutdownhook_establish.9 \ @@ -620,6 +620,11 @@ rwlock.9 rw_tryenter.9 rwlock.9 rw_tryupgrade.9 \ rwlock.9 rw_downgrade.9 rwlock.9 rw_read_held.9 \ rwlock.9 rw_write_held.9 rwlock.9 rw_lock_held.9 +MLINKS+=STACK.9 STACK_ALLOC.9 \ + STACK.9 STACK_MAX.9 \ + STACK.9 STACK_ALIGN.9 \ + STACK.9 STACK_GROW.9 \ + STACK.9 STACK_SHRINK.9 MAN+= select.9 MLINKS+=select.9 selinit.9 \ select.9 seldestroy.9 \ Added files: Index: src/share/man/man9/STACK.9 diff -u /dev/null src/share/man/man9/STACK.9:1.1 --- /dev/null Fri Jul 30 09:13:00 2010 +++ src/share/man/man9/STACK.9 Fri Jul 30 09:13:00 2010 @@ -0,0 +1,96 @@ +.\" $NetBSD: STACK.9,v 1.1 2010/07/30 09:13:00 jruoho Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 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. +.\" +.Dd July 30, 2010 +.Dt STACK 9 +.Os +.Sh NAME +.Nm STACK +.Nd stack macros +.Sh SYNOPSIS +.In sys/param.h +.Ft type +.Fn STACK_ALLOC "sp" "size" +.Ft type +.Fn STACK_MAX "sp" "size" +.Ft type +.Fn STACK_ALIGN "sp" "bytes" +.Ft type +.Fn STACK_GROW "sp" "size" +.Ft type +.Fn STACK_SHRINK "sp" "size" +.Sh DESCRIPTION +A stack is an area of memory with a fixed origin but with a variable size. +A stack pointer points to the most recently referenced location on the stack. +Initially, when the stack has a size of zero, +the stack pointer points to the origin of the stack. +When data items are added to the stack, +the stack pointer moves away from the origin. +.Pp +The +.Fn STACK_ALLOC +macro returns a pointer to allocated stack space of some +.Fa size . +Given the returned pointer +.Fa sp +and +.Fa size , +.Fn STACK_MAX +returns the maximum stack address of the allocated stack space. +The +.Fn STACK_ALIGN +macro can be used to align the stack pointer +.Fa sp +by the specified amount of +.Fa bytes . +.Pp +Two basic operations are common to all stacks: +a data item is added +.Pq Dq push +to the location pointed by +.Fa sp +or a data item is removed +.Pq Dq pop +from the stack. +The stack pointer must be subsequently adjusted by the size of the data item. +The +.Fn STACK_GROW +and +.Fn STACK_SHRINK +macros adjust the stack pointer +.Fa sp +by given +.Fa size . +.Pp +A stack may grow either up or down. +The described macros take this into account by using the +.Dv __MACHINE_STACK_GROWS_UP +preprocessor define. +.Sh SEE ALSO +.Xr queue 3