better documentation and implementation for lock/unlock

1 files changed, 12 insertions, 0 deletions

diff --git a/include/hardware/gralloc.h b/include/hardware/gralloc.h
index 6bde8f7..dba6fda 100644
--- a/include/hardware/gralloc.h
+++ b/include/hardware/gralloc.h
@@ -131,6 +131,18 @@ struct gralloc_module_t {
      * If usage specifies GRALLOC_USAGE_SW_*, vaddr is filled with the address
      * of the buffer in virtual memory.
      *
+     * THREADING CONSIDERATIONS:
+     *
+     * It is legal for several different threads to lock a buffer from 
+     * read access, none of the threads are blocked.
+     * 
+     * However, locking a buffer simultaneously for write or read/write is
+     * undefined, but:
+     * - shall not result in termination of the process
+     * - shall not block the caller
+     * It is acceptable to return an error or to leave the buffer's content
+     * into an indeterminate state.
+     *
      * If the buffer was created with a usage mask incompatible with the
      * requested usage flags here, -EINVAL is returned. 
      *