From 2e35a3d99ff23c8a28f2860350b874683dcc4c0b Mon Sep 17 00:00:00 2001 From: jruoho Date: Thu, 4 Mar 2010 08:09:51 +0000 Subject: [PATCH] Document the counting and rounding macros from . --- share/man/man9/Makefile | 10 +++-- share/man/man9/roundup.9 | 96 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 103 insertions(+), 3 deletions(-) create mode 100644 share/man/man9/roundup.9 diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index c9b58107dc93..fa96071668a0 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1,4 +1,4 @@ -# $NetBSD: Makefile,v 1.318 2010/03/01 19:09:41 jruoho Exp $ +# $NetBSD: Makefile,v 1.319 2010/03/04 08:09:51 jruoho Exp $ # Makefile for section 9 (kernel function and variable) manual pages. @@ -41,8 +41,8 @@ MAN= accept_filter.9 accf_data.9 accf_http.9 \ pcmcia.9 pcq.9 percpu.9 pfil.9 physio.9 pmap.9 pmatch.9 pmc.9 pmf.9 \ pool.9 pool_cache.9 powerhook_establish.9 ppsratecheck.9 \ preempt.9 putter.9 \ - radio.9 ras.9 rasops.9 ratecheck.9 resettodr.9 rnd.9 rssadapt.9 \ - rt_timer.9 rwlock.9 RUN_ONCE.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 \ sched_4bsd.9 scsipi.9 \ secmodel.9 secmodel_bsd44.9 secmodel_overlay.9 secmodel_securelevel.9 \ secmodel_suser.9 setbit.9 setjmp.9 shutdownhook_establish.9 \ @@ -577,6 +577,10 @@ MLINKS+=rasops.9 rasops_init.9 \ rasops.9 rasops_reconfig.9 MLINKS+=rnd.9 rnd_attach_source.9 rnd.9 rnd_detach_source.9 \ rnd.9 rnd_add_data.9 rnd.9 rnd_add_uint32.9 +MLINKS+=roundup.9 howmany.9 \ + roundup.9 rounddown.9 \ + roundup.9 roundup2.9 \ + roundup.9 powerof2.9 MLINKS+=rssadapt.9 ieee80211_rssadapt_choose.9 \ rssadapt.9 ieee80211_rssadapt_input.9 \ rssadapt.9 ieee80211_rssadapt_lower_rate.9 \ diff --git a/share/man/man9/roundup.9 b/share/man/man9/roundup.9 new file mode 100644 index 000000000000..0d3ca8c3c16f --- /dev/null +++ b/share/man/man9/roundup.9 @@ -0,0 +1,96 @@ +.\" $NetBSD: roundup.9,v 1.1 2010/03/04 08:09:52 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 March 4, 2010 +.Dt ROUNDUP 9 +.Os +.Sh NAME +.Nm roundup +.Nd macros for counting and rounding +.Sh SYNOPSIS +.In sys/param.h +.Ft size +.Fn howmany "x" "size" +.Ft size +.Fn roundup "x" "size" +.Ft size +.Fn rounddown "x" "size" +.Ft size +.Fn roundup2 "x" "size" +.Ft int +.Fn powerof2 "x" +.Sh DESCRIPTION +The +.Fn roundup +and +.Fn rounddown +macros return an integer from rounding +.Fa x +up and down, respectively, to the next +.Fa size . +The +.Fn howmany +macro in turn reveals how many times +.Fa size +fits into +.Fa x , +rounding the residual up. +.Pp +The +.Fn roundup2 +macro also rounds up, but with the assumption that +.Fa x +is a power of two. +If +.Fa x +is indeed a power of two, +.Fn powerof2 +return 1. +.Sh RETURN VALUES +The return value is an integer from the respective operation. +If +.Fa x +is 0, all macros except +.Fn powerof2 +return 0. +The behavior is undefined if +.Fa size +is 0. +.Sh EXAMPLES +.Bd -literal -offset indent +uint16_t rx; + +\&... + +/* Round up to 32-bit boundary. */ +rx = roundup2(rx, sizeof(uint32_t)); +.Ed +.Sh CAVEATS +All described macros make no assumptions about the type of the parameters. +These are implicitly assumed to be unsigned integers.