# HG changeset patch
# User Francisco J Ballesteros <nemo.mbox@gmail.com>
# Date 1316368076 -7200
# Node ID 92a3bab230c599573832ea2ff01819f29c3e1425
# Parent  87a53ed24152dc561b2755f3b7071b867a1dedfb
atomics: fix interface and man page
Change casl to be casul and provide
interfaces for missing atomics in libc.
new man page.

R=nix-dev, rminnich
CC=nix-dev
http://codereview.appspot.com/5036049

diff -r 87a53ed24152 -r 92a3bab230c5 sys/include/libc.h
--- a/sys/include/libc.h	Sun Sep 18 19:44:57 2011 +0200
+++ b/sys/include/libc.h	Sun Sep 18 19:47:56 2011 +0200
@@ -707,10 +707,17 @@
 
 /*
  * Atomics
+ * (casul was known before as casl; we don't suppy a prototype
+ * so we could see the warnings and update the source; the function
+ * is still in libc).
  */
-extern int	casl(ulong *p, ulong ov, ulong nv);
 extern int	ainc(int *); 
 extern int	adec(int *); 
+extern int	cas(uint *p, int ov, int nv);
+extern int	casul(ulong *p, ulong ov, ulong nv);
+extern int	casp(void **p, void *ov, void *nv);
+extern int	cas32(u32int *p, u32int ov, u32int nv);
+extern int	cas64(u64int *p, u64int ov, u64int nv);
 extern void	mfence(void);
 
 /*
diff -r 87a53ed24152 -r 92a3bab230c5 sys/man/2/ainc
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/sys/man/2/ainc	Sun Sep 18 19:47:56 2011 +0200
@@ -0,0 +1,71 @@
+.TH AINC 2
+.SH NAME
+ainc, adec, cas32, cas, casp, casl, cas64, mfence \- atomic operations
+.SH SYNOPSIS
+.B #include <u.h>
+.br
+.B #include <libc.h>
+.PP
+.nf
+.B
+int ainc(int *p)
+.PP
+.B
+int adec(int *p)
+.PP
+.B
+int cas(uint *p, int ov, int nv)
+.PP
+.B
+int casp(void **p, void *ov, void *nv)
+.PP
+.B
+int casul(ulong *p, ulong ov, ulong nv)
+.PP
+.B
+int cas32(u32int *p, u32int ov, u32int nv)
+.PP
+.B
+int cas64(u64int *p, u64int ov, u64int nv)
+.PP
+.B
+void mfence(void)
+.SH DESCRIPTION
+These functions provide access to atomic operations, useful for
+synchronization.
+.PP
+.I Ainc
+and
+.I adec
+atomically
+increment and decrement (respectively) the integer pointed to by
+.IR p ,
+and return the resulting value after the operation.
+.PP
+.I Cas
+performs a compare and swap on the word pointed to by
+.IR p ,
+provided that the value is still
+.I ov
+(the old value), so that the new value is
+.IR nv .
+Functions
+.IR cas32 ,
+.IR cas64 ,
+.IR casp ,
+and
+.I casul
+do the same for 32-bit values, 64-bit values, pointers, and unsigned long
+integers.
+.PP
+.I Mfence
+sets a memory fence so that all outstanding memory operations are performed
+before returning from it.
+.SH SOURCE
+.B /sys/src/libc/386/atom.s
+.br
+.B /sys/src/libc/amd64/atom.s
+.SH SEE ALSO
+.IR incref (2).
+.SH BUGS
+Some of them may not be implemented for some architectures.
diff -r 87a53ed24152 -r 92a3bab230c5 sys/src/libc/386/atom.s
--- a/sys/src/libc/386/atom.s	Sun Sep 18 19:44:57 2011 +0200
+++ b/sys/src/libc/386/atom.s	Sun Sep 18 19:47:56 2011 +0200
@@ -1,4 +1,4 @@
-TEXT ainc(SB), $0	/* long ainc(long *); */
+TEXT ainc(SB), $0	/* int ainc(int *); */
 	MOVL	addr+0(FP), BX
 ainclp:
 	MOVL	(BX), AX
@@ -10,7 +10,7 @@
 	MOVL	CX, AX
 	RET
 
-TEXT adec(SB), $0	/* long adec(long*); */
+TEXT adec(SB), $0	/* int adec(int*); */
 	MOVL	addr+0(FP), BX
 adeclp:
 	MOVL	(BX), AX
@@ -26,7 +26,7 @@
  * int cas32(u32int *p, u32int ov, u32int nv);
  * int cas(uint *p, int ov, int nv);
  * int casp(void **p, void *ov, void *nv);
- * int casl(ulong *p, ulong ov, ulong nv);
+ * int casul(ulong *p, ulong ov, ulong nv);
  */
 
 /*
@@ -39,7 +39,8 @@
 TEXT	cas32+0(SB),0,$0
 TEXT	cas+0(SB),0,$0
 TEXT	casp+0(SB),0,$0
-TEXT	casl+0(SB),0,$0
+TEXT	casul+0(SB),0,$0
+TEXT	casl+0(SB),0,$0		/* compatibility with old name */
 	MOVL	p+0(FP), CX
 	MOVL	ov+4(FP), AX
 	MOVL	nv+8(FP), DX
diff -r 87a53ed24152 -r 92a3bab230c5 sys/src/libc/amd64/atom.s
--- a/sys/src/libc/amd64/atom.s	Sun Sep 18 19:44:57 2011 +0200
+++ b/sys/src/libc/amd64/atom.s	Sun Sep 18 19:47:56 2011 +0200
@@ -21,12 +21,13 @@
 /*
  * int cas32(u32int *p, u32int ov, u32int nv);
  * int cas(uint *p, int ov, int nv);
- * int casl(ulong *p, ulong ov, ulong nv);
+ * int casul(ulong *p, ulong ov, ulong nv);
  */
 
 TEXT cas32(SB), 1, $0
 TEXT cas(SB), 1, $0
-TEXT casl(SB), 1, $0
+TEXT casul(SB), 1, $0
+TEXT casl(SB), 1, $0			/* back compat */
 	MOVL	exp+8(FP), AX
 	MOVL	new+16(FP), BX
 	LOCK; CMPXCHGL BX, (RARG)