1 /*
2  * Copyright (C) 2018 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef ANDROID_BUFFER_HUB_BUFFER_H_
18 #define ANDROID_BUFFER_HUB_BUFFER_H_
19 
20 #include <android/frameworks/bufferhub/1.0/IBufferClient.h>
21 #include <android/hardware_buffer.h>
22 #include <cutils/native_handle.h>
23 #include <ui/BufferHubDefs.h>
24 #include <ui/BufferHubEventFd.h>
25 #include <ui/BufferHubMetadata.h>
26 #include <utils/NativeHandle.h>
27 
28 namespace android {
29 
30 class BufferHubBuffer {
31 public:
32     // Allocates a standalone BufferHubBuffer.
33     static std::unique_ptr<BufferHubBuffer> create(uint32_t width, uint32_t height,
34                                                    uint32_t layerCount, uint32_t format,
35                                                    uint64_t usage, size_t userMetadataSize);
36 
37     // Imports the given token to a BufferHubBuffer. Not taking ownership of the token.
38     static std::unique_ptr<BufferHubBuffer> import(const sp<NativeHandle>& token);
39 
40     BufferHubBuffer(const BufferHubBuffer&) = delete;
41     void operator=(const BufferHubBuffer&) = delete;
42 
43     virtual ~BufferHubBuffer();
44 
45     // Gets ID of the buffer client. All BufferHubBuffer clients derived from the same buffer in
46     // BufferHub share the same buffer id.
id()47     int id() const { return mId; }
48 
49     // Returns the buffer description, which is guaranteed to be faithful values from BufferHub.
desc()50     const AHardwareBuffer_Desc& desc() const { return mBufferDesc; }
51 
52     // Duplicate the underlying Gralloc buffer handle. Caller is responsible to free the handle
53     // after use.
duplicateHandle()54     native_handle_t* duplicateHandle() {
55         return native_handle_clone(mBufferHandle.getNativeHandle());
56     }
57 
eventFd()58     const BufferHubEventFd& eventFd() const { return mEventFd; }
59 
60     // Returns the current value of MetadataHeader::bufferState.
bufferState()61     uint32_t bufferState() const { return mBufferState->load(std::memory_order_acquire); }
62 
63     // A state mask which is unique to a buffer hub client among all its siblings sharing the same
64     // concrete graphic buffer.
clientStateMask()65     uint32_t clientStateMask() const { return mClientStateMask; }
66 
userMetadataSize()67     size_t userMetadataSize() const { return mMetadata.userMetadataSize(); }
68 
69     // Returns true if the BufferClient is still alive.
isConnected()70     bool isConnected() const { return mBufferClient->ping().isOk(); }
71 
72     // Returns true if the buffer is valid: non-null buffer handle, valid id, valid client bit mask,
73     // valid metadata and valid buffer client
74     bool isValid() const;
75 
76     // Gains the buffer for exclusive write permission. Read permission is implied once a buffer is
77     // gained.
78     // The buffer can be gained as long as there is no other client in acquired or gained state.
79     int gain();
80 
81     // Posts the gained buffer for other buffer clients to use the buffer.
82     // The buffer can be posted iff the buffer state for this client is gained.
83     // After posting the buffer, this client is put to released state and does not have access to
84     // the buffer for this cycle of the usage of the buffer.
85     int post();
86 
87     // Acquires the buffer for shared read permission.
88     // The buffer can be acquired iff the buffer state for this client is posted.
89     int acquire();
90 
91     // Releases the buffer.
92     // The buffer can be released from any buffer state.
93     // After releasing the buffer, this client no longer have any permissions to the buffer for the
94     // current cycle of the usage of the buffer.
95     int release();
96 
97     // Returns whether the buffer is released by all active clients or not.
98     bool isReleased() const;
99 
100     // Creates a token that stands for this BufferHubBuffer client and could be used for Import to
101     // create another BufferHubBuffer. The new BufferHubBuffer will share the same underlying
102     // gralloc buffer and ashmem region for metadata. Not taking ownership of the token.
103     // Returns a valid token on success, nullptr on failure.
104     sp<NativeHandle> duplicate();
105 
106 private:
107     BufferHubBuffer(uint32_t width, uint32_t height, uint32_t layerCount, uint32_t format,
108                     uint64_t usage, size_t userMetadataSize);
109 
110     BufferHubBuffer(const sp<NativeHandle>& token);
111 
112     int initWithBufferTraits(const frameworks::bufferhub::V1_0::BufferTraits& bufferTraits);
113 
114     // Global id for the buffer that is consistent across processes.
115     int mId = 0;
116 
117     // Client state mask of this BufferHubBuffer object. It is unique amoung all
118     // clients/users of the buffer.
119     uint32_t mClientStateMask = 0U;
120 
121     // Stores ground truth of the buffer.
122     AHardwareBuffer_Desc mBufferDesc;
123 
124     // Wraps the gralloc buffer handle of this buffer.
125     hardware::hidl_handle mBufferHandle;
126 
127     // Event fd used for signalling buffer state changes. Shared by all clients of the same buffer.
128     BufferHubEventFd mEventFd;
129 
130     // An ashmem-based metadata object. The same shared memory are mapped to the
131     // bufferhubd daemon and all buffer clients.
132     BufferHubMetadata mMetadata;
133     // Shortcuts to the atomics inside the header of mMetadata.
134     std::atomic<uint32_t>* mBufferState = nullptr;
135     std::atomic<uint32_t>* mFenceState = nullptr;
136     std::atomic<uint32_t>* mActiveClientsBitMask = nullptr;
137 
138     // HwBinder backend
139     sp<frameworks::bufferhub::V1_0::IBufferClient> mBufferClient;
140 };
141 
142 } // namespace android
143 
144 #endif // ANDROID_BUFFER_HUB_BUFFER_H_
145