buffer_hub_client.h revision ec971362bc651d8c98febb8399981877da859c14
1#ifndef ANDROID_DVR_BUFFER_HUB_CLIENT_H_ 2#define ANDROID_DVR_BUFFER_HUB_CLIENT_H_ 3 4#include <hardware/gralloc.h> 5#include <pdx/channel_handle.h> 6#include <pdx/client.h> 7#include <pdx/file_handle.h> 8#include <pdx/status.h> 9 10#include <vector> 11 12#include <private/dvr/ion_buffer.h> 13 14namespace android { 15namespace dvr { 16 17class BufferHubBuffer : public pdx::Client { 18 public: 19 using LocalHandle = pdx::LocalHandle; 20 using LocalChannelHandle = pdx::LocalChannelHandle; 21 template <typename T> 22 using Status = pdx::Status<T>; 23 24 // Create a new consumer channel that is attached to the producer. Returns 25 // a file descriptor for the new channel or a negative error code. 26 Status<LocalChannelHandle> CreateConsumer(); 27 28 // Polls the fd for |timeout_ms| milliseconds (-1 for infinity). 29 int Poll(int timeout_ms); 30 31 // Locks the area specified by (x, y, width, height) for a specific usage. If 32 // the usage is software then |addr| will be updated to point to the address 33 // of the buffer in virtual memory. The caller should only access/modify the 34 // pixels in the specified area. anything else is undefined behavior. 35 int Lock(int usage, int x, int y, int width, int height, void** addr, 36 size_t index); 37 38 // Must be called after Lock() when the caller has finished changing the 39 // buffer. 40 int Unlock(size_t index); 41 42 // Helper for when index is 0. 43 int Lock(int usage, int x, int y, int width, int height, void** addr) { 44 return Lock(usage, x, y, width, height, addr, 0); 45 } 46 47 // Helper for when index is 0. 48 int Unlock() { return Unlock(0); } 49 50 // Gets a blob buffer that was created with BufferProducer::CreateBlob. 51 // Locking and Unlocking is handled internally. There's no need to Unlock 52 // after calling this method. 53 int GetBlobReadWritePointer(size_t size, void** addr); 54 55 // Gets a blob buffer that was created with BufferProducer::CreateBlob. 56 // Locking and Unlocking is handled internally. There's no need to Unlock 57 // after calling this method. 58 int GetBlobReadOnlyPointer(size_t size, void** addr); 59 60 // Returns a dup'd file descriptor for accessing the blob shared memory. The 61 // caller takes ownership of the file descriptor and must close it or pass on 62 // ownership. Some GPU API extensions can take file descriptors to bind shared 63 // memory gralloc buffers to GPU buffer objects. 64 LocalHandle GetBlobFd() const { 65 // Current GPU vendor puts the buffer allocation in one FD. If we change GPU 66 // vendors and this is the wrong fd, late-latching and EDS will very clearly 67 // stop working and we will need to correct this. The alternative is to use 68 // a GL context in the pose service to allocate this buffer or to use the 69 // ION API directly instead of gralloc. 70 return LocalHandle(dup(native_handle()->data[0])); 71 } 72 73 // Get up to |max_fds_count| file descriptors for accessing the blob shared 74 // memory. |fds_count| will contain the actual number of file descriptors. 75 void GetBlobFds(int* fds, size_t* fds_count, size_t max_fds_count) const; 76 77 using Client::event_fd; 78 79 Status<int> GetEventMask(int events) { 80 if (auto* client_channel = GetChannel()) { 81 return client_channel->GetEventMask(events); 82 } else { 83 return pdx::ErrorStatus(EINVAL); 84 } 85 } 86 87 native_handle_t* native_handle() const { 88 return const_cast<native_handle_t*>(slices_[0].handle()); 89 } 90 // If index is greater than or equal to slice_count(), the result is 91 // undefined. 92 native_handle_t* native_handle(size_t index) const { 93 return const_cast<native_handle_t*>(slices_[index].handle()); 94 } 95 96 IonBuffer* buffer() { return &slices_[0]; } 97 const IonBuffer* buffer() const { return &slices_[0]; } 98 99 // If index is greater than or equal to slice_count(), the result is 100 // undefined. 101 IonBuffer* slice(size_t index) { return &slices_[index]; } 102 const IonBuffer* slice(size_t index) const { return &slices_[index]; } 103 104 int slice_count() const { return static_cast<int>(slices_.size()); } 105 int id() const { return id_; } 106 107 // The following methods return settings of the first buffer. Currently, 108 // it is only possible to create multi-buffer BufferHubBuffers with the same 109 // settings. 110 uint32_t width() const { return slices_[0].width(); } 111 uint32_t height() const { return slices_[0].height(); } 112 uint32_t stride() const { return slices_[0].stride(); } 113 uint32_t format() const { return slices_[0].format(); } 114 uint32_t usage() const { return slices_[0].usage(); } 115 uint32_t layer_count() const { return slices_[0].layer_count(); } 116 117 // TODO(b/37881101) Clean up producer/consumer usage. 118 uint64_t producer_usage() const { return slices_[0].usage(); } 119 uint64_t consumer_usage() const { return slices_[0].usage(); } 120 121 protected: 122 explicit BufferHubBuffer(LocalChannelHandle channel); 123 explicit BufferHubBuffer(const std::string& endpoint_path); 124 virtual ~BufferHubBuffer(); 125 126 // Initialization helper. 127 int ImportBuffer(); 128 129 private: 130 BufferHubBuffer(const BufferHubBuffer&) = delete; 131 void operator=(const BufferHubBuffer&) = delete; 132 133 // Global id for the buffer that is consistent across processes. It is meant 134 // for logging and debugging purposes only and should not be used for lookup 135 // or any other functional purpose as a security precaution. 136 int id_; 137 138 // A BufferHubBuffer may contain multiple slices of IonBuffers with same 139 // configurations. 140 std::vector<IonBuffer> slices_; 141}; 142 143// This represents a writable buffer. Calling Post notifies all clients and 144// makes the buffer read-only. Call Gain to acquire write access. A buffer 145// may have many consumers. 146// 147// The user of BufferProducer is responsible with making sure that the Post() is 148// done with the correct metadata type and size. The user is also responsible 149// for making sure that remote ends (BufferConsumers) are also using the correct 150// metadata when acquiring the buffer. The API guarantees that a Post() with a 151// metadata of wrong size will fail. However, it currently does not do any 152// type checking. 153// The API also assumes that metadata is a serializable type (plain old data). 154class BufferProducer : public pdx::ClientBase<BufferProducer, BufferHubBuffer> { 155 public: 156 // Create a buffer designed to hold arbitrary bytes that can be read and 157 // written from CPU, GPU and DSP. The buffer is mapped uncached so that CPU 158 // reads and writes are predictable. 159 static std::unique_ptr<BufferProducer> CreateUncachedBlob(size_t size); 160 161 // Creates a persistent uncached buffer with the given name and access. 162 static std::unique_ptr<BufferProducer> CreatePersistentUncachedBlob( 163 const std::string& name, int user_id, int group_id, size_t size); 164 165 // Imports a bufferhub producer channel, assuming ownership of its handle. 166 static std::unique_ptr<BufferProducer> Import(LocalChannelHandle channel); 167 static std::unique_ptr<BufferProducer> Import( 168 Status<LocalChannelHandle> status); 169 170 // Post this buffer, passing |ready_fence| to the consumers. The bytes in 171 // |meta| are passed unaltered to the consumers. The producer must not modify 172 // the buffer until it is re-gained. 173 // This returns zero or a negative unix error code. 174 int Post(const LocalHandle& ready_fence, const void* meta, 175 size_t meta_size_bytes); 176 177 template <typename Meta, 178 typename = typename std::enable_if<std::is_void<Meta>::value>::type> 179 int Post(const LocalHandle& ready_fence) { 180 return Post(ready_fence, nullptr, 0); 181 } 182 template <typename Meta, typename = typename std::enable_if< 183 !std::is_void<Meta>::value>::type> 184 int Post(const LocalHandle& ready_fence, const Meta& meta) { 185 return Post(ready_fence, &meta, sizeof(meta)); 186 } 187 188 // Attempt to re-gain the buffer for writing. If |release_fence| is valid, it 189 // must be waited on before using the buffer. If it is not valid then the 190 // buffer is free for immediate use. This call will only succeed if the buffer 191 // is in the released state. 192 // This returns zero or a negative unix error code. 193 int Gain(LocalHandle* release_fence); 194 195 // Asynchronously marks a released buffer as gained. This method is similar to 196 // the synchronous version above, except that it does not wait for BufferHub 197 // to acknowledge success or failure, nor does it transfer a release fence to 198 // the client. This version may be used in situations where a release fence is 199 // not needed. Because of the asynchronous nature of the underlying message, 200 // no error is returned if this method is called when the buffer is in an 201 // incorrect state. Returns zero if sending the message succeeded, or a 202 // negative errno code otherwise. 203 int GainAsync(); 204 205 // Attaches the producer to |name| so that it becomes a persistent buffer that 206 // may be retrieved by name at a later time. This may be used in cases where a 207 // shared memory buffer should persist across the life of the producer process 208 // (i.e. the buffer may be held by clients across a service restart). The 209 // buffer may be associated with a user and/or group id to restrict access to 210 // the buffer. If user_id or group_id is -1 then checks for the respective id 211 // are disabled. If user_id or group_id is 0 then the respective id of the 212 // calling process is used instead. 213 int MakePersistent(const std::string& name, int user_id, int group_id); 214 215 // Removes the persistence of the producer. 216 int RemovePersistence(); 217 218 private: 219 friend BASE; 220 221 // Constructors are automatically exposed through BufferProducer::Create(...) 222 // static template methods inherited from ClientBase, which take the same 223 // arguments as the constructors. 224 225 // Constructs a buffer with the given geometry and parameters. 226 BufferProducer(uint32_t width, uint32_t height, uint32_t format, 227 uint32_t usage, size_t metadata_size = 0, 228 size_t slice_count = 1); 229 BufferProducer(uint32_t width, uint32_t height, uint32_t format, 230 uint64_t producer_usage, uint64_t consumer_usage, 231 size_t metadata_size, size_t slice_count); 232 233 // Constructs a persistent buffer with the given geometry and parameters and 234 // binds it to |name| in one shot. If a persistent buffer with the same name 235 // and settings already exists and matches the given geometry and parameters, 236 // that buffer is connected to this client instead of creating a new buffer. 237 // If the name matches but the geometry or settings do not match then 238 // construction fails and BufferProducer::Create() returns nullptr. 239 // 240 // Access to the persistent buffer may be restricted by |user_id| and/or 241 // |group_id|; these settings are established only when the buffer is first 242 // created and cannot be changed. A user or group id of -1 disables checks for 243 // that respective id. A user or group id of 0 is substituted with the 244 // effective user or group id of the calling process. 245 BufferProducer(const std::string& name, int user_id, int group_id, 246 uint32_t width, uint32_t height, uint32_t format, 247 uint32_t usage, size_t metadata_size = 0, 248 size_t slice_count = 1); 249 BufferProducer(const std::string& name, int user_id, int group_id, 250 uint32_t width, uint32_t height, uint32_t format, 251 uint64_t producer_usage, uint64_t consumer_usage, 252 size_t metadata_size, size_t slice_count); 253 254 // Constructs a blob (flat) buffer with the given usage flags. 255 BufferProducer(uint32_t usage, size_t size); 256 BufferProducer(uint64_t producer_usage, uint64_t consumer_usage, size_t size); 257 258 // Constructs a persistent blob (flat) buffer and binds it to |name|. 259 BufferProducer(const std::string& name, int user_id, int group_id, 260 uint32_t usage, size_t size); 261 BufferProducer(const std::string& name, int user_id, int group_id, 262 uint64_t producer_usage, uint64_t consumer_usage, size_t size); 263 264 // Constructs a channel to persistent buffer by name only. The buffer must 265 // have been previously created or made persistent. 266 explicit BufferProducer(const std::string& name); 267 268 // Imports the given file handle to a producer channel, taking ownership. 269 explicit BufferProducer(LocalChannelHandle channel); 270}; 271 272// This is a connection to a producer buffer, which can be located in another 273// application. When that buffer is Post()ed, this fd will be signaled and 274// Acquire allows read access. The user is responsible for making sure that 275// Acquire is called with the correct metadata structure. The only guarantee the 276// API currently provides is that an Acquire() with metadata of the wrong size 277// will fail. 278class BufferConsumer : public pdx::ClientBase<BufferConsumer, BufferHubBuffer> { 279 public: 280 // This call assumes ownership of |fd|. 281 static std::unique_ptr<BufferConsumer> Import(LocalChannelHandle channel); 282 static std::unique_ptr<BufferConsumer> Import( 283 Status<LocalChannelHandle> status); 284 285 // Attempt to retrieve a post event from buffer hub. If successful, 286 // |ready_fence| will be set to a fence to wait on until the buffer is ready. 287 // This call will only succeed after the fd is signalled. This call may be 288 // performed as an alternative to the Acquire() with metadata. In such cases 289 // the metadata is not read. 290 // 291 // This returns zero or negative unix error code. 292 int Acquire(LocalHandle* ready_fence); 293 294 // Attempt to retrieve a post event from buffer hub. If successful, 295 // |ready_fence| is set to a fence signaling that the contents of the buffer 296 // are available. This call will only succeed if the buffer is in the posted 297 // state. 298 // Returns zero on success, or a negative errno code otherwise. 299 int Acquire(LocalHandle* ready_fence, void* meta, size_t meta_size_bytes); 300 301 // Attempt to retrieve a post event from buffer hub. If successful, 302 // |ready_fence| is set to a fence to wait on until the buffer is ready. This 303 // call will only succeed after the fd is signaled. This returns zero or a 304 // negative unix error code. 305 template <typename Meta> 306 int Acquire(LocalHandle* ready_fence, Meta* meta) { 307 return Acquire(ready_fence, meta, sizeof(*meta)); 308 } 309 310 // This should be called after a successful Acquire call. If the fence is 311 // valid the fence determines the buffer usage, otherwise the buffer is 312 // released immediately. 313 // This returns zero or a negative unix error code. 314 int Release(const LocalHandle& release_fence); 315 316 // Asynchronously releases a buffer. Similar to the synchronous version above, 317 // except that it does not wait for BufferHub to reply with success or error, 318 // nor does it transfer a release fence. This version may be used in 319 // situations where a release fence is not needed. Because of the asynchronous 320 // nature of the underlying message, no error is returned if this method is 321 // called when the buffer is in an incorrect state. Returns zero if sending 322 // the message succeeded, or a negative errno code otherwise. 323 int ReleaseAsync(); 324 325 // May be called after or instead of Acquire to indicate that the consumer 326 // does not need to access the buffer this cycle. This returns zero or a 327 // negative unix error code. 328 int Discard(); 329 330 // When set, this consumer is no longer notified when this buffer is 331 // available. The system behaves as if Discard() is immediately called 332 // whenever the buffer is posted. If ignore is set to true while a buffer is 333 // pending, it will act as if Discard() was also called. 334 // This returns zero or a negative unix error code. 335 int SetIgnore(bool ignore); 336 337 private: 338 friend BASE; 339 340 explicit BufferConsumer(LocalChannelHandle channel); 341}; 342 343} // namespace dvr 344} // namespace android 345 346#endif // ANDROID_DVR_BUFFER_HUB_CLIENT_H_ 347