1 /*
2  * Copyright (C) 2019 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 HARDWARE_GOOGLE_CAMERA_HAL_UTILS_ZSL_BUFFER_MANAGER_H
18 #define HARDWARE_GOOGLE_CAMERA_HAL_UTILS_ZSL_BUFFER_MANAGER_H
19 
20 #include <utils/Errors.h>
21 #include <deque>
22 #include <functional>
23 #include <list>
24 #include <map>
25 #include <memory>
26 #include <mutex>
27 #include <vector>
28 
29 #include "gralloc_buffer_allocator.h"
30 #include "hal_buffer_allocator.h"
31 
32 #include "hal_types.h"
33 
34 namespace android {
35 namespace google_camera_hal {
36 
37 // ZslBufferManager creates and manages ZSL buffers.
38 class ZslBufferManager {
39  public:
40   // allocator will be used to allocate buffers. If allocator is nullptr,
41   // GrallocBufferAllocator will be used to allocate buffers.
42   ZslBufferManager(IHalBufferAllocator* allocator = nullptr);
43   virtual ~ZslBufferManager();
44 
45   // Defines a ZSL buffer.
46   struct ZslBuffer {
47     // Original frame number of this ZSL buffer captured by HAL.
48     uint32_t frame_number = 0;
49     // Buffer
50     StreamBuffer buffer;
51     // Original result metadata of this ZSL buffer captured by HAL.
52     std::unique_ptr<HalCameraMetadata> metadata;
53   };
54 
55   // Allocate buffers. This can only be called once.
56   // The second call will return ALREADY_EXISTS.
57   status_t AllocateBuffers(const HalBufferDescriptor& buffer_descriptor);
58 
59   // Get an empty buffer for capture. The caller can modify the buffer data
60   // but the buffer is owned by ZslBufferManager and
61   // must not be freed by the caller.
62   buffer_handle_t GetEmptyBuffer();
63 
64   // Return an empty buffer that was previously obtained by GetEmptyBuffer().
65   status_t ReturnEmptyBuffer(buffer_handle_t buffer);
66 
67   // Return the buffer part of a filled buffer
68   // that was previously obtained by GetEmptyBuffer().
69   status_t ReturnFilledBuffer(uint32_t frame_number, const StreamBuffer& buffer);
70 
71   // Return the metadata part of a filled buffer
72   // that was previously obtained by GetEmptyBuffer().
73   // ZSL buffer manager will make a copy of metadata.
74   // The caller still owns metadata.
75   status_t ReturnMetadata(uint32_t frame_number,
76                           const HalCameraMetadata* metadata);
77 
78   // Get a number of the most recent ZSL buffers.
79   // If numBuffers is larger than available ZSL buffers,
80   // zslBuffers will contain all available ZSL buffers,
81   // i.e. zslBuffers.size() may be smaller than numBuffers.
82   // The buffer and metadata are owned by ZslBufferManager and
83   // must not be freed by the caller.
84   // minBuffers is the minimum number of buffers the
85   // zsl buffer manager should return. If this can not be satisfied
86   // (i.e. not enough ZSL buffers exist),
87   // this GetMostRecentZslBuffers returns an empty vector.
88   void GetMostRecentZslBuffers(std::vector<ZslBuffer>* zsl_buffers,
89                                uint32_t num_buffers, uint32_t min_buffers);
90 
91   // Return a ZSL buffer that was previously obtained by
92   // GetMostRecentZslBuffers().
93   void ReturnZslBuffer(ZslBuffer zsl_buffer);
94 
95   // Return a vector of ZSL buffers that were previously obtained by
96   // GetMostRecentZslBuffers().
97   void ReturnZslBuffers(std::vector<ZslBuffer> zsl_buffers);
98 
99   // Check ZslBuffers are allocated or not.
100   bool IsBufferAllocated() {
101     return allocated_;
102   };
103 
104   // Check pending_zsl_buffers_ is empty or not.
105   bool IsPendingBufferEmpty();
106 
107   // Add buffer map to pending_zsl_buffers_
108   void AddPendingBuffers(const std::vector<ZslBuffer>& buffers);
109 
110   // Clean buffer map from pending_zsl_buffers_
111   status_t CleanPendingBuffers(std::vector<ZslBuffer>* buffers);
112 
113  private:
114   static const uint32_t kMaxPartialZslBuffers = 100;
115 
116   // Max timestamp difference of the ZSL buffer and current time. Used
117   // to discard old ZSL buffers.
118   static const int64_t kMaxBufferTimestampDiff = 1000000000;  // 1 second
119 
120   // Maximum number of unused buffers. When the number of unused buffers >
121   // kMaxUnusedBuffers, it will try to free excessive buffers.
122   static const uint32_t kMaxUnusedBuffers = 2;
123 
124   const bool kMemoryProfilingEnabled;
125 
126   // Remove the oldest metadata.
127   status_t RemoveOldestMetadataLocked();
128 
129   // Get current BOOT_TIME timestamp in nanoseconds
130   status_t GetCurrentTimestampNs(int64_t* current_timestamp);
131 
132   // Allocate a number of buffers. Must be protected by zsl_buffers_lock_.
133   status_t AllocateBuffersLocked(uint32_t buffer_number);
134 
135   // Get an empty buffer. Must be protected by zsl_buffers_lock_.
136   buffer_handle_t GetEmptyBufferLocked();
137 
138   // Try to free unused buffers. Must be protected by zsl_buffers_lock_.
139   void FreeUnusedBuffersLocked();
140 
141   bool allocated_ = false;
142   std::mutex zsl_buffers_lock_;
143 
144   // Buffer manager for allocating the buffers. Protected by mZslBuffersLock.
145   std::unique_ptr<IHalBufferAllocator> internal_buffer_allocator_;
146 
147   // external buffer allocator
148   IHalBufferAllocator* buffer_allocator_ = nullptr;
149 
150   // Empty ZSL buffer queue. Protected by mZslBuffersLock.
151   std::deque<buffer_handle_t> empty_zsl_buffers_;
152 
153   // Filled ZSL buffers. Map from frameNumber to ZslBuffer.
154   // Ordered from the oldest to the newest buffers.
155   // Protected by mZslBuffersLock.
156   std::map<uint32_t, ZslBuffer> filled_zsl_buffers_;
157 
158   // Partially filled ZSL buffers. Either the metadata or
159   // the buffer is returned. Once the metadata and the buffer are both ready,
160   // the ZslBuffer will be moved to the filled_zsl_buffers_.
161   // Map from frameNumber to ZslBuffer. Ordered from the oldest to the newest
162   // buffers. filled_zsl_buffers_ protected by zsl_buffers_lock_.
163   std::map<uint32_t, ZslBuffer> partially_filled_zsl_buffers_;
164 
165   // Store all allocated buffers return from GrallocBufferAllocator
166   std::vector<buffer_handle_t> buffers_;
167 
168   std::mutex pending_zsl_buffers_mutex;
169 
170   // Map from buffer handle to ZSL buffer. Protected by pending_zsl_buffers_mutex.
171   std::unordered_map<buffer_handle_t, ZslBuffer> pending_zsl_buffers_;
172 
173   // Store the buffer descriptor when call AllocateBuffers()
174   // Use it for AllocateExtraBuffers()
175   HalBufferDescriptor buffer_descriptor_;
176 };
177 
178 }  // namespace google_camera_hal
179 }  // namespace android
180 
181 #endif  // HARDWARE_GOOGLE_CAMERA_HAL_UTILS_ZSL_BUFFER_MANAGER_H
182