gui: Update header docs for IGraphicBufferConsumer/Producer/BufferQueue

Also fix compiler warnings for libgui

Change-Id: I0ee38d9ad5eaa82d55bf812d291da8c433581cef

include/gui/BufferQueue.h

@@ -42,10 +42,16 @@ class BufferQueue : public BnGraphicBufferProducer,
                     private IBinder::DeathRecipient {
 public:
     enum { MIN_UNDEQUEUED_BUFFERS = 2 };
+    // BufferQueue will keep track of at most this value of buffers.
+    // Attempts at runtime to increase the number of buffers past this will fail.
     enum { NUM_BUFFER_SLOTS = 32 };
-    enum { NO_CONNECTED_API = 0 };
+    // Used as a placeholder slot# when the value isn't pointing to an existing buffer.
-    enum { INVALID_BUFFER_SLOT = -1 };
+    enum { INVALID_BUFFER_SLOT = IGraphicBufferConsumer::BufferItem::INVALID_BUFFER_SLOT };
-    enum { STALE_BUFFER_SLOT = 1, NO_BUFFER_AVAILABLE, PRESENT_LATER };
+    // Alias to <IGraphicBufferConsumer.h> -- please scope from there in future code!
+    enum {
+        NO_BUFFER_AVAILABLE = IGraphicBufferConsumer::NO_BUFFER_AVAILABLE,
+        PRESENT_LATER = IGraphicBufferConsumer::PRESENT_LATER,
+    };
 
     // When in async mode we reserve two slots in order to guarantee that the
     // producer and consumer can run asynchronously.
@@ -75,7 +81,6 @@ public:
         wp<ConsumerListener> mConsumerListener;
     };
 
-
     // BufferQueue manages a pool of gralloc memory slots to be used by
     // producers and consumers. allocator is used to allocate all the
     // needed gralloc buffers.
@@ -212,7 +217,7 @@ public:
      */
 
     // acquireBuffer attempts to acquire ownership of the next pending buffer in
-    // the BufferQueue.  If no buffer is pending then it returns -EINVAL.  If a
+    // the BufferQueue.  If no buffer is pending then it returns NO_BUFFER_AVAILABLE. If a
     // buffer is successfully acquired, the information about the buffer is
     // returned in BufferItem.  If the buffer returned had previously been
     // acquired then the BufferItem::mGraphicBuffer field of buffer is set to
@@ -224,7 +229,7 @@ public:
     // future, the buffer won't be acquired, and PRESENT_LATER will be
     // returned.  The presentation time is in nanoseconds, and the time base
     // is CLOCK_MONOTONIC.
-    virtual status_t acquireBuffer(BufferItem *buffer, nsecs_t presentWhen);
+    virtual status_t acquireBuffer(BufferItem* buffer, nsecs_t presentWhen);
 
     // releaseBuffer releases a buffer slot from the consumer back to the
     // BufferQueue.  This may be done while the buffer's contents are still
@@ -312,8 +317,13 @@ public:
     // dump our state in a String
     virtual void dump(String8& result, const char* prefix) const;
 
-
 private:
+    // The default API number used to indicate no producer client is connected.
+    enum { NO_CONNECTED_API = 0 };
+
+    // Aliases for using enums from <IGraphicBufferConsumer.h>
+    enum { STALE_BUFFER_SLOT = IGraphicBufferConsumer::STALE_BUFFER_SLOT };
+
     // freeBufferLocked frees the GraphicBuffer and sync resources for the
     // given slot.
     void freeBufferLocked(int index);

include/gui/IGraphicBufferConsumer.h

@@ -48,6 +48,7 @@ public:
         status_t unflatten(void const*& buffer, size_t& size, int const*& fds, size_t& count);
 
     public:
+        // The default value of mBuf, used to indicate this doesn't correspond to a slot.
         enum { INVALID_BUFFER_SLOT = -1 };
         BufferItem();
 
@@ -63,13 +64,17 @@ public:
         Rect mCrop;
 
         // mTransform is the current transform flags for this buffer slot.
+        // refer to NATIVE_WINDOW_TRANSFORM_* in <window.h>
         uint32_t mTransform;
 
         // mScalingMode is the current scaling mode for this buffer slot.
+        // refer to NATIVE_WINDOW_SCALING_* in <window.h>
         uint32_t mScalingMode;
 
         // mTimestamp is the current timestamp for this buffer slot. This gets
-        // to set by queueBuffer each time this slot is queued.
+        // to set by queueBuffer each time this slot is queued. This value
+        // is guaranteed to be monotonically increasing for each newly
+        // acquired buffer.
         int64_t mTimestamp;
 
         // mIsAutoTimestamp indicates whether mTimestamp was generated
@@ -79,7 +84,7 @@ public:
         // mFrameNumber is the number of the queued frame for this slot.
         uint64_t mFrameNumber;
 
-        // mBuf is the slot index of this buffer
+        // mBuf is the slot index of this buffer (default INVALID_BUFFER_SLOT).
         int mBuf;
 
         // mIsDroppable whether this buffer was queued with the
@@ -97,21 +102,42 @@ public:
         bool mTransformToDisplayInverse;
     };
 
+    enum {
+        // Returned by releaseBuffer, after which the consumer must
+        // free any references to the just-released buffer that it might have.
+        STALE_BUFFER_SLOT = 1,
+        // Returned by dequeueBuffer if there are no pending buffers available.
+        NO_BUFFER_AVAILABLE,
+        // Returned by dequeueBuffer if it's too early for the buffer to be acquired.
+        PRESENT_LATER,
+    };
 
     // acquireBuffer attempts to acquire ownership of the next pending buffer in
-    // the BufferQueue.  If no buffer is pending then it returns -EINVAL.  If a
+    // the BufferQueue.  If no buffer is pending then it returns
-    // buffer is successfully acquired, the information about the buffer is
+    // NO_BUFFER_AVAILABLE.  If a buffer is successfully acquired, the
-    // returned in BufferItem.  If the buffer returned had previously been
+    // information about the buffer is returned in BufferItem.
+    //
+    // If the buffer returned had previously been
     // acquired then the BufferItem::mGraphicBuffer field of buffer is set to
     // NULL and it is assumed that the consumer still holds a reference to the
     // buffer.
     //
-    // If presentWhen is nonzero, it indicates the time when the buffer will
+    // If presentWhen is non-zero, it indicates the time when the buffer will
     // be displayed on screen.  If the buffer's timestamp is farther in the
     // future, the buffer won't be acquired, and PRESENT_LATER will be
     // returned.  The presentation time is in nanoseconds, and the time base
     // is CLOCK_MONOTONIC.
-    virtual status_t acquireBuffer(BufferItem *buffer, nsecs_t presentWhen) = 0;
+    //
+    // Return of NO_ERROR means the operation completed as normal.
+    //
+    // Return of a positive value means the operation could not be completed
+    //    at this time, but the user should try again later:
+    // * NO_BUFFER_AVAILABLE - no buffer is pending (nothing queued by producer)
+    // * PRESENT_LATER - the buffer's timestamp is farther in the future
+    //
+    // Return of a negative value means an error has occurred:
+    // * INVALID_OPERATION - too many buffers have been acquired
+    virtual status_t acquireBuffer(BufferItem* buffer, nsecs_t presentWhen) = 0;
 
     // releaseBuffer releases a buffer slot from the consumer back to the
     // BufferQueue.  This may be done while the buffer's contents are still
@@ -125,6 +151,18 @@ public:
     //
     // Note that the dependencies on EGL will be removed once we switch to using
     // the Android HW Sync HAL.
+    //
+    // Return of NO_ERROR means the operation completed as normal.
+    //
+    // Return of a positive value means the operation could not be completed
+    //    at this time, but the user should try again later:
+    // * STALE_BUFFER_SLOT - see above (second paragraph)
+    //
+    // Return of a negative value means an error has occurred:
+    // * BAD_VALUE - one of the following could've happened:
+    //               * the buffer slot was invalid
+    //               * the fence was NULL
+    //               * the buffer slot specified is not in the acquired state
     virtual status_t releaseBuffer(int buf, uint64_t frameNumber,
             EGLDisplay display, EGLSyncKHR fence,
             const sp<Fence>& releaseFence) = 0;
@@ -137,24 +175,38 @@ public:
     // the application.
     //
     // consumer may not be NULL.
+    //
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * NO_INIT - the buffer queue has been abandoned
+    // * BAD_VALUE - a NULL consumer was provided
     virtual status_t consumerConnect(const sp<IConsumerListener>& consumer, bool controlledByApp) = 0;
 
     // consumerDisconnect disconnects a consumer from the BufferQueue. All
     // buffers will be freed and the BufferQueue is placed in the "abandoned"
     // state, causing most interactions with the BufferQueue by the producer to
     // fail.
+    //
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * BAD_VALUE - no consumer is currently connected
     virtual status_t consumerDisconnect() = 0;
 
-    // getReleasedBuffers sets the value pointed to by slotMask to a bit mask
+    // getReleasedBuffers sets the value pointed to by slotMask to a bit set.
-    // indicating which buffer slots have been released by the BufferQueue
+    // Each bit index with a 1 corresponds to a released buffer slot with that
-    // but have not yet been released by the consumer.
+    // index value.  In particular, a released buffer is one that has
+    // been released by the BufferQueue but have not yet been released by the consumer.
     //
     // This should be called from the onBuffersReleased() callback.
+    //
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * NO_INIT - the buffer queue has been abandoned.
     virtual status_t getReleasedBuffers(uint32_t* slotMask) = 0;
 
     // setDefaultBufferSize is used to set the size of buffers returned by
     // dequeueBuffer when a width and height of zero is requested.  Default
     // is 1x1.
+    //
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * BAD_VALUE - either w or h was zero
     virtual status_t setDefaultBufferSize(uint32_t w, uint32_t h) = 0;
 
     // setDefaultMaxBufferCount sets the default value for the maximum buffer
@@ -163,6 +215,9 @@ public:
     // take effect if the producer sets the count back to zero.
     //
     // The count must be between 2 and NUM_BUFFER_SLOTS, inclusive.
+    //
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * BAD_VALUE - bufferCount was out of range (see above).
     virtual status_t setDefaultMaxBufferCount(int bufferCount) = 0;
 
     // disableAsyncBuffer disables the extra buffer used in async mode
@@ -170,11 +225,20 @@ public:
     // flag) and has dequeueBuffer() return WOULD_BLOCK instead.
     //
     // This can only be called before consumerConnect().
+    //
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * INVALID_OPERATION - attempting to call this after consumerConnect.
     virtual status_t disableAsyncBuffer() = 0;
 
     // setMaxAcquiredBufferCount sets the maximum number of buffers that can
     // be acquired by the consumer at one time (default 1).  This call will
     // fail if a producer is connected to the BufferQueue.
+    //
+    // maxAcquiredBuffers must be (inclusive) between 1 and MAX_MAX_ACQUIRED_BUFFERS.
+    //
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * BAD_VALUE - maxAcquiredBuffers was out of range (see above).
+    // * INVALID_OPERATION - attempting to call this after a producer connected.
     virtual status_t setMaxAcquiredBufferCount(int maxAcquiredBuffers) = 0;
 
     // setConsumerName sets the name used in logging
@@ -184,16 +248,22 @@ public:
     // GraphicBuffers of a defaultFormat if no format is specified
     // in dequeueBuffer.  Formats are enumerated in graphics.h; the
     // initial default is HAL_PIXEL_FORMAT_RGBA_8888.
+    //
+    // Return of a value other than NO_ERROR means an unknown error has occurred.
     virtual status_t setDefaultBufferFormat(uint32_t defaultFormat) = 0;
 
     // setConsumerUsageBits will turn on additional usage bits for dequeueBuffer.
     // These are merged with the bits passed to dequeueBuffer.  The values are
     // enumerated in gralloc.h, e.g. GRALLOC_USAGE_HW_RENDER; the default is 0.
+    //
+    // Return of a value other than NO_ERROR means an unknown error has occurred.
     virtual status_t setConsumerUsageBits(uint32_t usage) = 0;
 
     // setTransformHint bakes in rotation to buffers so overlays can be used.
     // The values are enumerated in window.h, e.g.
     // NATIVE_WINDOW_TRANSFORM_ROT_90.  The default is 0 (no transform).
+    //
+    // Return of a value other than NO_ERROR means an unknown error has occurred.
     virtual status_t setTransformHint(uint32_t hint) = 0;
 
     // dump state into a string

include/gui/IGraphicBufferProducer.h

@@ -54,7 +54,11 @@ public:
     DECLARE_META_INTERFACE(GraphicBufferProducer);
 
     enum {
+        // A flag returned by dequeueBuffer when the client needs to call
+        // requestBuffer immediately thereafter.
         BUFFER_NEEDS_REALLOCATION = 0x1,
+        // A flag returned by dequeueBuffer when all mirrored slots should be
+        // released by the client. This flag should always be processed first.
         RELEASE_ALL_BUFFERS       = 0x2,
     };
 
@@ -63,51 +67,140 @@ public:
     // buffer to the given slot index, and the client is expected to mirror the
     // slot->buffer mapping so that it's not necessary to transfer a
     // GraphicBuffer for every dequeue operation.
+    //
+    // The slot must be in the range of [0, NUM_BUFFER_SLOTS).
+    //
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * NO_INIT - the buffer queue has been abandoned.
+    // * BAD_VALUE - one of the two conditions occurred:
+    //              * slot was out of range (see above)
+    //              * buffer specified by the slot is not dequeued
     virtual status_t requestBuffer(int slot, sp<GraphicBuffer>* buf) = 0;
 
     // setBufferCount sets the number of buffer slots available. Calling this
     // will also cause all buffer slots to be emptied. The caller should empty
     // its mirrored copy of the buffer slots when calling this method.
+    //
+    // This function should not be called when there are any dequeued buffer
+    // slots, doing so will result in a BAD_VALUE error returned.
+    //
+    // The buffer count should be at most NUM_BUFFER_SLOTS, but at least
+    // the minimum undequeued buffer count (inclusive). The minimum value
+    // can be obtained by calling query(NATIVE_WINDOW_MIN_UNDEQUEUED_BUFFERS);
+    //
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * NO_INIT - the buffer queue has been abandoned.
+    // * BAD_VALUE - one of the below conditions occurred:
+    //              * bufferCount was out of range (see above)
+    //              * client has one or more buffers dequeued
     virtual status_t setBufferCount(int bufferCount) = 0;
 
     // dequeueBuffer requests a new buffer slot for the client to use. Ownership
     // of the slot is transfered to the client, meaning that the server will not
-    // use the contents of the buffer associated with that slot. The slot index
+    // use the contents of the buffer associated with that slot.
-    // returned may or may not contain a buffer. If the slot is empty the client
+    //
-    // should call requestBuffer to assign a new buffer to that slot. The client
+    // The slot index returned may or may not contain a buffer (client-side).
-    // is expected to either call cancelBuffer on the dequeued slot or to fill
+    // If the slot is empty the client should call requestBuffer to assign a new
-    // in the contents of its associated buffer contents and call queueBuffer.
+    // buffer to that slot.
-    // If dequeueBuffer return BUFFER_NEEDS_REALLOCATION, the client is
+    //
+    // Once the client is done filling this buffer, it is expected to transfer
+    // buffer ownership back to the server with either cancelBuffer on
+    // the dequeued slot or to fill in the contents of its associated buffer
+    // contents and call queueBuffer.
+    //
+    // If dequeueBuffer returns the BUFFER_NEEDS_REALLOCATION flag, the client is
     // expected to call requestBuffer immediately.
     //
+    // If dequeueBuffer returns the RELEASE_ALL_BUFFERS flag, the client is
+    // expected to release all of the mirrored slot->buffer mappings.
+    //
     // The fence parameter will be updated to hold the fence associated with
     // the buffer. The contents of the buffer must not be overwritten until the
-    // fence signals. If the fence is NULL, the buffer may be written
+    // fence signals. If the fence is Fence::NO_FENCE, the buffer may be written
     // immediately.
     //
-    // The async parameter sets whether we're in asynchrnous mode for this
+    // The async parameter sets whether we're in asynchronous mode for this
-    // deququeBuffer() call.
+    // dequeueBuffer() call.
-    virtual status_t dequeueBuffer(int *slot, sp<Fence>* fence, bool async,
+    //
+    // The width and height parameters must be no greater than the minimum of
+    // GL_MAX_VIEWPORT_DIMS and GL_MAX_TEXTURE_SIZE (see: glGetIntegerv).
+    // An error due to invalid dimensions might not be reported until
+    // updateTexImage() is called.  If width and height are both zero, the
+    // default values specified by setDefaultBufferSize() are used instead.
+    //
+    // The pixel formats are enumerated in <graphics.h>, e.g.
+    // HAL_PIXEL_FORMAT_RGBA_8888.  If the format is 0, the default format
+    // will be used.
+    //
+    // The usage argument specifies gralloc buffer usage flags.  The values
+    // are enumerated in <gralloc.h>, e.g. GRALLOC_USAGE_HW_RENDER.  These
+    // will be merged with the usage flags specified by
+    // IGraphicBufferConsumer::setConsumerUsageBits.
+    //
+    // This call will block until a buffer is available to be dequeued. If
+    // both the producer and consumer are controlled by the app, then this call
+    // can never block and will return WOULD_BLOCK if no buffer is available.
+    //
+    // A non-negative value with flags set (see above) will be returned upon
+    // success.
+    //
+    // Return of a negative means an error has occurred:
+    // * NO_INIT - the buffer queue has been abandoned.
+    // * BAD_VALUE - one of the below conditions occurred:
+    //              * both in async mode and buffer count was less than the
+    //                max numbers of buffers that can be allocated at once
+    //              * attempting dequeue more than one buffer at a time
+    //                without setting the buffer count with setBufferCount()
+    // * -EBUSY - attempting to dequeue too many buffers at a time
+    // * WOULD_BLOCK - no buffer is currently available, and blocking is disabled
+    //                 since both the producer/consumer are controlled by app
+    // * NO_MEMORY - out of memory, cannot allocate the graphics buffer.
+    //
+    // All other negative values are an unknown error returned downstream
+    // from the graphics allocator (typically errno).
+    virtual status_t dequeueBuffer(int* slot, sp<Fence>* fence, bool async,
             uint32_t w, uint32_t h, uint32_t format, uint32_t usage) = 0;
 
     // queueBuffer indicates that the client has finished filling in the
     // contents of the buffer associated with slot and transfers ownership of
-    // that slot back to the server. It is not valid to call queueBuffer on a
+    // that slot back to the server.
-    // slot that is not owned by the client or one for which a buffer associated
+    //
-    // via requestBuffer. In addition, a timestamp must be provided by the
+    // It is not valid to call queueBuffer on a slot that is not owned
-    // client for this buffer. The timestamp is measured in nanoseconds, and
+    // by the client or one for which a buffer associated via requestBuffer
-    // must be monotonically increasing. Its other properties (zero point, etc)
+    // (an attempt to do so will fail with a return value of BAD_VALUE).
+    //
+    // In addition, the input must be described by the client (as documented
+    // below). Any other properties (zero point, etc)
     // are client-dependent, and should be documented by the client.
     //
-    // The async parameter sets whether we're queuing a buffer in asynchronous mode.
+    // The slot must be in the range of [0, NUM_BUFFER_SLOTS).
     //
-    // outWidth, outHeight and outTransform are filled with the default width
+    // Upon success, the output will be filled with meaningful values
-    // and height of the window and current transform applied to buffers,
+    // (refer to the documentation below).
-    // respectively.
+    //
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * NO_INIT - the buffer queue has been abandoned.
+    // * BAD_VALUE - one of the below conditions occurred:
+    //              * fence was NULL
+    //              * scaling mode was unknown
+    //              * both in async mode and buffer count was less than the
+    //                max numbers of buffers that can be allocated at once
+    //              * slot index was out of range (see above).
+    //              * the slot was not in the dequeued state
+    //              * the slot was enqueued without requesting a buffer
+    //              * crop rect is out of bounds of the buffer dimensions
 
     struct QueueBufferInput : public Flattenable<QueueBufferInput> {
         friend class Flattenable<QueueBufferInput>;
         inline QueueBufferInput(const Parcel& parcel);
+        // timestamp - a monotonically increasing value in nanoseconds
+        // isAutoTimestamp - if the timestamp was synthesized at queue time
+        // crop - a crop rectangle that's used as a hint to the consumer
+        // scalingMode - a set of flags from NATIVE_WINDOW_SCALING_* in <window.h>
+        // transform - a set of flags from NATIVE_WINDOW_TRANSFORM_* in <window.h>
+        // async - if the buffer is queued in asynchronous mode
+        // fence - a fence that the consumer must wait on before reading the buffer,
+        //         set this to Fence::NO_FENCE if the buffer is ready immediately
         inline QueueBufferInput(int64_t timestamp, bool isAutoTimestamp,
                 const Rect& crop, int scalingMode, uint32_t transform, bool async,
                 const sp<Fence>& fence)
@@ -143,8 +236,13 @@ public:
     };
 
     // QueueBufferOutput must be a POD structure
-    struct QueueBufferOutput {
+    struct __attribute__ ((__packed__)) QueueBufferOutput {
         inline QueueBufferOutput() { }
+        // outWidth - filled with default width applied to the buffer
+        // outHeight - filled with default height applied to the buffer
+        // outTransformHint - filled with default transform applied to the buffer
+        // outNumPendingBuffers - num buffers queued that haven't yet been acquired
+        //                        (counting the currently queued buffer)
         inline void deflate(uint32_t* outWidth,
                 uint32_t* outHeight,
                 uint32_t* outTransformHint,
@@ -174,24 +272,53 @@ public:
     // cancelBuffer indicates that the client does not wish to fill in the
     // buffer associated with slot and transfers ownership of the slot back to
     // the server.
+    //
+    // The buffer is not queued for use by the consumer.
+    //
+    // The buffer will not be overwritten until the fence signals.  The fence
+    // will usually be the one obtained from dequeueBuffer.
     virtual void cancelBuffer(int slot, const sp<Fence>& fence) = 0;
 
     // query retrieves some information for this surface
-    // 'what' tokens allowed are that of android_natives.h
+    // 'what' tokens allowed are that of NATIVE_WINDOW_* in <window.h>
+    //
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * NO_INIT - the buffer queue has been abandoned.
+    // * BAD_VALUE - what was out of range
     virtual int query(int what, int* value) = 0;
 
     // connect attempts to connect a client API to the IGraphicBufferProducer.
     // This must be called before any other IGraphicBufferProducer methods are
-    // called except for getAllocator.
+    // called except for getAllocator. A consumer must be already connected.
     //
     // This method will fail if the connect was previously called on the
     // IGraphicBufferProducer and no corresponding disconnect call was made.
     //
-    // outWidth, outHeight and outTransform are filled with the default width
+    // The token needs to be any opaque binder object that lives in the
-    // and height of the window and current transform applied to buffers,
-    // respectively. The token needs to be any binder object that lives in the
     // producer process -- it is solely used for obtaining a death notification
     // when the producer is killed.
+    //
+    // The api should be one of the NATIVE_WINDOW_API_* values in <window.h>
+    //
+    // The producerControlledByApp should be set to true if the producer is hosted
+    // by an untrusted process (typically app_process-forked processes). If both
+    // the producer and the consumer are app-controlled then all buffer queues
+    // will operate in async mode regardless of the async flag.
+    //
+    // Upon success, the output will be filled with meaningful data
+    // (refer to QueueBufferOutput documentation above).
+    //
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * NO_INIT - one of the following occurred:
+    //             * the buffer queue was abandoned
+    //             * no consumer has yet connected
+    // * BAD_VALUE - one of the following has occurred:
+    //             * the producer is already connected
+    //             * api was out of range (see above).
+    // * DEAD_OBJECT - the token is hosted by an already-dead process
+    //
+    // Additional negative errors may be returned by the internals, they
+    // should be treated as opaque fatal unrecoverable errors.
     virtual status_t connect(const sp<IBinder>& token,
             int api, bool producerControlledByApp, QueueBufferOutput* output) = 0;
 
@@ -203,6 +330,17 @@ public:
     //
     // This method will fail if the the IGraphicBufferProducer is not currently
     // connected to the specified client API.
+    //
+    // The api should be one of the NATIVE_WINDOW_API_* values in <window.h>
+    //
+    // Disconnecting from an abandoned IGraphicBufferProducer is legal and
+    // is considered a no-op.
+    //
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * BAD_VALUE - one of the following has occurred:
+    //             * the api specified does not match the one that was connected
+    //             * api was out of range (see above).
+    // * DEAD_OBJECT - the token is hosted by an already-dead process
     virtual status_t disconnect(int api) = 0;
 };
 

libs/gui/BufferQueue.cpp

@@ -703,7 +703,7 @@ retry:
     return err;
 }
 
-void BufferQueue::binderDied(const wp<IBinder>& who) {
+void BufferQueue::binderDied(const wp<IBinder>& who __attribute__((unused))) {
     // If we're here, it means that a producer we were connected to died.
     // We're GUARANTEED that we still are connected to it because it has no other way
     // to get disconnected -- or -- we wouldn't be here because we're removing this

libs/gui/ConsumerBase.cpp

@@ -85,7 +85,7 @@ ConsumerBase::~ConsumerBase() {
         "consumer is not abandoned!", mName.string());
 }
 
-void ConsumerBase::onLastStrongRef(const void* id) {
+void ConsumerBase::onLastStrongRef(const void* id __attribute__((unused))) {
     abandon();
 }
 
@@ -243,7 +243,7 @@ status_t ConsumerBase::releaseBufferLocked(
             slot, mSlots[slot].mFrameNumber);
     status_t err = mConsumer->releaseBuffer(slot, mSlots[slot].mFrameNumber,
             display, eglFence, mSlots[slot].mFence);
-    if (err == BufferQueue::STALE_BUFFER_SLOT) {
+    if (err == IGraphicBufferConsumer::STALE_BUFFER_SLOT) {
         freeBufferLocked(slot);
     }
 

libs/gui/IGraphicBufferConsumer.cpp

@@ -223,7 +223,7 @@ public:
     }
 
     virtual status_t releaseBuffer(int buf, uint64_t frameNumber,
-            EGLDisplay display, EGLSyncKHR fence,
+            EGLDisplay display __attribute__((unused)), EGLSyncKHR fence __attribute__((unused)),
             const sp<Fence>& releaseFence) {
         Parcel data, reply;
         data.writeInterfaceToken(IGraphicBufferConsumer::getInterfaceDescriptor());

libs/gui/Surface.cpp

@@ -251,7 +251,7 @@ int Surface::getSlotFromBufferLocked(
     return BAD_VALUE;
 }
 
-int Surface::lockBuffer_DEPRECATED(android_native_buffer_t* buffer) {
+int Surface::lockBuffer_DEPRECATED(android_native_buffer_t* buffer __attribute__((unused))) {
     ALOGV("Surface::lockBuffer");
     Mutex::Autolock lock(mMutex);
     return OK;
@@ -482,7 +482,7 @@ int Surface::dispatchLock(va_list args) {
     return lock(outBuffer, inOutDirtyBounds);
 }
 
-int Surface::dispatchUnlockAndPost(va_list args) {
+int Surface::dispatchUnlockAndPost(va_list args __attribute__((unused))) {
     return unlockAndPost();
 }