1 /* 2 * Copyright (C) 2016 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 C2BUFFER_BASE_H_ 18 #define C2BUFFER_BASE_H_ 19 20 /// \defgroup allocator Allocation and memory placement 21 /// @{ 22 23 /** 24 * Buffer/memory usage bits. These shall be used by the allocators to select optimal memory type/ 25 * pool and buffer layout. Usage bits are conceptually separated into read and write usage, while 26 * the buffer use life-cycle is separated into producers (writers) and consumers (readers). 27 * These two concepts are related but not equivalent: consumers may only read buffers and only 28 * producers may write to buffers; note, however, that buffer producers may also want or need to 29 * read the buffers. 30 * 31 * Read and write buffer usage bits shall be or-ed to arrive at the full buffer usage. Admittedly, 32 * this does not account for the amount of reading and writing (e.g. a buffer may have one or more 33 * readers); however, the proper information necessary to properly weigh the various usages would be 34 * the amount of data read/written for each usage type. This would result in an integer array of 35 * size 64 (or the number of distinct usages) for memory usage, and likely such detailed information 36 * would not always be available. 37 * 38 * That platform-agnostic Codec 2.0 API only defines the bare minimum usages. Platforms shall define 39 * usage bits that are appropriate for the platform. 40 */ 41 struct C2MemoryUsage { 42 // public: 43 /** 44 * Buffer read usage. 45 */ 46 enum read_t : uint64_t { 47 /** Buffer is read by the CPU. */ 48 CPU_READ = 1 << 0, 49 /** 50 * Buffer shall only be read by trusted hardware. The definition of trusted hardware is 51 * platform specific, but this flag is reserved to prevent mapping this block into CPU 52 * readable memory resulting in bus fault. This flag can be used when buffer access must be 53 * protected. 54 */ 55 READ_PROTECTED = 1 << 1, 56 }; 57 58 /** 59 * Buffer write usage. 60 */ 61 enum write_t : uint64_t { 62 /** Buffer is writted to by the CPU. */ 63 CPU_WRITE = 1 << 2, 64 /** 65 * Buffer shall only be written to by trusted hardware. The definition of trusted hardware 66 * is platform specific, but this flag is reserved to prevent mapping this block into CPU 67 * writable memory resulting in bus fault. This flag can be used when buffer integrity must 68 * be protected. 69 */ 70 WRITE_PROTECTED = 1 << 3, 71 }; 72 73 enum : uint64_t { 74 /** 75 * Buffer usage bits reserved for the platform. We don't separately reserve read and 76 * write usages as platforms may have asymmetric distribution between them. 77 */ 78 PLATFORM_MASK = ~(CPU_READ | CPU_WRITE | READ_PROTECTED | WRITE_PROTECTED), 79 }; 80 81 /** Create a usage from separate consumer and producer usage mask. \deprecated */ C2MemoryUsageC2MemoryUsage82 inline C2MemoryUsage(uint64_t consumer, uint64_t producer) 83 : expected(consumer | producer) { } 84 C2MemoryUsageC2MemoryUsage85 inline explicit C2MemoryUsage(uint64_t expected_) 86 : expected(expected_) { } 87 88 uint64_t expected; // expected buffer usage 89 }; 90 91 /// @} 92 93 #endif // C2BUFFER_BASE_H_ 94 95