orb: add some comments about locking

src/drivers/device/vdev.h

@@ -178,6 +178,8 @@ protected:
 	 * Each driver instance has its own lock/semaphore.
 	 *
 	 * Note that we must loop as the wait may be interrupted by a signal.
+	 *
+	 * Careful: lock() calls cannot be nested!
 	 */
 	void		lock()
 	{
@@ -195,7 +197,7 @@ protected:
 	}
 
 private:
-	px4_sem_t		_lock;
+	px4_sem_t		_lock; /**< lock to protect access to all class members (also for derived classes) */
 
 	/** disable copy construction for this and all subclasses */
 	Device(const Device &);
@@ -348,6 +350,8 @@ protected:
 	 *
 	 * The default implementation returns no events.
 	 *
+	 * Lock must already be held when calling this.
+	 *
 	 * @param filep		The file that's interested.
 	 * @return		The current set of poll events.
 	 */
@@ -366,6 +370,8 @@ protected:
 	/**
 	 * Internal implementation of poll_notify.
 	 *
+	 * Lock must already be held when calling this.
+	 *
 	 * @param fds		A poll waiter to notify.
 	 * @param events	The event(s) to send to the waiter.
 	 */

src/modules/uORB/uORBDevices_posix.hpp

@@ -148,6 +148,8 @@ private:
 	/**
 	 * Check whether a topic appears updated to a subscriber.
 	 *
+	 * Lock must already be held when calling this.
+	 *
 	 * @param sd    The subscriber for whom to check.
 	 * @return    True if the topic should appear updated to the subscriber
 	 */