Evolution-x/hardware_interfaces
1
0
Fork 0
mirror of https://github.com/Evolution-X/hardware_interfaces synced 2026-02-01 11:36:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

android.hardware.media.bufferpool@1.0 HAL

Browse Source 
BufferPool HAL for allocating, deallocating, and recycling buffers
on behalf of media.stagefright.

Bug: 72651719
Change-Id: I30bf630e41de2c8718aaaf8cbf5ee3f48f2859bc
This commit is contained in:
Sungtak Lee
2018-01-25 15:07:40 -08:00
parent 6327b86696
commit 108a2fe68c
6 changed files with 331 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
media/bufferpool/1.0/Android.bp Normal file
View File

@@ -0,0 +1,26 @@
// This file is autogenerated by hidl-gen -Landroidbp.
hidl_interface {
name: "android.hardware.media.bufferpool@1.0",
root: "android.hardware",
vndk: {
enabled: true,
},
srcs: [
"types.hal",
"IAccessor.hal",
"IClientManager.hal",
"IConnection.hal",
],
interfaces: [
"android.hidl.base@1.0",
],
types: [
"Buffer",
"BufferStatus",
"BufferStatusMessage",
"ResultStatus",
],
gen_java: false,
}

68
media/bufferpool/1.0/IAccessor.hal Normal file
View File

@@ -0,0 +1,68 @@
/*
* Copyright (C) 2018 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.media.bufferpool@1.0;
import IConnection;
/**
* IAccessor creates IConnection which is used from IClientManager in order to
* use functionality of the specified buffer pool.
*/
interface IAccessor {
/**
* Registers a new client and creates IConnection to the buffer pool for
* the client. IConnection and FMQ are used by IClientManager in order to
* communicate with the buffer pool. Via FMQ IClientManager sends
* BufferStatusMesage(s) to the buffer pool.
*
* FMQ is used to send buffer ownership status changes to a buffer pool
* from a buffer pool client. A buffer pool synchronizes FMQ messages when
* there is a hidl request from the clients. Every client has its own
* connection and FMQ to communicate with the buffer pool. So sending an
* FMQ message on behalf of other clients is not possible.
*
* FMQ messages are sent when a buffer is acquired or released. Also, FMQ
* messages are sent when a buffer is transferred from a client to another
* client. FMQ has its own ID from a buffer pool. A client is specified
* with the ID.
*
* To transfer a buffer, a sender must send an FMQ message. The message
* must include a receiver's ID and a transaction ID. A receiver must send
* the transaction ID to fetch a buffer from a buffer pool. Since the
* sender already registered the receiver via an FMQ message, The buffer
* pool must verify the receiver with the transaction ID. In order to
* prevent faking a receiver, a connection to a buffer pool from client is
* made and kept private. Also part of transaction ID is a sender ID in
* order to prevent fake transactions from other clients. This must be
* verified with an FMQ message from a buffer pool.
*
* @return status The status of the call.
* OK - A connection is made successfully.
* NO_MEMORY - Memory allocation failure occurred.
* ALREADY_EXISTS - A connection was already made.
* CRITICAL_ERROR - Other errors.
* @return connection The IConnection have interfaces
* to get shared buffers from the buffer pool.
* @return connectionId Id of IConnection. The Id identifies
* sender and receiver in FMQ messages during buffer transfer.
* @return mqDesc FMQ descriptor. The descriptor can be used to
* send/receive FMQ messages.
*/
connect()
generates (ResultStatus status, IConnection connection,
int64_t connectionId, fmq_sync<BufferStatusMessage> mqDesc);
};

47
media/bufferpool/1.0/IClientManager.hal Normal file
View File

@@ -0,0 +1,47 @@
/*
* Copyright (C) 2018 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.media.bufferpool@1.0;
import IAccessor;
/**
* IClientManager manages IConnection(s) inside a process. A locally
* created IConnection represents a communication node(receiver) with the
* specified buffer pool(IAccessor).
* IConnection(s) are not exposed to other processes(IClientManager).
* IClientManager instance must be unique within a process.
*/
interface IClientManager {
/**
* Sets up a buffer receiving communication node for the specified
* buffer pool. A manager must create a IConnection to the buffer
* pool if it does not already have a connection.
*
* @param bufferPool a buffer pool which is specified with the IAccessor.
* The specified buffer pool is the owner of received buffers.
* @return status The status of the call.
* OK - A sender was set successfully.
* NO_MEMORY - Memory allocation failure occurred.
* ALREADY_EXISTS - A sender was registered already.
* CRITICAL_ERROR - Other errors.
* @return connectionId the Id of the communication node to the buffer pool.
* This id is used in FMQ to notify IAccessor that a buffer has been
* sent to that connection during transfers.
*/
registerSender(IAccessor bufferPool) generates
(ResultStatus status, int64_t connectionId);
};

43
media/bufferpool/1.0/IConnection.hal Normal file
View File

@@ -0,0 +1,43 @@
/*
* Copyright (C) 2018 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.media.bufferpool@1.0;
/**
* A connection to a buffer pool which handles requests from a buffer pool
* client. The connection must be made in order to receive buffers from
* other buffer pool clients.
*/
interface IConnection {
/**
* Retrieves a buffer using bufferId. The method must be called from
* receiving side of buffer during transferring only when the specified
* buffer is neither cached nor used. This fails if the specified
* transaction is not valid.
*
* @param transactionId Unique transaction id for buffer transferring.
* @param bufferId Id of the buffer to be fetched.
* @return status The status of the call.
* OK - A buffer was fetched successfully.
* NO_MEMORY - Memory allocation failure occurred.
* NOT_FOUND - A buffer was not found due to invalidation.
* CRITICAL_ERROR - Other errors.
* @return buffer The actual buffer which is specified with bufferId.
*/
fetch(uint64_t transactionId, uint32_t bufferId) generates
(ResultStatus status, Buffer buffer);
};

54
media/bufferpool/1.0/README.md Normal file
View File

@@ -0,0 +1,54 @@
1. Overview
A buffer pool enables processes to transfer buffers asynchronously.
Without a buffer pool, a process calls a synchronous method of the other
process and waits until the call finishes transferring a buffer. This adds
unwanted latency due to context switching. With help from a buffer pool, a
process can pass buffers asynchronously and reduce context switching latency.
Passing an interface and a handle adds extra latency also. To mitigate the
latency, passing IDs with local cache is used. For security concerns about
rogue clients, FMQ is used to communicate between a buffer pool and a client
process. FMQ is used to send buffer ownership change status from a client
process to a buffer pool. Except FMQ, a buffer pool does not use any shared
memory.
2. FMQ
FMQ is used to send buffer ownership status changes to a buffer pool from a
buffer pool client. A buffer pool synchronizes FMQ messages when there is a
hidl request from the clients. Every client has its own connection and FMQ
to communicate with the buffer pool. So sending an FMQ message on behalf of
other clients is not possible.
FMQ messages are sent when a buffer is acquired or released. Also, FMQ messages
are sent when a buffer is transferred from a client to another client. FMQ has
its own ID from a buffer pool. A client is specified with the ID.
To transfer a buffer, a sender must send an FMQ message. The message must
include a receiver's ID and a transaction ID. A receiver must send the
transaction ID to fetch a buffer from a buffer pool. Since the sender already
registered the receiver via an FMQ message, The buffer pool must verify the
receiver with the transaction ID. In order to prevent faking a receiver, a
connection to a buffer pool from client is made and kept privately. Also part of
transaction ID is a sender ID in order to prevent fake transactions from other
clients. This must be verified with an FMQ message from a buffer pool.
FMQ messages are defined in BufferStatus and BufferStatusMessage of 'types.hal'.
3. Interfaces
IConnection
A connection to a buffer pool from a buffer pool client. The connection
provides the functionalities to share buffers between buffer pool clients.
The connection must be unique for each client.
IAccessor
An accessor to a buffer pool which makes a connection to the buffer pool.
IAccesssor#connect creates an IConnection.
IClientManager
A manager of buffer pool clients and clients' connections to buffer pools. It
sets up a process to be a receiver of buffers from a buffer pool. The manager
is unique in a process.

93
media/bufferpool/1.0/types.hal Normal file
View File

@@ -0,0 +1,93 @@
/*
* Copyright (C) 2018 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.media.bufferpool@1.0;
enum ResultStatus : int32_t {
OK = 0,
NO_MEMORY = 1,
ALREADY_EXISTS = 2,
NOT_FOUND = 3,
CRITICAL_ERROR = 4,
};
/**
* Generic buffer for fast recycling for media/stagefright.
*
* During media pipeline buffer references are created, shared and
* destroyed frequently. The underlying buffers are allocated on demand
* by a buffer pool, and are recycled to the buffer pool when they are
* no longer referenced by the clients.
*
* E.g. ion or gralloc buffer
*/
struct Buffer {
uint32_t id;
handle buffer;
};
/**
* Buffer ownership status for the specified client.
* Buffer transfer status for the specified buffer transafer transaction.
* BufferStatus is posted along with BufferStatusMessage from a client to
* the buffer pool for synchronization after status change.
*/
enum BufferStatus : int32_t {
/** No longer used by the specified client. */
NOT_USED = 0,
/** Buffer is acquired by the specified client. */
USED = 1,
/** Buffer is sent by the specified client. */
TRANSFER_TO = 2,
/** Buffer transfer is acked by the receiver client. */
TRANSFER_FROM = 3,
/** Buffer transfer is timed out by receiver client. */
TRANSFER_TIMEOUT = 4,
/** Buffer transfer is not acked by the receiver. */
TRANSFER_LOST = 5,
/** Buffer fetch request from the client. */
TRANSFER_FETCH = 6,
/** Buffer transaction succeeded. */
TRANSFER_OK = 7,
/** Buffer transaction failure. */
TRANSFER_ERROR = 8,
};
/**
* Buffer ownership status change message. This message is
* sent via fmq to the buffer pool from client processes.
*/
struct BufferStatusMessage {
/**
* Transaction Id = (SenderId : sender local transaction Id)
* Transaction Id is created from sender and posted via fmq within
* TRANSFER_TO message.
*/
uint64_t transactionId;
uint32_t bufferId;
BufferStatus newStatus;
/** Used by the buffer pool. not by client. */
int64_t connectionId;
/** Valid only when TRANSFER_TO is posted. */
int64_t targetConnectionId;
/**
* Used by the buffer pool, not by client.
* Monotonic timestamp in Us since fixed point in time as decided
* by the sender of the message
*/
int64_t timestampUs;
};