Update locks docs

app_locks_example/src/main.xc

@@ -19,4 +19,5 @@ int main()
     use_swlock(6);
   }
   free_locks();
+  return 0;
 }

module_locks/doc/Makefile

@@ -0,0 +1 @@
+DOXYGEN_DIRS=..

module_locks/doc/locks.rst

@@ -0,0 +1,33 @@
+Lock handling library
+=====================
+
+This module provides access to hardware and software locks for use in
+concurrent C programs. In general it is not safe to use these to
+marshall within XC due to the assumptions XC
+makes about safe concurrent data access.
+
+Two types of locks are provided. Hardware locks are fast and power
+efficient but there are a limited number per tile. Software locks are
+slower but you can use an unlimited number of them.
+
+Hardware lock API
+-----------------
+
+.. doxygentypedef:: hwlock_t
+
+.. doxygenfunction:: hwlock_alloc
+.. doxygenfunction:: hwlock_free
+.. doxygenfunction:: hwlock_acquire
+.. doxygenfunction:: hwlock_release
+
+Software lock API
+-----------------
+
+.. doxygentypedef:: swlock_t
+
+.. doxygendefine:: SWLOCK_INITIAL_VALUE
+
+.. doxygenfunction:: swlock_init
+.. doxygenfunction:: swlock_try_acquire
+.. doxygenfunction:: swlock_acquire
+.. doxygenfunction:: swlock_release

module_locks/src/swlock.c

@@ -6,14 +6,15 @@
 #include "swlock.h"
 /* Locks */
 
-void swlock_init(volatile swlock_t *lock)
+void swlock_init(swlock_t *_lock)
 {
+  volatile swlock_t *lock = _lock;
   *lock = 0;
 }
 
-extern int swlock_try_acquire(volatile swlock_t *lock);
+extern int swlock_try_acquire(swlock_t *lock);
 
-void swlock_acquire(volatile swlock_t *lock)
+void swlock_acquire(swlock_t *lock)
 {  
   int value;
   do {
@@ -22,14 +23,9 @@ void swlock_acquire(volatile swlock_t *lock)
   while (value == SWLOCK_NOT_ACQUIRED);
 }
 
-void swlock_release(volatile swlock_t *lock)
+void swlock_release(swlock_t *lock)
 {
   *lock = 0;
 }
 
-void swlock_init_xc(swlock_t *lock) { swlock_init(lock); }
-
-int swlock_try_acquire_xc(swlock_t *lock) {return swlock_try_acquire(lock); }
-
-void swlock_acquire_xc(swlock_t *lock) {swlock_acquire(lock);}
 

module_locks/src/swlock.h

@@ -10,19 +10,15 @@
 /** Type that represents a software lock */
 typedef unsigned swlock_t;
 
-/** This define should be used to initialize a software lock e.g.::
- *
- *  swlock_t my_lock = SWLOCK_INITIAL_VALUE;
- *
- *  If you intialize this way there is no need to call swlock_init().
- */
-#define SWLOCK_INITIAL_VALUE 0
+/** This define should be used to initialize a software lock e.g.
 
-#ifdef __XC__
-#define VOLATILE_SWLOCK swlock_t
-#else
-#define VOLATILE_SWLOCK volatile swlock_t
-#endif
+    \code
+       swlock_t my_lock = SWLOCK_INITIAL_VALUE;
+    \endcode
+
+    If you intialize this way there is no need to call swlock_init().
+*/
+#define SWLOCK_INITIAL_VALUE 0
 
 enum {
   SWLOCK_NOT_ACQUIRED = 0
@@ -34,7 +30,7 @@ enum {
  *  hardware locks, there is no need to allocate or free a software lock from a
  *  limited pool.
  */
-void swlock_init(REFERENCE_PARAM(VOLATILE_SWLOCK, lock));
+void swlock_init(REFERENCE_PARAM(swlock_t, lock));
 
 /** Try and acquire a software lock.
  *
@@ -47,7 +43,7 @@ void swlock_init(REFERENCE_PARAM(VOLATILE_SWLOCK, lock));
  *           the attempt fails. Any other value indicates that the
  *           acquisition has succeeded.
  */
-int  swlock_try_acquire(REFERENCE_PARAM(VOLATILE_SWLOCK, lock));
+int  swlock_try_acquire(REFERENCE_PARAM(swlock_t, lock));
 
 /** Acquire a software lock.
  *
@@ -58,7 +54,7 @@ int  swlock_try_acquire(REFERENCE_PARAM(VOLATILE_SWLOCK, lock));
  *  \param   lock  the software lock to acquire.
  *
  */
-void swlock_acquire(REFERENCE_PARAM(VOLATILE_SWLOCK, lock));
+void swlock_acquire(REFERENCE_PARAM(swlock_t, lock));
 
 /** Release a software lock.
  *
@@ -68,6 +64,6 @@ void swlock_acquire(REFERENCE_PARAM(VOLATILE_SWLOCK, lock));
  *  \param lock   the software lock to release.
  *
  */
-void swlock_release(REFERENCE_PARAM(VOLATILE_SWLOCK, lock));
+void swlock_release(REFERENCE_PARAM(swlock_t, lock));
 
 #endif

xpd.xml

@@ -33,6 +33,7 @@
     <docdir>module_random/doc</docdir>
     <docdir>module_xassert/doc</docdir>
     <docdir>module_logging/doc</docdir>
+    <docdir>module_locks/doc</docdir>
     <exclude_dir>tests</exclude_dir>
     <location>[email protected]:xcore/sc_util</location>
     <name>sc_util</name>