summaryrefslogtreecommitdiffstats
path: root/media
diff options
context:
space:
mode:
authorSungtak Lee2018-01-25 17:07:40 -0600
committerSungtak Lee2018-01-29 17:49:41 -0600
commit108a2fe68cf68b76207b540457ab4e8bd97f5a76 (patch)
tree2b4b156bcba06974fd422ce9308d5b2b694a2385 /media
parent6327b866963d7bea96edf02332f9b24267b53e5f (diff)
downloadplatform-hardware-interfaces-108a2fe68cf68b76207b540457ab4e8bd97f5a76.tar.gz
platform-hardware-interfaces-108a2fe68cf68b76207b540457ab4e8bd97f5a76.tar.xz
platform-hardware-interfaces-108a2fe68cf68b76207b540457ab4e8bd97f5a76.zip
android.hardware.media.bufferpool@1.0 HAL
BufferPool HAL for allocating, deallocating, and recycling buffers on behalf of media.stagefright. Bug: 72651719 Change-Id: I30bf630e41de2c8718aaaf8cbf5ee3f48f2859bc
Diffstat (limited to 'media')
-rw-r--r--media/bufferpool/1.0/Android.bp26
-rw-r--r--media/bufferpool/1.0/IAccessor.hal68
-rw-r--r--media/bufferpool/1.0/IClientManager.hal47
-rw-r--r--media/bufferpool/1.0/IConnection.hal43
-rw-r--r--media/bufferpool/1.0/README.md54
-rw-r--r--media/bufferpool/1.0/types.hal93
6 files changed, 331 insertions, 0 deletions
diff --git a/media/bufferpool/1.0/Android.bp b/media/bufferpool/1.0/Android.bp
new file mode 100644
index 00000000..986da8a4
--- /dev/null
+++ b/media/bufferpool/1.0/Android.bp
@@ -0,0 +1,26 @@
1// This file is autogenerated by hidl-gen -Landroidbp.
2
3hidl_interface {
4 name: "android.hardware.media.bufferpool@1.0",
5 root: "android.hardware",
6 vndk: {
7 enabled: true,
8 },
9 srcs: [
10 "types.hal",
11 "IAccessor.hal",
12 "IClientManager.hal",
13 "IConnection.hal",
14 ],
15 interfaces: [
16 "android.hidl.base@1.0",
17 ],
18 types: [
19 "Buffer",
20 "BufferStatus",
21 "BufferStatusMessage",
22 "ResultStatus",
23 ],
24 gen_java: false,
25}
26
diff --git a/media/bufferpool/1.0/IAccessor.hal b/media/bufferpool/1.0/IAccessor.hal
new file mode 100644
index 00000000..5b5aec04
--- /dev/null
+++ b/media/bufferpool/1.0/IAccessor.hal
@@ -0,0 +1,68 @@
1/*
2 * Copyright (C) 2018 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
17package android.hardware.media.bufferpool@1.0;
18
19import IConnection;
20/**
21 * IAccessor creates IConnection which is used from IClientManager in order to
22 * use functionality of the specified buffer pool.
23 */
24interface IAccessor {
25
26 /**
27 * Registers a new client and creates IConnection to the buffer pool for
28 * the client. IConnection and FMQ are used by IClientManager in order to
29 * communicate with the buffer pool. Via FMQ IClientManager sends
30 * BufferStatusMesage(s) to the buffer pool.
31 *
32 * FMQ is used to send buffer ownership status changes to a buffer pool
33 * from a buffer pool client. A buffer pool synchronizes FMQ messages when
34 * there is a hidl request from the clients. Every client has its own
35 * connection and FMQ to communicate with the buffer pool. So sending an
36 * FMQ message on behalf of other clients is not possible.
37 *
38 * FMQ messages are sent when a buffer is acquired or released. Also, FMQ
39 * messages are sent when a buffer is transferred from a client to another
40 * client. FMQ has its own ID from a buffer pool. A client is specified
41 * with the ID.
42 *
43 * To transfer a buffer, a sender must send an FMQ message. The message
44 * must include a receiver's ID and a transaction ID. A receiver must send
45 * the transaction ID to fetch a buffer from a buffer pool. Since the
46 * sender already registered the receiver via an FMQ message, The buffer
47 * pool must verify the receiver with the transaction ID. In order to
48 * prevent faking a receiver, a connection to a buffer pool from client is
49 * made and kept private. Also part of transaction ID is a sender ID in
50 * order to prevent fake transactions from other clients. This must be
51 * verified with an FMQ message from a buffer pool.
52 *
53 * @return status The status of the call.
54 * OK - A connection is made successfully.
55 * NO_MEMORY - Memory allocation failure occurred.
56 * ALREADY_EXISTS - A connection was already made.
57 * CRITICAL_ERROR - Other errors.
58 * @return connection The IConnection have interfaces
59 * to get shared buffers from the buffer pool.
60 * @return connectionId Id of IConnection. The Id identifies
61 * sender and receiver in FMQ messages during buffer transfer.
62 * @return mqDesc FMQ descriptor. The descriptor can be used to
63 * send/receive FMQ messages.
64 */
65 connect()
66 generates (ResultStatus status, IConnection connection,
67 int64_t connectionId, fmq_sync<BufferStatusMessage> mqDesc);
68};
diff --git a/media/bufferpool/1.0/IClientManager.hal b/media/bufferpool/1.0/IClientManager.hal
new file mode 100644
index 00000000..e1e8f95b
--- /dev/null
+++ b/media/bufferpool/1.0/IClientManager.hal
@@ -0,0 +1,47 @@
1/*
2 * Copyright (C) 2018 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
17package android.hardware.media.bufferpool@1.0;
18
19import IAccessor;
20/**
21 * IClientManager manages IConnection(s) inside a process. A locally
22 * created IConnection represents a communication node(receiver) with the
23 * specified buffer pool(IAccessor).
24 * IConnection(s) are not exposed to other processes(IClientManager).
25 * IClientManager instance must be unique within a process.
26 */
27interface IClientManager {
28
29 /**
30 * Sets up a buffer receiving communication node for the specified
31 * buffer pool. A manager must create a IConnection to the buffer
32 * pool if it does not already have a connection.
33 *
34 * @param bufferPool a buffer pool which is specified with the IAccessor.
35 * The specified buffer pool is the owner of received buffers.
36 * @return status The status of the call.
37 * OK - A sender was set successfully.
38 * NO_MEMORY - Memory allocation failure occurred.
39 * ALREADY_EXISTS - A sender was registered already.
40 * CRITICAL_ERROR - Other errors.
41 * @return connectionId the Id of the communication node to the buffer pool.
42 * This id is used in FMQ to notify IAccessor that a buffer has been
43 * sent to that connection during transfers.
44 */
45 registerSender(IAccessor bufferPool) generates
46 (ResultStatus status, int64_t connectionId);
47};
diff --git a/media/bufferpool/1.0/IConnection.hal b/media/bufferpool/1.0/IConnection.hal
new file mode 100644
index 00000000..e284db28
--- /dev/null
+++ b/media/bufferpool/1.0/IConnection.hal
@@ -0,0 +1,43 @@
1/*
2 * Copyright (C) 2018 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
17package android.hardware.media.bufferpool@1.0;
18
19/**
20 * A connection to a buffer pool which handles requests from a buffer pool
21 * client. The connection must be made in order to receive buffers from
22 * other buffer pool clients.
23 */
24interface IConnection {
25
26 /**
27 * Retrieves a buffer using bufferId. The method must be called from
28 * receiving side of buffer during transferring only when the specified
29 * buffer is neither cached nor used. This fails if the specified
30 * transaction is not valid.
31 *
32 * @param transactionId Unique transaction id for buffer transferring.
33 * @param bufferId Id of the buffer to be fetched.
34 * @return status The status of the call.
35 * OK - A buffer was fetched successfully.
36 * NO_MEMORY - Memory allocation failure occurred.
37 * NOT_FOUND - A buffer was not found due to invalidation.
38 * CRITICAL_ERROR - Other errors.
39 * @return buffer The actual buffer which is specified with bufferId.
40 */
41 fetch(uint64_t transactionId, uint32_t bufferId) generates
42 (ResultStatus status, Buffer buffer);
43};
diff --git a/media/bufferpool/1.0/README.md b/media/bufferpool/1.0/README.md
new file mode 100644
index 00000000..ed985d82
--- /dev/null
+++ b/media/bufferpool/1.0/README.md
@@ -0,0 +1,54 @@
11. Overview
2
3A buffer pool enables processes to transfer buffers asynchronously.
4Without a buffer pool, a process calls a synchronous method of the other
5process and waits until the call finishes transferring a buffer. This adds
6unwanted latency due to context switching. With help from a buffer pool, a
7process can pass buffers asynchronously and reduce context switching latency.
8
9Passing an interface and a handle adds extra latency also. To mitigate the
10latency, passing IDs with local cache is used. For security concerns about
11rogue clients, FMQ is used to communicate between a buffer pool and a client
12process. FMQ is used to send buffer ownership change status from a client
13process to a buffer pool. Except FMQ, a buffer pool does not use any shared
14memory.
15
162. FMQ
17
18FMQ is used to send buffer ownership status changes to a buffer pool from a
19buffer pool client. A buffer pool synchronizes FMQ messages when there is a
20hidl request from the clients. Every client has its own connection and FMQ
21to communicate with the buffer pool. So sending an FMQ message on behalf of
22other clients is not possible.
23
24FMQ messages are sent when a buffer is acquired or released. Also, FMQ messages
25are sent when a buffer is transferred from a client to another client. FMQ has
26its own ID from a buffer pool. A client is specified with the ID.
27
28To transfer a buffer, a sender must send an FMQ message. The message must
29include a receiver's ID and a transaction ID. A receiver must send the
30transaction ID to fetch a buffer from a buffer pool. Since the sender already
31registered the receiver via an FMQ message, The buffer pool must verify the
32receiver with the transaction ID. In order to prevent faking a receiver, a
33connection to a buffer pool from client is made and kept privately. Also part of
34transaction ID is a sender ID in order to prevent fake transactions from other
35clients. This must be verified with an FMQ message from a buffer pool.
36
37FMQ messages are defined in BufferStatus and BufferStatusMessage of 'types.hal'.
38
393. Interfaces
40
41IConnection
42A connection to a buffer pool from a buffer pool client. The connection
43provides the functionalities to share buffers between buffer pool clients.
44The connection must be unique for each client.
45
46IAccessor
47An accessor to a buffer pool which makes a connection to the buffer pool.
48IAccesssor#connect creates an IConnection.
49
50IClientManager
51A manager of buffer pool clients and clients' connections to buffer pools. It
52sets up a process to be a receiver of buffers from a buffer pool. The manager
53is unique in a process.
54
diff --git a/media/bufferpool/1.0/types.hal b/media/bufferpool/1.0/types.hal
new file mode 100644
index 00000000..d8ab5977
--- /dev/null
+++ b/media/bufferpool/1.0/types.hal
@@ -0,0 +1,93 @@
1/*
2 * Copyright (C) 2018 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
17package android.hardware.media.bufferpool@1.0;
18
19enum ResultStatus : int32_t {
20 OK = 0,
21
22 NO_MEMORY = 1,
23 ALREADY_EXISTS = 2,
24 NOT_FOUND = 3,
25 CRITICAL_ERROR = 4,
26};
27
28/**
29 * Generic buffer for fast recycling for media/stagefright.
30 *
31 * During media pipeline buffer references are created, shared and
32 * destroyed frequently. The underlying buffers are allocated on demand
33 * by a buffer pool, and are recycled to the buffer pool when they are
34 * no longer referenced by the clients.
35 *
36 * E.g. ion or gralloc buffer
37 */
38struct Buffer {
39 uint32_t id;
40 handle buffer;
41};
42
43/**
44 * Buffer ownership status for the specified client.
45 * Buffer transfer status for the specified buffer transafer transaction.
46 * BufferStatus is posted along with BufferStatusMessage from a client to
47 * the buffer pool for synchronization after status change.
48 */
49enum BufferStatus : int32_t {
50 /** No longer used by the specified client. */
51 NOT_USED = 0,
52 /** Buffer is acquired by the specified client. */
53 USED = 1,
54 /** Buffer is sent by the specified client. */
55 TRANSFER_TO = 2,
56 /** Buffer transfer is acked by the receiver client. */
57 TRANSFER_FROM = 3,
58 /** Buffer transfer is timed out by receiver client. */
59 TRANSFER_TIMEOUT = 4,
60 /** Buffer transfer is not acked by the receiver. */
61 TRANSFER_LOST = 5,
62 /** Buffer fetch request from the client. */
63 TRANSFER_FETCH = 6,
64 /** Buffer transaction succeeded. */
65 TRANSFER_OK = 7,
66 /** Buffer transaction failure. */
67 TRANSFER_ERROR = 8,
68};
69
70/**
71 * Buffer ownership status change message. This message is
72 * sent via fmq to the buffer pool from client processes.
73 */
74struct BufferStatusMessage {
75 /**
76 * Transaction Id = (SenderId : sender local transaction Id)
77 * Transaction Id is created from sender and posted via fmq within
78 * TRANSFER_TO message.
79 */
80 uint64_t transactionId;
81 uint32_t bufferId;
82 BufferStatus newStatus;
83 /** Used by the buffer pool. not by client. */
84 int64_t connectionId;
85 /** Valid only when TRANSFER_TO is posted. */
86 int64_t targetConnectionId;
87 /**
88 * Used by the buffer pool, not by client.
89 * Monotonic timestamp in Us since fixed point in time as decided
90 * by the sender of the message
91 */
92 int64_t timestampUs;
93};