patch-2.4.7 linux/include/asm-mips64/bitops.h

• Lines: 319
• Date: Wed Jul 4 11:50:39 2001
• Orig file: v2.4.6/linux/include/asm-mips64/bitops.h
• Orig date: Tue Nov 28 21:42:04 2000

diff -u --recursive --new-file v2.4.6/linux/include/asm-mips64/bitops.h linux/include/asm-mips64/bitops.h
@@ -21,16 +21,15 @@
 #include <asm/mipsregs.h>
 
 /*
- * clear_bit() doesn't provide any barrier for the compiler.
+ * set_bit - Atomically set a bit in memory
+ * @nr: the bit to set
+ * @addr: the address to start counting from
+ *
+ * This function is atomic and may not be reordered.  See __set_bit()
+ * if you do not require the atomic guarantees.
+ * Note that @nr may be almost arbitrarily large; this function is not
+ * restricted to acting on a single-word quantity.
  */
-#define smp_mb__before_clear_bit()	barrier()
-#define smp_mb__after_clear_bit()	barrier()
-
-/*
- * These functions for MIPS ISA > 1 are interrupt and SMP proof and
- * interrupt friendly
- */
-
 extern __inline__ void
 set_bit(unsigned long nr, volatile void *addr)
 {
@@ -47,7 +46,15 @@
 		: "memory");
 }
 
-/* WARNING: non atomic and it can be reordered! */
+/*
+ * __set_bit - Set a bit in memory
+ * @nr: the bit to set
+ * @addr: the address to start counting from
+ *
+ * Unlike set_bit(), this function is non-atomic and may be reordered.
+ * If it's called on the same region of memory simultaneously, the effect
+ * may be that only one operation succeeds.
+ */
 extern __inline__ void __set_bit(int nr, volatile void * addr)
 {
 	unsigned long * m = ((unsigned long *) addr) + (nr >> 6);
@@ -55,6 +62,16 @@
 	*m |= 1UL << (nr & 0x3f);
 }
 
+/*
+ * clear_bit - Clears a bit in memory
+ * @nr: Bit to clear
+ * @addr: Address to start counting from
+ *
+ * clear_bit() is atomic and may not be reordered.  However, it does
+ * not contain a memory barrier, so if it is used for locking purposes,
+ * you should call smp_mb__before_clear_bit() and/or smp_mb__after_clear_bit()
+ * in order to ensure changes are visible on other processors.
+ */
 extern __inline__ void
 clear_bit(unsigned long nr, volatile void *addr)
 {
@@ -70,7 +87,18 @@
 		: "ir" (~(1UL << (nr & 0x3f))), "m" (*m));
 }
 
+#define smp_mb__before_clear_bit()	barrier()
+#define smp_mb__after_clear_bit()	barrier()
 
+/*
+ * change_bit - Toggle a bit in memory
+ * @nr: Bit to clear
+ * @addr: Address to start counting from
+ *
+ * change_bit() is atomic and may not be reordered.
+ * Note that @nr may be almost arbitrarily large; this function is not
+ * restricted to acting on a single-word quantity.
+ */
 extern __inline__ void
 change_bit(unsigned long nr, volatile void *addr)
 {
@@ -86,6 +114,30 @@
 		:"ir" (1UL << (nr & 0x3f)), "m" (*m));
 }
 
+/*
+ * __change_bit - Toggle a bit in memory
+ * @nr: the bit to set
+ * @addr: the address to start counting from
+ *
+ * Unlike change_bit(), this function is non-atomic and may be reordered.
+ * If it's called on the same region of memory simultaneously, the effect
+ * may be that only one operation succeeds.
+ */
+extern __inline__ void __change_bit(int nr, volatile void * addr)
+{
+	unsigned long * m = ((unsigned long *) addr) + (nr >> 6);
+
+	*m ^= 1UL << (nr & 0x3f);
+}
+
+/*
+ * test_and_set_bit - Set a bit and return its old value
+ * @nr: Bit to set
+ * @addr: Address to count from
+ *
+ * This operation is atomic and cannot be reordered.  
+ * It also implies a memory barrier.
+ */
 extern __inline__ unsigned long
 test_and_set_bit(unsigned long nr, volatile void *addr)
 {
@@ -107,19 +159,37 @@
 	return res != 0;
 }
 
-extern __inline__ int __test_and_set_bit(int nr, volatile void * addr)
+/*
+ * __test_and_set_bit - Set a bit and return its old value
+ * @nr: Bit to set
+ * @addr: Address to count from
+ *
+ * This operation is non-atomic and can be reordered.  
+ * If two examples of this operation race, one can appear to succeed
+ * but actually fail.  You must protect multiple accesses with a lock.
+ */
+extern __inline__ int
+__test_and_set_bit(int nr, volatile void * addr)
 {
-	int mask, retval;
-	volatile long *a = addr;
+	unsigned long mask, retval;
+	long *a = (unsigned long *) addr;
 
-	a += nr >> 6;
-	mask = 1 << (nr & 0x3f);
-	retval = (mask & *a) != 0;
+	a += (nr >> 6);
+	mask = 1UL << (nr & 0x3f);
+	retval = ((mask & *a) != 0);
 	*a |= mask;
 
 	return retval;
 }
 
+/*
+ * test_and_clear_bit - Clear a bit and return its old value
+ * @nr: Bit to set
+ * @addr: Address to count from
+ *
+ * This operation is atomic and cannot be reordered.  
+ * It also implies a memory barrier.
+ */
 extern __inline__ unsigned long
 test_and_clear_bit(unsigned long nr, volatile void *addr)
 {
@@ -142,19 +212,37 @@
 	return res != 0;
 }
 
-extern __inline__ int __test_and_clear_bit(int nr, volatile void * addr)
+/*
+ * __test_and_clear_bit - Clear a bit and return its old value
+ * @nr: Bit to set
+ * @addr: Address to count from
+ *
+ * This operation is non-atomic and can be reordered.  
+ * If two examples of this operation race, one can appear to succeed
+ * but actually fail.  You must protect multiple accesses with a lock.
+ */
+extern __inline__ int
+__test_and_clear_bit(int nr, volatile void * addr)
 {
-	int     mask, retval;
-	volatile long    *a = addr;
+	unsigned long mask, retval;
+	unsigned long *a = (unsigned long *) addr;
 
-	a += nr >> 6;
-	mask = 1 << (nr & 0x3f);
-	retval = (mask & *a) != 0;
+	a += (nr >> 6);
+	mask = 1UL << (nr & 0x3f);
+	retval = ((mask & *a) != 0);
 	*a &= ~mask;
 
 	return retval;
 }
 
+/*
+ * test_and_change_bit - Change a bit and return its new value
+ * @nr: Bit to set
+ * @addr: Address to count from
+ *
+ * This operation is atomic and cannot be reordered.  
+ * It also implies a memory barrier.
+ */
 extern __inline__ unsigned long
 test_and_change_bit(unsigned long nr, volatile void *addr)
 {
@@ -176,16 +264,51 @@
 	return res != 0;
 }
 
+/*
+ * __test_and_change_bit - Change a bit and return its old value
+ * @nr: Bit to set
+ * @addr: Address to count from
+ *
+ * This operation is non-atomic and can be reordered.  
+ * If two examples of this operation race, one can appear to succeed
+ * but actually fail.  You must protect multiple accesses with a lock.
+ */
+extern __inline__ int
+__test_and_change_bit(int nr, volatile void * addr)
+{
+	unsigned long mask, retval;
+	unsigned long *a = (unsigned long *) addr;
+
+	a += (nr >> 6);
+	mask = 1UL << (nr & 0x3f);
+	retval = ((mask & *a) != 0);
+	*a ^= mask;
+
+	return retval;
+}
+/*
+ * test_bit - Determine whether a bit is set
+ * @nr: bit number to test
+ * @addr: Address to start counting from
+ */
 extern __inline__ unsigned long
 test_bit(int nr, volatile void * addr)
 {
-	return 1UL & (((const long *) addr)[nr >> 6] >> (nr & 0x3f));
+	return 1UL & (((volatile unsigned long *) addr)[nr >> 6] >> (nr & 0x3f));
 }
 
 #ifndef __MIPSEB__
 
 /* Little endian versions. */
 
+/*
+ * find_first_zero_bit - find the first zero bit in a memory region
+ * @addr: The address to start the search at
+ * @size: The maximum size to search
+ *
+ * Returns the bit-number of the first zero bit, not the number of the byte
+ * containing a bit.
+ */
 extern __inline__ int
 find_first_zero_bit (void *addr, unsigned size)
 {
@@ -228,6 +351,12 @@
 	return res;
 }
 
+/*
+ * find_next_zero_bit - find the first zero bit in a memory region
+ * @addr: The address to base the search on
+ * @offset: The bitnumber to start searching at
+ * @size: The maximum size to search
+ */
 extern __inline__ int
 find_next_zero_bit (void * addr, int size, int offset)
 {
@@ -267,8 +396,10 @@
 #endif /* !(__MIPSEB__) */
 
 /*
- * ffz = Find First Zero in word. Undefined if no zero exists,
- * so code should check against ~0UL first..
+ * ffz - find first zero in word.
+ * @word: The word to search
+ *
+ * Undefined if no zero exists, so code should check against ~0UL first.
  */
 extern __inline__ unsigned long ffz(unsigned long word)
 {
@@ -288,8 +419,12 @@
 
 #ifdef __KERNEL__
 
+
 /*
- * ffs: find first bit set. This is defined the same way as
+ * ffs - find first bit set
+ * @x: the word to search
+ *
+ * This is defined the same way as
  * the libc and compiler builtin ffs routines, therefore
  * differs in spirit from the above ffz (man ffs).
  */
@@ -297,8 +432,10 @@
 #define ffs(x) generic_ffs(x)
 
 /*
- * hweightN: returns the hamming weight (i.e. the number
- * of bits set) of a N-bit word
+ * hweightN - returns the hamming weight of a N-bit word
+ * @x: the word to weigh
+ *
+ * The Hamming Weight of a number is the total number of bits set in it.
  */
 
 #define hweight32(x) generic_hweight32(x)
@@ -310,11 +447,11 @@
 #ifdef __MIPSEB__
 
 /*
- * find_next_zero_bit() finds the first zero bit in a bit string of length
- * 'size' bits, starting the search at bit 'offset'. This is largely based
- * on Linus's ALPHA routines, which are pretty portable BTW.
+ * find_next_zero_bit - find the first zero bit in a memory region
+ * @addr: The address to base the search on
+ * @offset: The bitnumber to start searching at
+ * @size: The maximum size to search
  */
-
 extern __inline__ unsigned long
 find_next_zero_bit(void *addr, unsigned long size, unsigned long offset)
 {