1*ae5984bfSjruoho.\" $NetBSD: STACK.9,v 1.2 2011/04/08 07:55:04 jruoho Exp $ 21a6962b4Sjruoho.\" 31a6962b4Sjruoho.\" Copyright (c) 2010 The NetBSD Foundation, Inc. 41a6962b4Sjruoho.\" All rights reserved. 51a6962b4Sjruoho.\" 61a6962b4Sjruoho.\" This code is derived from software contributed to The NetBSD Foundation 71a6962b4Sjruoho.\" by Jukka Ruohonen. 81a6962b4Sjruoho.\" 91a6962b4Sjruoho.\" Redistribution and use in source and binary forms, with or without 101a6962b4Sjruoho.\" modification, are permitted provided that the following conditions 111a6962b4Sjruoho.\" are met: 121a6962b4Sjruoho.\" 1. Redistributions of source code must retain the above copyright 131a6962b4Sjruoho.\" notice, this list of conditions and the following disclaimer. 141a6962b4Sjruoho.\" 2. Redistributions in binary form must reproduce the above copyright 151a6962b4Sjruoho.\" notice, this list of conditions and the following disclaimer in the 161a6962b4Sjruoho.\" documentation and/or other materials provided with the distribution. 171a6962b4Sjruoho.\" 181a6962b4Sjruoho.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 191a6962b4Sjruoho.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 201a6962b4Sjruoho.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 211a6962b4Sjruoho.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 221a6962b4Sjruoho.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 231a6962b4Sjruoho.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 241a6962b4Sjruoho.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 251a6962b4Sjruoho.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 261a6962b4Sjruoho.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 271a6962b4Sjruoho.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 281a6962b4Sjruoho.\" POSSIBILITY OF SUCH DAMAGE. 291a6962b4Sjruoho.\" 30*ae5984bfSjruoho.Dd April 8, 2011 311a6962b4Sjruoho.Dt STACK 9 321a6962b4Sjruoho.Os 331a6962b4Sjruoho.Sh NAME 341a6962b4Sjruoho.Nm STACK 351a6962b4Sjruoho.Nd stack macros 361a6962b4Sjruoho.Sh SYNOPSIS 371a6962b4Sjruoho.In sys/param.h 381a6962b4Sjruoho.Ft type 391a6962b4Sjruoho.Fn STACK_ALLOC "sp" "size" 401a6962b4Sjruoho.Ft type 411a6962b4Sjruoho.Fn STACK_MAX "sp" "size" 421a6962b4Sjruoho.Ft type 431a6962b4Sjruoho.Fn STACK_ALIGN "sp" "bytes" 441a6962b4Sjruoho.Ft type 451a6962b4Sjruoho.Fn STACK_GROW "sp" "size" 461a6962b4Sjruoho.Ft type 471a6962b4Sjruoho.Fn STACK_SHRINK "sp" "size" 481a6962b4Sjruoho.Sh DESCRIPTION 491a6962b4SjruohoA stack is an area of memory with a fixed origin but with a variable size. 501a6962b4SjruohoA stack pointer points to the most recently referenced location on the stack. 511a6962b4SjruohoInitially, when the stack has a size of zero, 521a6962b4Sjruohothe stack pointer points to the origin of the stack. 531a6962b4SjruohoWhen data items are added to the stack, 541a6962b4Sjruohothe stack pointer moves away from the origin. 551a6962b4Sjruoho.Pp 561a6962b4SjruohoThe 571a6962b4Sjruoho.Fn STACK_ALLOC 581a6962b4Sjruohomacro returns a pointer to allocated stack space of some 591a6962b4Sjruoho.Fa size . 601a6962b4SjruohoGiven the returned pointer 611a6962b4Sjruoho.Fa sp 621a6962b4Sjruohoand 631a6962b4Sjruoho.Fa size , 641a6962b4Sjruoho.Fn STACK_MAX 651a6962b4Sjruohoreturns the maximum stack address of the allocated stack space. 661a6962b4SjruohoThe 671a6962b4Sjruoho.Fn STACK_ALIGN 681a6962b4Sjruohomacro can be used to align the stack pointer 691a6962b4Sjruoho.Fa sp 701a6962b4Sjruohoby the specified amount of 711a6962b4Sjruoho.Fa bytes . 721a6962b4Sjruoho.Pp 731a6962b4SjruohoTwo basic operations are common to all stacks: 741a6962b4Sjruohoa data item is added 751a6962b4Sjruoho.Pq Dq push 761a6962b4Sjruohoto the location pointed by 771a6962b4Sjruoho.Fa sp 781a6962b4Sjruohoor a data item is removed 791a6962b4Sjruoho.Pq Dq pop 801a6962b4Sjruohofrom the stack. 811a6962b4SjruohoThe stack pointer must be subsequently adjusted by the size of the data item. 821a6962b4SjruohoThe 831a6962b4Sjruoho.Fn STACK_GROW 841a6962b4Sjruohoand 851a6962b4Sjruoho.Fn STACK_SHRINK 861a6962b4Sjruohomacros adjust the stack pointer 871a6962b4Sjruoho.Fa sp 881a6962b4Sjruohoby given 891a6962b4Sjruoho.Fa size . 901a6962b4Sjruoho.Pp 911a6962b4SjruohoA stack may grow either up or down. 921a6962b4SjruohoThe described macros take this into account by using the 931a6962b4Sjruoho.Dv __MACHINE_STACK_GROWS_UP 941a6962b4Sjruohopreprocessor define. 951a6962b4Sjruoho.Sh SEE ALSO 96*ae5984bfSjruoho.Xr param 3 , 971a6962b4Sjruoho.Xr queue 3 98