From owner-svn-src-head@freebsd.org Tue Jan 3 20:59:52 2017 Return-Path: Delivered-To: svn-src-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 4B441C9E0B0; Tue, 3 Jan 2017 20:59:52 +0000 (UTC) (envelope-from mjg@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id EE33412C3; Tue, 3 Jan 2017 20:59:51 +0000 (UTC) (envelope-from mjg@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id v03KxpFV093284; Tue, 3 Jan 2017 20:59:51 GMT (envelope-from mjg@FreeBSD.org) Received: (from mjg@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id v03Kxpgs093283; Tue, 3 Jan 2017 20:59:51 GMT (envelope-from mjg@FreeBSD.org) Message-Id: <201701032059.v03Kxpgs093283@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: mjg set sender to mjg@FreeBSD.org using -f From: Mateusz Guzik Date: Tue, 3 Jan 2017 20:59:51 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r311168 - head/share/man/man9 X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 03 Jan 2017 20:59:52 -0000 Author: mjg Date: Tue Jan 3 20:59:50 2017 New Revision: 311168 URL: https://svnweb.freebsd.org/changeset/base/311168 Log: Add the upcoming atomic_fcmpset family to the atomic(9) man page. These primitives give the caller the read value if the exchange attempt failed which saves an explicit reload for cmpset loops. The man page was partially submitted by kib. Reviewed by: kib (previous version), jhb (previous version) Modified: head/share/man/man9/atomic.9 Modified: head/share/man/man9/atomic.9 ============================================================================== --- head/share/man/man9/atomic.9 Tue Jan 3 20:28:48 2017 (r311167) +++ head/share/man/man9/atomic.9 Tue Jan 3 20:59:50 2017 (r311168) @@ -23,13 +23,14 @@ .\" .\" $FreeBSD$ .\" -.Dd May 12, 2016 +.Dd Jan 3, 2017 .Dt ATOMIC 9 .Os .Sh NAME .Nm atomic_add , .Nm atomic_clear , .Nm atomic_cmpset , +.Nm atomic_fcmpset , .Nm atomic_fetchadd , .Nm atomic_load , .Nm atomic_readandclear , @@ -50,6 +51,12 @@ .Fa " old" .Fa " new" .Fc +.Ft int +.Fo atomic_fcmpset_[acq_|rel_] +.Fa "volatile *dst" +.Fa " *old" +.Fa " new" +.Fc .Ft .Fn atomic_fetchadd_ "volatile *p" " v" .Ft @@ -228,6 +235,45 @@ functions are not implemented for the ty and .Dq Li 16 . .Bl -hang +.It Fn atomic_fcmpset dst *old new +.El +.Pp +On architectures implementing +.Em Compare And Swap +operation in hardware, the functionality can be described as +.Bd -literal -offset indent -compact +if (*dst == *old) { + *dst = new; + return (1); +} else { + *old = *dst; + return (0); +} +.Ed +On architectures which provide +.Em Load Linked/Store Conditional +primitive, the write to +.Dv *dst +might also fail for several reasons, most important of which +is a parallel write to +.Dv *dst +cache line by other CPU. +In this case +.Fn atomic_fcmpset +function also returns +.Dv false , +despite +.Dl *old == *dst . +.Pp +The +.Fn atomic_fcmpset +functions are not implemented for the types +.Dq Li char , +.Dq Li short , +.Dq Li 8 , +and +.Dq Li 16 . +.Bl -hang .It Fn atomic_fetchadd p v .Bd -literal -compact tmp = *p; @@ -353,6 +399,16 @@ The .Fn atomic_cmpset function returns the result of the compare operation. The +.Fn atomic_fcmpset +function returns +.Dv true +if the operationg succeeded. +Otherwise it returns +.Dv false +and sets +.Va *old +to the found value. +The .Fn atomic_fetchadd , .Fn atomic_load , .Fn atomic_readandclear ,