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@2.0;
18
19import IConnection;
20import IObserver;
21/**
22 * IAccessor creates IConnection which is used from IClientManager in order to
23 * use functionality of the specified buffer pool.
24 */
25interface IAccessor {
26
27    /**
28     * Registers a new client and creates IConnection to the buffer pool for
29     * the client. IConnection and FMQ are used by IClientManager in order to
30     * communicate with the buffer pool. Via FMQ IClientManager sends
31     * BufferStatusMesage(s) to the buffer pool.
32     *
33     * FMQ is used to send buffer ownership status changes to a buffer pool
34     * from a buffer pool client. A buffer pool synchronizes FMQ messages when
35     * there is a hidl request from the clients. Every client has its own
36     * connection and FMQ to communicate with the buffer pool. So sending an
37     * FMQ message on behalf of other clients is not possible.
38     *
39     * FMQ messages are sent when a buffer is acquired or released. Also, FMQ
40     * messages are sent when a buffer is transferred from a client to another
41     * client. FMQ has its own ID from a buffer pool. A client is specified
42     * with the ID.
43     *
44     * To transfer a buffer, a sender must send an FMQ message. The message
45     * must include a receiver's ID and a transaction ID. A receiver must send
46     * the transaction ID to fetch a buffer from a buffer pool. Since the
47     * sender already registered the receiver via an FMQ message, The buffer
48     * pool must verify the receiver with the transaction ID. In order to
49     * prevent faking a receiver, a connection to a buffer pool from client is
50     * made and kept private. Also part of transaction ID is a sender ID in
51     * order to prevent fake transactions from other clients. This must be
52     * verified with an FMQ message from a buffer pool.
53
54     * @param observer The buffer pool event observer from the client.
55     *     Observer is provided to ensure FMQ messages are processed even when
56     *     client processes are idle. Buffer invalidation caused by
57     *     reconfiguration does not call observer. Buffer invalidation caused
58     *     by termination of pipeline call observer in order to ensure
59     *     invalidation is done after pipeline completion.
60     *
61     * @return status The status of the call.
62     *     OK               - A connection is made successfully.
63     *     NO_MEMORY        - Memory allocation failure occurred.
64     *     ALREADY_EXISTS   - A connection was already made.
65     *     CRITICAL_ERROR   - Other errors.
66     * @return connection The IConnection have interfaces
67     *     to get shared buffers from the buffer pool.
68     * @return connectionId Id of IConnection. The Id identifies
69     *     sender and receiver in FMQ messages during buffer transfer.
70     * @return msgId Id of the most recent message from buffer pool.
71     * @return toFmqDesc FMQ descriptor. The descriptor is used to
72     *     post buffer status messages.
73     * @return fromFmqDesc FMQ descriptor. The descriptor is used to
74     *     receive buffer invalidation messages from the buffer pool.
75     */
76    connect(IObserver observer)
77        generates (ResultStatus status, IConnection connection,
78                   int64_t connectionId,
79                   uint32_t msgId,
80                   fmq_sync<BufferStatusMessage> toFmqDesc,
81                   fmq_unsync<BufferInvalidationMessage> fromFmqDesc);
82};
83