源碼位置：
/hardware/interfaces/graphics/mapper/4.0/IMapper.hal
package android.hardware.graphics.mapper@4.0;
import android.hardware.graphics.common@1.2::BufferUsage;
import android.hardware.graphics.common@1.2::PixelFormat;
import android.hardware.graphics.common@1.2::Rect;
interface IMapper {
// BufferDescriptorInfo用於描述圖形buffer的屬性(寬、高、格式...)
struct BufferDescriptorInfo {
/**
* The name of the buffer. Useful for debugging/tracing.
* buffer的名字，用於debugging/tracing
*/
string name;
/**
* The width specifies how many columns of pixels must be in the
* allocated buffer, but does not necessarily represent the offset in
* columns between the same column in adjacent rows. The rows may be
* padded.
* width說明了分配的buffer中有多少個像素列，但它並不表示相鄰行的同一列元素的偏移量。
* 為了字節對齊,width可能並不是實際的大小，參考stride
*/
uint32_t width;
/**
* The height specifies how many rows of pixels must be in the
* allocated buffer.
* height說明了分配的buffer中有多少像素行
*/
uint32_t height;
/**
* The number of image layers that must be in the allocated buffer.
* 必須在分配的緩沖區中的圖像層數。
*/
uint32_t layerCount;
/**
* Buffer pixel format.
* 像素格式 (參見/frameworks/native/libs/ui/include/ui/PixelFormat.h中的定義)
*/
PixelFormat format;
/**
* Buffer usage mask; valid flags can be found in the definition of
* BufferUsage.
* buffer使用方式的標志位(參見/frameworks/native/libs/ui/include/ui/GraphicBuffer.h的定義)。
*/
bitfield<BufferUsage> usage;
/**
* The size in bytes of the reserved region associated with the buffer.
* See getReservedRegion for more information.
* 與緩沖區關聯的保留區域的大小（字節）。
*/
uint64_t reservedSize;
};
struct Rect {
int32_t left;
int32_t top;
int32_t width;
int32_t height;
};
/**
* Creates a buffer descriptor. The descriptor can be used with IAllocator
* to allocate buffers.
* 創建一個 buffer descriptor，這個descriptor可以用於IAllocator分配buffer
*
* Since the buffer descriptor fully describes a buffer, any device
* dependent or device independent checks must be performed here whenever
* possible.
*
* 由於buffer descriptor完全描述了一個緩沖區，因此必須盡可能在此處執行任何與設備相關或與設備無關的檢查。
*
* When layered buffers are not supported, 當分層緩沖區不支持時
* this function must return `UNSUPPORTED` if `description.layers` is great than 1.
* This function may return `UNSUPPORTED` if `description.reservedSize` is larger than a page.
*
* @param description Attributes of the descriptor.
* @return error Error status of the call, which may be
* - `NONE` upon success. 成功
* - `BAD_VALUE` if any of the specified attributes are invalid or
* inconsistent. 指定的屬性非法或不一致
* - `NO_RESOURCES` if the creation cannot be fullfilled due to
* unavailability of resources. 由於資源不可用而無法完成創建
* - `UNSUPPORTED` when any of the specified attributes are not
* supported. 不支持指定的屬性
* @return descriptor Newly created buffer descriptor.
*
* 返回新創建的BufferDescriptor(定義typedef vec<uint8_t> BufferDescriptor;)
*/
* 主要完成兩個工作：
* 1. 檢查參數的合法性(設備是否支持)；
* 2. 把BufferDescriptorInfo這個結構體變量進行重新的包裝，本質就是轉化為byte stream，這樣可以傳遞給IAllocator
createDescriptor(BufferDescriptorInfo description)
generates (Error error,
BufferDescriptor descriptor);
/**
* Imports a raw buffer handle to create an imported buffer handle for use
* with the rest of the mapper or with other in-process libraries.
*
* 把raw buffer handle轉為imported buffer handle，這樣就可以在進程使用了
*
* A buffer handle is considered raw when it is cloned (e.g., with
* `native_handle_clone()`) from another buffer handle locally, or when it
* is received from another HAL server/client or another process. A raw
* buffer handle must not be used to access the underlying graphic
* buffer. It must be imported to create an imported handle first.
*
* buffer handle被視作raw : 1. 從本地buffer handle做native_handle_clone
* 2. 接收到的來自另一個HAL server/client或其它進程的buffer handle
*
* This function must at least validate the raw handle before creating the
* imported handle. It must also support importing the same raw handle
* multiple times to create multiple imported handles. The imported handle
* must be considered valid everywhere in the process, including in
* another instance of the mapper.
*
* 1. 在創建imported handle前，這個函數必須對raw handle進行raw handle
* 2. 這個函數必須支持對同一個raw handle進行多次import來產生多個imported handles
* 3. imported handle在進程內的任何地方或對於不同的mapper對象都是合法有效的
*
* Because of passthrough HALs, a raw buffer handle received from a HAL
* may actually have been imported in the process. importBuffer() must treat
* such a handle as if it is raw and must not return `BAD_BUFFER`. The
* returned handle is independent from the input handle as usual, and
* freeBuffer() must be called on it when it is no longer needed.
*
* 由於passthrough HAL，從HAL接收的raw buffer handle實際上可能已在該進程中imported。
* importBuffer()必須將此類句柄視為原始句柄，並且不能返回'BAD_BUFFER'。
* 返回的句柄獨立於輸入句柄，當不再需要時，必須對其調用freeBuffer()。
*
* @param rawHandle Raw buffer handle to import.
* @return error Error status of the call, which may be
* - `NONE` upon success. 成功
* - `BAD_BUFFER` if the raw handle is invalid. 參數無效/非法
* - `NO_RESOURCES` if the raw handle cannot be imported due to
* unavailability of resources. 資源不可用導致import失敗
* @return buffer Imported buffer handle that has the type
* `buffer_handle_t` which is a handle type.
*/
importBuffer(handle rawHandle) generates (Error error, pointer buffer);
/**
* Frees a buffer handle. Buffer handles returned by importBuffer() must be
* freed with this function when no longer needed.
*
* importBuffer()返回的buffer handle不再使用后必須調用freeBuffer()釋放
*
* This function must free up all resources allocated by importBuffer() for
* the imported handle. For example, if the imported handle was created
* with `native_handle_create()`, this function must call
* `native_handle_close()` and `native_handle_delete()`.
*
* 釋放掉所有importBuffer中分配的資源
*
* @param buffer Imported buffer handle.
* @return error Error status of the call, which may be
* - `NONE` upon success.
* - `BAD_BUFFER` if the buffer is invalid.
*/
freeBuffer(pointer buffer) generates (Error error);
/**
* Validates that the buffer can be safely accessed by a caller who assumes
* the specified @p description and @p stride. This must at least validate
* that the buffer size is large enough. Validating the buffer against
* individual buffer attributes is optional.
*
* 驗證buffer是否可以被調用者已指定的description&stride進行安全訪問。
* 至少要驗證buffer size是足夠的。
*
* @param buffer Buffer to validate against. 驗證的buffer
* @param description Attributes of the buffer. buffer屬性
* @param stride Stride returned by IAllocator::allocate(). 步長
* @return error Error status of the call, which may be
* - `NONE` upon success.
* - `BAD_BUFFER` if the buffer is invalid.
* - `BAD_VALUE` if the buffer cannot be safely accessed.
*/
validateBufferSize(pointer buffer,
BufferDescriptorInfo description,
uint32_t stride)
generates (Error error);
/**
* Calculates the transport size of a buffer. An imported buffer handle is a
* raw buffer handle with the process-local runtime data appended. This
* function, for example, allows a caller to omit the process-local runtime
* data at the tail when serializing the imported buffer handle.
*
* 計算buffer傳輸數據的大小。imported buffer handle是在raw buffer handle基礎上附加了
* 進程本地運行時數據。例如，此函數允許調用方忽略進程本地運行時
* 序列化導入的緩沖區句柄時尾部的數據。
*
* Note that a client might or might not omit the process-local runtime data
* when sending an imported buffer handle. The mapper must support both
* cases on the receiving end.
*
* @param buffer Buffer to get the transport size from.
* @return error Error status of the call, which may be
* - `NONE` upon success.
* - `BAD_BUFFER` if the buffer is invalid.
* @return numFds The number of file descriptors needed for transport.需要傳遞的文件描述符個數
* @return numInts The number of integers needed for transport.需要傳遞的整數個數
*/
getTransportSize(pointer buffer)
generates (Error error,
uint32_t numFds,
uint32_t numInts);
/**
* Locks the given buffer for the specified CPU usage.
* 鎖定指定CPU usage的緩沖區。
* Locking the same buffer simultaneously from multiple threads is
* permitted, but if any of the threads attempt to lock the buffer for
* writing, the behavior is undefined, except that it must not cause
* process termination or block the client indefinitely. Leaving the
* buffer content in an indeterminate state or returning an error are both
* acceptable.
*
* 允許多個線程同時lock同一個buffer
* 如果任意個線程試圖lock后寫buffer,這個行為沒有定義
* 但它不能導致進程終止或無限期地阻止客戶端。
* 將緩沖區內容保持在不確定狀態或返回錯誤都是可以接受的。
*
* 1D buffers (width = size in bytes, height = 1, pixel_format = BLOB) must
* "lock in place". The buffers must be directly accessible via mapping.
*
* The client must not modify the content of the buffer outside of
* @p accessRegion, and the device need not guarantee that content outside
* of @p accessRegion is valid for reading. The result of reading or writing
* outside of @p accessRegion is undefined, except that it must not cause
* process termination.
*
* client禁止調整accessRegion以外的內容，該設備無需保證accessRegion之外的內容可以有效讀取。
* 在accessRegion之外讀取或寫入的結果未定義，但它不得導致進程終止。
*
* An accessRegion of all-zeros means the entire buffer. That is, it is
* equivalent to '(0,0)-(buffer width, buffer height)'.
*
* accessRegion(0,0,0,0)全是0，意味是整個buffer (0,0,width,height)
*
* This function can lock both single-planar and multi-planar formats. The caller
* should use get() to get information about the buffer they are locking.
* get() can be used to get information about the planes, offsets, stride,
* etc.
*
* This function must also work on buffers with
* `AHARDWAREBUFFER_FORMAT_Y8Cb8Cr8_*` if supported by the device, as well
* as with any other formats requested by multimedia codecs when they are
* configured with a flexible-YUV-compatible color format.
*
* 如果設備支持，此功能還必須適用於“AHARDWAREBUFFER_FORMAT_Y8Cb8Cr8_*”格式的緩沖區，
* 以及多媒體編解碼器配置靈活的YUV兼容顏色格式時所需的任何其他格式。
*
* On success, @p data must be filled with a pointer to the locked buffer
* memory. This address will represent the top-left corner of the entire
* buffer, even if @p accessRegion does not begin at the top-left corner.
*
* The locked buffer must adhere to the format requested at allocation time
* in the BufferDescriptorInfo.
*
* 鎖定的緩沖區必須符合分配時請求的格式BufferDescriptorInfo。
*
* @param buffer Buffer to lock.
* @param cpuUsage CPU usage flags to request. See +ndk
* libnativewindow#AHardwareBuffer_UsageFlags for possible values.
* @param accessRegion Portion of the buffer that the client intends to
* access. 客戶端打算訪問的緩沖區部分。
* @param acquireFence Handle containing a file descriptor referring to a
* sync fence object, which will be signaled when it is safe for the
* mapper to lock the buffer. @p acquireFence may be an empty fence if
* it is already safe to lock.
* @return error Error status of the call, which may be
* - `NONE` upon success.
* - `BAD_BUFFER` if the buffer is invalid or is incompatible with this
* function.
* - `BAD_VALUE` if @p cpuUsage is 0, contains non-CPU usage flags, or
* is incompatible with the buffer. Also if the @p accessRegion is
* outside the bounds of the buffer or the accessRegion is invalid.
* - `NO_RESOURCES` if the buffer cannot be locked at this time. Note
* that locking may succeed at a later time.
* @return data CPU-accessible pointer to the buffer data. CPU可訪問的buffer數據地址
*/
lock(pointer buffer,
uint64_t cpuUsage,
Rect accessRegion,
handle acquireFence)
generates (Error error,
pointer data);
/**
* Unlocks a buffer to indicate all CPU accesses to the buffer have
* completed.
* 解鎖緩沖區以指示對緩沖區的所有CPU訪問都已完成
*
* @param buffer Buffer to unlock.
* @return error Error status of the call, which may be
* - `NONE` upon success.
* - `BAD_BUFFER` if the buffer is invalid or not locked.
* @return releaseFence Handle containing a file descriptor referring to a
* sync fence object. The sync fence object will be signaled when the
* mapper has completed any pending work. @p releaseFence may be an
* empty fence.
*/
unlock(pointer buffer) generates (Error error, handle releaseFence);
/**
* Flushes the contents of a locked buffer. 刷新鎖定緩沖區的內容。
*
* This function flushes the CPUs caches for the range of all the buffer's
* planes and metadata. This should behave similarly to unlock() except the
* buffer should remain mapped to the CPU.
*
* 此函數用於刷新所有緩沖區平面和元數據范圍的CPU緩存。
* 這應該類似於unlock（），只是緩沖區應該保持映射到CPU
*
* The client is still responsible for calling unlock() when it is done
* with all CPU accesses to the buffer.
*
* 完成對緩沖區的所有CPU訪問后，客戶端仍負責調用unlock()。
*
* If non-CPU blocks are simultaneously writing the buffer, the locked
* copy should still be flushed but what happens is undefined except that
* it should not cause any crashes.
8
* 如果非CPU塊同時寫入緩沖區，則仍應刷新鎖定的副本，但所發生的情況尚未定義，除非不會導致任何崩潰。
*
* @param buffer Buffer to flush.
* @return error Error status of the call, which may be
* - `NONE` upon success.
* - `BAD_BUFFER` if the buffer is invalid or not locked.
* @return releaseFence Handle containing a file descriptor referring to a
* sync fence object. The sync fence object will be signaled when the
* mapper has completed any pending work. @p releaseFence may be an
* empty fence.
*/
flushLockedBuffer(pointer buffer) generates (Error error, handle releaseFence);
/**
* Rereads the contents of a locked buffer. 重新讀取鎖定緩沖區的內容
*
* This should fetch the most recent copy of the locked buffer. 這將獲取鎖定緩沖區的最新副本。
*
* It may reread locked copies of the buffer in other processes. 它可能會在其他進程中重新讀取緩沖區的鎖定副本
*
* The client is still responsible for calling unlock() when it is done
* with all CPU accesses to the buffer.
*
* @param buffer Buffer to reread.
* @return error Error status of the call, which may be
* - `NONE` upon success.
* - `BAD_BUFFER` if the buffer is invalid or not locked.
* - `NO_RESOURCES` if the buffer cannot be reread at this time. Note
* that rereading may succeed at a later time.
*/
rereadLockedBuffer(pointer buffer) generates(Error error);
/**
* Test whether the given BufferDescriptorInfo is allocatable.
*
* 測試給定的BufferDescriptorInfo是否可分配。
*
* If this function returns true, it means that a buffer with the given
* description can be allocated on this implementation, unless resource
* exhaustion occurs. If this function returns false, it means that the
* allocation of the given description will never succeed.
*
* @param description the description of the buffer
* @return supported whether the description is supported
*/
isSupported(BufferDescriptorInfo description)
generates (Error error,
bool supported);
/**
* Description for get(...), set(...) and getFromBufferDescriptorInfo(...)
*
* ------------ Overview -----------------------------------
* Gralloc 4 adds support for getting and setting buffer metadata on a buffer.
*
* To get buffer metadata, the client passes in a buffer handle and a token that
* represents the type of buffer metadata they would like to get. IMapper returns
* a byte stream that contains the buffer metadata. To set the buffer metadata, the
* client passes in a buffer handle and a token that represents the type of buffer
* metadata they would like to set and a byte stream that contains the buffer metadata
* they are setting.
*
* Buffer metadata is global for a buffer. When the metadata is set on the buffer
* in a process, the updated metadata should be available to all other processes.
* Please see "Storing and Propagating Metadata" below for more details.
*
* The getter and setter functions have been optimized for easy vendor extension.
* They do not require a formal HIDL extension to add support for getting and setting
* vendor defined buffer metadata. In order to allow easy extension, the types used
* here are not typical HIDL types. See "Buffer Metadata Token" and
* "Buffer Metadata Stream" below for more details.
*
* ------------ Storing and Propagating Metadata -----------
* Buffer metadata must be global. Any changes to the metadata must be propagated
* to all other processes immediately. Vendors may chose how they would like support
* this functionality.
*
* We recommend supporting this functionality by allocating an extra page of shared
* memory and storing it in the buffer's native_handle_t. The buffer metadata can
* be stored in the extra page of shared memory. Set operations are automatically
* propagated to all other processes.
*
* ------------ Buffer Metadata Synchronization ------------
* There are no explicit buffer metadata synchronization primitives. Many devices
* before gralloc 4 already support getting and setting of global buffer metadata
* with no explicit synchronization primitives. Adding synchronization primitives
* would just add unnecessary complexity.
*
* The general rule is if a process has permission to write to a buffer, they
* have permission to write to the buffer's metadata. If a process has permission
* to read from a buffer, they have permission to read the buffer's metadata.
*
* There is one exception to this rule. Fences CANNOT be used to protect a buffer's
* metadata. A process should finish writing to a buffer's metadata before
* sending the buffer to another process that will read or write to the buffer.
* This exception is needed because sometimes userspace needs to read the
* buffer's metadata before the buffer's contents are ready.
*
* As a simple example: an app renders to a buffer and then displays the buffer.
* In this example when the app renders to the buffer, both the buffer and its
* metadata need to be updated. The app's process queues up its work on the GPU
* and gets back an acquire fence. The app's process must update the buffer's
* metadata before enqueuing the buffer to SurfaceFlinger. The app process CANNOT
* update the buffer's metadata after enqueuing the buffer. When HardwareComposer
* receives the buffer, it is immediately safe to read the buffer's metadata
* and use it to program the display driver. To read the buffer's contents,
* display driver must still wait on the acquire fence.
*
* ------------ Buffer Metadata Token ----------------------
* In order to allow arbitrary vendor defined metadata, we could not use a
* HIDL enum as the buffer metadata token. Extending a HIDL enum requires a full
* HIDL extension. We also could not use a simple non-HIDL enum because vendor
* defined enums from different vendors could collide. Instead we have defined
* a struct that has a string representing the enum type and an int that
* represents the enum value. The string protects different enum values from
* colliding.
*
* The token struct (MetadataType) is defined as a HIDL struct since it
* is passed into a HIDL function. The standard buffer metadata types are NOT
* defined as a HIDL enum because it would have required a new IMapper version
* just to add future standard buffer metadata types. By putting the enum in the
* stable AIDL (hardware/interfaces/graphics/common/aidl/android/hardware/
* graphics/common/StandardMetadataType.aidl), vendors will be able to optionally
* choose to support future standard buffer metadata types without upgrading
* HIDL versions. For more information see the description of "struct MetadataType".
*
* ------------ Buffer Metadata Stream ---------------------
* The buffer metadata is get and set as a byte stream (vec<uint8_t>). By getting
* and setting buffer metadata as a byte stream, vendors can use the standard
* getters and setter functions defined here. Vendors do NOT need to add their own
* getters and setter functions for each new type of buffer metadata.
*
* Converting buffer metadata into a byte stream can be non-trivial. For the standard
* buffer metadata types defined in StandardMetadataType.aidl, there are also
* support functions that will encode the buffer metadata into a byte stream
* and decode the buffer metadata from a byte stream. We STRONGLY recommend using
* these support functions. The framework will use them when getting and setting
* metadata. The support functions are defined in
* frameworks/native/libs/gralloc/types/include/gralloctypes/Gralloc4.h.
*/
/**
* MetadataType represents the different types of buffer metadata that could be
* associated with a buffer. It is used by IMapper to help get and set buffer metadata
* on the buffer's native handle.
*
* Standard buffer metadata will have the name field set to
* "android.hardware.graphics.common.StandardMetadataType" and will contain values
* from StandardMetadataType.aidl.
*
* This struct should be "extended" by devices that use a proprietary or non-standard
* buffer metadata. To extend the struct, first create a custom @VendorStability vendor
* AIDL interface that defines the new type(s) you would like to support. Set the
* struct's name field to the custom aidl interface's name
* (eg. "vendor.mycompanyname.graphics.common.MetadataType"). Set the struct's value
* field to the custom @VendorStabilty vendor AIDL interface.
*
* Each company should create their own StandardMetadataType.aidl extension. The name
* field prevents values from different companies from colliding.
*/
struct MetadataType {
string name;
int64_t value;
};
/**
* Gets the buffer metadata for a given MetadataType.
*
* Buffer metadata can be changed after allocation so clients should avoid "caching"
* the buffer metadata. For example, if the video resolution changes and the buffers
* are not reallocated, several buffer metadata values may change without warning.
* Clients should not expect the values to be constant. They should requery them every
* frame. The only exception is buffer metadata that is determined at allocation
* time. For StandardMetadataType values, only BUFFER_ID, NAME, WIDTH,
* HEIGHT, LAYER_COUNT, PIXEL_FORMAT_REQUESTED and USAGE are safe to cache because
* they are determined at allocation time.
*
* @param buffer Buffer containing desired metadata
* @param metadataType MetadataType for the metadata value being queried
* @return error Error status of the call, which may be
* - `NONE` upon success.
* - `BAD_BUFFER` if the raw handle is invalid.
* - `NO_RESOURCES` if the get cannot be fullfilled due to unavailability of
* resources.
* - `UNSUPPORTED` when metadataType is unknown/unsupported.
* IMapper must support getting all StandardMetadataType.aidl values defined
* at the time the device first launches.
* @return metadata Vector of bytes representing the buffer metadata associated with
* the MetadataType.
*/
get(pointer buffer, MetadataType metadataType)
generates (Error error,
vec<uint8_t> metadata);
/**
* Sets the global value for a given MetadataType.
*
* Metadata fields are not required to be settable. This function can
* return Error::UNSUPPORTED whenever it doesn't support setting a
* particular Metadata field.
*
* The framework may attempt to set the following StandardMetadataType
* values: DATASPACE, SMPTE2086, CTA861_3, SMPTE2094_40 and BLEND_MODE.
* We strongly encourage everyone to support setting as many of those fields as
* possible. If a device's Composer implementation supports a field, it should be
* supported here. Over time these metadata fields will be moved out of
* Composer/BufferQueue/etc. and into the buffer's Metadata fields.
* If a device's IMapper doesn't support setting those Metadata fields,
* eventually the device may not longer be able to support these fields.
*
* @param buffer Buffer receiving desired metadata
* @param metadataType MetadataType for the metadata value being set
* @param metadata Vector of bytes representing the value associated with
* @return error Error status of the call, which may be
* - `NONE` upon success.
* - `BAD_BUFFER` if the raw handle is invalid.
* - `BAD_VALUE` when the field is constant and can never be set (such as
* BUFFER_ID, NAME, WIDTH, HEIGHT, LAYER_COUNT, PIXEL_FORMAT_REQUESTED and
* USAGE)
* - `NO_RESOURCES` if the set cannot be fullfilled due to unavailability of
* resources.
* - `UNSUPPORTED` when metadataType is unknown/unsupported or setting
* it is unsupported. Unsupported should also be returned if the metadata
* is malformed.
*/
set(pointer buffer, MetadataType metadataType, vec<uint8_t> metadata)
generates (Error error);
/**
* Given a BufferDescriptorInfo, gets the starting value of a given
* MetadataType. This can be used to query basic information about a buffer
* before the buffer is allocated.
*
* @param description Attributes of the descriptor.
* @param metadataType MetadataType for the metadata value being queried
* @return error Error status of the call, which may be
* - `NONE` upon success.
* - `BAD_VALUE` if any of the specified BufferDescriptorInfo attributes
* are invalid.
* - `NO_RESOURCES` if the get cannot be fullfilled due to unavailability of
* resources.
* - `UNSUPPORTED` when any of the description attributes are unsupported or
* if the metadataType is unknown/unsupported. This should also be
* returned if the requested metadata is not defined until a buffer has been
* allocated.
* @return metadata Vector of bytes representing the value associated with
* the MetadataType value.
*/
getFromBufferDescriptorInfo(BufferDescriptorInfo description,
MetadataType metadataType)
generates (Error error,
vec<uint8_t> metadata);
struct MetadataTypeDescription {
MetadataType metadataType;
/**
* description should contain a string representation of the MetadataType.
*
* For example: "MyExampleMetadataType is a 64-bit timestamp in nanoseconds
* that indicates when a buffer is decoded. It is set by the media HAL after
* a buffer is decoded. It is used by the display HAL for hardware
* synchronization".
*
* This field is required for any non-StandardMetadataTypes.
*/
string description;
/**
* isGettable represents if the MetadataType can be get.
*/
bool isGettable;
/**
* isSettable represents if the MetadataType can be set.
*/
bool isSettable;
};
/**
* Lists all the MetadataTypes supported by IMapper as well as a description
* of each supported MetadataType. For StandardMetadataTypes, the description
* string can be left empty.
*
* @return error Error status of the call, which may be
* - `NONE` upon success.
* - `NO_RESOURCES` if the get cannot be fullfilled due to unavailability of
* resources.
* @return descriptions Vector of MetadataTypeDescriptions that represent the
* MetadataTypes supported by the device.
*/
listSupportedMetadataTypes()
generates (Error error, vec<MetadataTypeDescription> descriptions);
struct MetadataDump {
/**
* The type of metadata being dumped.
*/
MetadataType metadataType;
/**
* The byte stream representation of the metadata. If the metadata is not
* gettable, the vector must be empty.
*/
vec<uint8_t> metadata; //字節流
};
struct BufferDump {
/**
* A vector of all the metadata that is being dumped for a particular buffer.
*/
vec<MetadataDump> metadataDump;
};
/**
* Dumps a buffer's metadata. 打印buffer的metadata信息
*
* @param buffer Buffer that is being dumped
* @return error Error status of the call, which may be
* - `NONE` upon success.
* - `BAD_BUFFER` if the raw handle is invalid.
* - `NO_RESOURCES` if the get cannot be fullfilled due to unavailability of
* resources.
* @return bufferDump Struct representing the metadata being dumped
*/
dumpBuffer(pointer buffer)
generates (Error error, BufferDump bufferDump);
/**
* Dumps the metadata for all the buffers in the current process.
*
* @return error Error status of the call, which may be
* - `NONE` upon success.
* - `NO_RESOURCES` if the get cannot be fullfilled due to unavailability of
* resources.
* @return bufferDumps Vector of structs representing the buffers being dumped
*/
dumpBuffers()
generates (Error error, vec<BufferDump> bufferDumps);
/**
* Returns the region of shared memory associated with the buffer that is
* reserved for client use.
*
* 返回與這個buffer相關的保留給client使用的共享內存區域
*
* The shared memory may be allocated from any shared memory allocator.
* The shared memory must be CPU-accessible and virtually contiguous. The
* starting address must be word-aligned.
*
* 共享內存可以從任何共享內存分配器分配。
* 共享內存必須是CPU可訪問且虛擬地址連續。起始地址必須是字對齊的。
*
* This function may only be called after importBuffer() has been called by the
* client. The reserved region must remain accessible until freeBuffer() has
* been called. After freeBuffer() has been called, the client must not access
* the reserved region.
*
* 這個函數只有在importBuffer()被調用后才可使用。
* 保留的內存區域在freeBuffer()被調用前都是可訪問的。
* freeBuffer()被調用后，client就無法再去訪問這塊內存區域了
*
* This reserved memory may be used in future versions of Android to
* help clients implement backwards compatible features without requiring
* IAllocator/IMapper updates.
*
* 這些保留內存可能會在未來版本的Android中使用，
* 以幫助客戶端實現向后兼容的功能，而無需iLocator/IMapper更新。
*
* @param buffer Imported buffer handle.
* @return error Error status of the call, which may be
* - `NONE` upon success.
* - `BAD_BUFFER` if the buffer is invalid.
* @return reservedRegion CPU-accessible pointer to the reserved region
* @return reservedSize the size of the reservedRegion that was requested
* in the BufferDescriptorInfo.
*/
getReservedRegion(pointer buffer)
generates (Error error,
pointer reservedRegion,
uint64_t reservedSize);
};