Alex Vakulenko | e4eec20 | 2017-01-27 14:41:04 -0800 | [diff] [blame] | 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 | |
| 14 | namespace android { |
| 15 | namespace dvr { |
| 16 | |
| 17 | class 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 | |
Hendrik Wagenaar | 10e68eb | 2017-03-15 13:29:02 -0700 | [diff] [blame] | 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 | |
Alex Vakulenko | e4eec20 | 2017-01-27 14:41:04 -0800 | [diff] [blame] | 77 | using Client::event_fd; |
Corey Tabaka | 3079cb7 | 2017-01-19 15:07:26 -0800 | [diff] [blame] | 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 | |
Alex Vakulenko | e4eec20 | 2017-01-27 14:41:04 -0800 | [diff] [blame] | 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]; } |
Corey Tabaka | 2655e1c | 2017-04-04 11:07:05 -0700 | [diff] [blame] | 97 | const IonBuffer* buffer() const { return &slices_[0]; } |
| 98 | |
Alex Vakulenko | e4eec20 | 2017-01-27 14:41:04 -0800 | [diff] [blame] | 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]; } |
Corey Tabaka | 2655e1c | 2017-04-04 11:07:05 -0700 | [diff] [blame] | 102 | const IonBuffer* slice(size_t index) const { return &slices_[index]; } |
Alex Vakulenko | e4eec20 | 2017-01-27 14:41:04 -0800 | [diff] [blame] | 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. |
Corey Tabaka | cd52dd9 | 2017-04-07 18:03:57 -0700 | [diff] [blame] | 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(); } |
Corey Tabaka | ec97136 | 2017-05-05 18:14:54 +0000 | [diff] [blame^] | 114 | uint32_t usage() const { return slices_[0].usage(); } |
Corey Tabaka | cd52dd9 | 2017-04-07 18:03:57 -0700 | [diff] [blame] | 115 | uint32_t layer_count() const { return slices_[0].layer_count(); } |
Jiwen 'Steve' Cai | 044963e | 2017-05-01 22:43:21 -0700 | [diff] [blame] | 116 | |
Corey Tabaka | ec97136 | 2017-05-05 18:14:54 +0000 | [diff] [blame^] | 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 | |
Alex Vakulenko | e4eec20 | 2017-01-27 14:41:04 -0800 | [diff] [blame] | 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). |
| 154 | class 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 | } |
Corey Tabaka | 2655e1c | 2017-04-04 11:07:05 -0700 | [diff] [blame] | 182 | template <typename Meta, typename = typename std::enable_if< |
| 183 | !std::is_void<Meta>::value>::type> |
Alex Vakulenko | e4eec20 | 2017-01-27 14:41:04 -0800 | [diff] [blame] | 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. |
Corey Tabaka | cd52dd9 | 2017-04-07 18:03:57 -0700 | [diff] [blame] | 226 | BufferProducer(uint32_t width, uint32_t height, uint32_t format, |
Corey Tabaka | ec97136 | 2017-05-05 18:14:54 +0000 | [diff] [blame^] | 227 | uint32_t usage, size_t metadata_size = 0, |
Corey Tabaka | cd52dd9 | 2017-04-07 18:03:57 -0700 | [diff] [blame] | 228 | size_t slice_count = 1); |
Corey Tabaka | ec97136 | 2017-05-05 18:14:54 +0000 | [diff] [blame^] | 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); |
Alex Vakulenko | e4eec20 | 2017-01-27 14:41:04 -0800 | [diff] [blame] | 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. |
Corey Tabaka | cd52dd9 | 2017-04-07 18:03:57 -0700 | [diff] [blame] | 245 | BufferProducer(const std::string& name, int user_id, int group_id, |
| 246 | uint32_t width, uint32_t height, uint32_t format, |
Corey Tabaka | ec97136 | 2017-05-05 18:14:54 +0000 | [diff] [blame^] | 247 | uint32_t usage, size_t metadata_size = 0, |
Alex Vakulenko | e4eec20 | 2017-01-27 14:41:04 -0800 | [diff] [blame] | 248 | size_t slice_count = 1); |
Corey Tabaka | ec97136 | 2017-05-05 18:14:54 +0000 | [diff] [blame^] | 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); |
Alex Vakulenko | e4eec20 | 2017-01-27 14:41:04 -0800 | [diff] [blame] | 253 | |
| 254 | // Constructs a blob (flat) buffer with the given usage flags. |
Corey Tabaka | ec97136 | 2017-05-05 18:14:54 +0000 | [diff] [blame^] | 255 | BufferProducer(uint32_t usage, size_t size); |
| 256 | BufferProducer(uint64_t producer_usage, uint64_t consumer_usage, size_t size); |
Alex Vakulenko | e4eec20 | 2017-01-27 14:41:04 -0800 | [diff] [blame] | 257 | |
| 258 | // Constructs a persistent blob (flat) buffer and binds it to |name|. |
Corey Tabaka | cd52dd9 | 2017-04-07 18:03:57 -0700 | [diff] [blame] | 259 | BufferProducer(const std::string& name, int user_id, int group_id, |
Corey Tabaka | ec97136 | 2017-05-05 18:14:54 +0000 | [diff] [blame^] | 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); |
Alex Vakulenko | e4eec20 | 2017-01-27 14:41:04 -0800 | [diff] [blame] | 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. |
| 278 | class 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_ |