From owner-freebsd-smp Sat Mar 15 4:58:33 2003 Delivered-To: freebsd-smp@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id B33AE37B401; Sat, 15 Mar 2003 04:58:29 -0800 (PST) Received: from mailman.zeta.org.au (mailman.zeta.org.au [203.26.10.16]) by mx1.FreeBSD.org (Postfix) with ESMTP id D36FC43FAF; Sat, 15 Mar 2003 04:58:27 -0800 (PST) (envelope-from bde@zeta.org.au) Received: from katana.zip.com.au (katana.zip.com.au [61.8.7.246]) by mailman.zeta.org.au (8.9.3/8.8.7) with ESMTP id XAA16296; Sat, 15 Mar 2003 23:58:19 +1100 Date: Sat, 15 Mar 2003 23:58:18 +1100 (EST) From: Bruce Evans X-X-Sender: bde@gamplex.bde.org To: Harti Brandt Cc: smp@FreeBSD.ORG, "" Subject: Re: malloc.9 locking section In-Reply-To: <20030315123530.X45650@beagle.fokus.fraunhofer.de> Message-ID: <20030315230514.A9013@gamplex.bde.org> References: <20030315123530.X45650@beagle.fokus.fraunhofer.de> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-freebsd-smp@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org On Sat, 15 Mar 2003, Harti Brandt wrote: > attached is a diff to malloc.9 that adds a section 'locking > considerations' to the man page. I would like to receive comments about > > - whether this is altogether useful information to have in the man page > - about the section name (Solaris calls this section 'CONTEXT') > - about the section contents itself. I'm quite sure, that I got this > partly wrong. > - about the formatting (not beeing a mandoc expert) > Index: malloc.9 > =================================================================== > RCS file: /home/ncvs/src/share/man/man9/malloc.9,v > retrieving revision 1.29 > diff -u -r1.29 malloc.9 > --- malloc.9 5 Feb 2003 14:00:46 -0000 1.29 > +++ malloc.9 15 Mar 2003 11:34:03 -0000 > @@ -230,6 +230,35 @@ > be used with > .Xr mbuf 9 > routines as it will cause undesired results. > +.Sh LOCKING CONSIDERATIONS > +.Fn malloc , > +.Fn realloc > +and > +.Fn reallocf > +may be called from threaded and fast interrupts handlers. > +When called from fast interrupts > +.Ar flag > +must contain > +.Dv M_NOWAIT . These functions (like most (should be all) functions that aren't in or ) may NOT be called from fast interrupt handlers. You may be confused by the bogus and broken check of td_intr_nesting_level in malloc(). This is supposed to check that normal interrupt handlers don't call malloc() with M_WAITOK, but has rotted to only checking that fast interrupt handlers don't do this. But fast interrupt handlers shouldn't even think of calling malloc(). > +When called from threaded interrupts > +.Ar flag > +should contain s/should/must/ > +.Dv M_NOWAIT . and not M_WAITOK (*). > +.Pp > +.Fn malloc , > +.Fn realloc > +and > +.Fn reallocf > +must not be called with > +.Dv M_WAIT > +while a mutex other than Giant is held. I think you mean M_WAITOK (M_WAIT is only for mbufs). It's confusing to say "flag must contain M_NOWAIT" for ithreads and "must not be called with M_WAITOK" while a mutex other than Giant is held. The requirements are the same, and the conditions are almost the same too -- ithreads might even be implemented using a mutex other than Giant to prevent them being reentred, though in practice they use a different type of locking. > +Giant may or may not be held when > +.Fn malloc , > +.Fn realloc , > +.Fn reallocf > +or > +.Fn free > +are called. This is redundant. (*) The man page doesn't seem to say that exactly one of {M_NOWAIT, M_WAITOK}, must be set, perhaps because it has rotted and still essentially says that M_WAITOK is 0. Changes like the above should be merged into the rotted bits to fix them and avoid redundancy. Here are some of the rotted bits: % Note that % .Dv M_NOWAIT % is defined to be 0, meaning that blocking operation is the default. Nope. Clearly no one reads man section 9 manpages. % Also note that % .Dv M_NOWAIT % is required when running in an interrupt context. Still correct. % .Pp % Programmers should be careful not to confuse % .Dv M_NOWAIT , % the % .Fn malloc % flag, with % .Dv M_DONTWAIT , % an % .Xr mbuf 9 % allocation flag, which is not a valid argument to % .Fn malloc . % .It Dv M_WAITOK % Indicates that it is Ok to wait for resources. It is unconveniently % defined as 0 so care should be taken never to compare against this value % directly or try to AND it as a flag. The default operation is to block % until the memory allocation succeeds. Mostly rotted. Bruce To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-smp" in the body of the message