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 ANDROID_AUDIO_MMAP_STREAM_INTERFACE_H
18#define ANDROID_AUDIO_MMAP_STREAM_INTERFACE_H
19
20#include <system/audio.h>
21#include <utils/Errors.h>
22#include <utils/RefBase.h>
23
24namespace android {
25
26class MmapStreamCallback;
27
28class MmapStreamInterface : public virtual RefBase
29{
30  public:
31
32    /**
33     * Values for direction argument passed to openMmapStream()
34     */
35    typedef enum {
36        DIRECTION_OUTPUT = 0,  /**< open a playback mmap stream */
37        DIRECTION_INPUT,       /**< open a capture mmap stream */
38    } stream_direction_t;
39
40    class Client {
41     public:
42        uid_t clientUid;
43        pid_t clientPid;
44        String16 packageName;
45    };
46    /**
47     * Open a playback or capture stream in MMAP mode at the audio HAL.
48     *
49     * \note This method is implemented by AudioFlinger
50     *
51     * \param[in] direction open a playback or capture stream.
52     * \param[in] attr audio attributes defining the main use case for this stream
53     * \param[in,out] config audio parameters (sampling rate, format ...) for the stream.
54     *                       Requested parameters as input,
55     *                       Actual parameters as output
56     * \param[in] client a Client struct describing the first client using this stream.
57     * \param[in,out] deviceId audio device the stream should preferably be routed to/from
58     *                       Requested as input,
59     *                       Actual as output
60     * \param[in] callback the MmapStreamCallback interface used by AudioFlinger to notify
61     *                     condition changes affecting the stream operation
62     * \param[out] interface the MmapStreamInterface interface controlling the created stream
63     * \return OK if the stream was successfully created.
64     *         NO_INIT if AudioFlinger is not properly initialized
65     *         BAD_VALUE if the stream cannot be opened because of invalid arguments
66     *         INVALID_OPERATION if the stream cannot be opened because of platform limitations
67     */
68    static status_t openMmapStream(stream_direction_t direction,
69                                           const audio_attributes_t *attr,
70                                           audio_config_base_t *config,
71                                           const Client& client,
72                                           audio_port_handle_t *deviceId,
73                                           const sp<MmapStreamCallback>& callback,
74                                           sp<MmapStreamInterface>& interface);
75
76    /**
77     * Retrieve information on the mmap buffer used for audio samples transfer.
78     * Must be called before any other method after opening the stream or entering standby.
79     *
80     * \param[in] min_size_frames minimum buffer size requested. The actual buffer
81     *        size returned in struct audio_mmap_buffer_info can be larger.
82     * \param[out] info address at which the mmap buffer information should be returned.
83     *
84     * \return OK if the buffer was allocated.
85     *         NO_INIT in case of initialization error
86     *         BAD_VALUE if the requested buffer size is too large
87     *         INVALID_OPERATION if called out of sequence (e.g. buffer already allocated)
88     */
89    virtual status_t createMmapBuffer(int32_t minSizeFrames,
90                                      struct audio_mmap_buffer_info *info) = 0;
91
92    /**
93     * Read current read/write position in the mmap buffer with associated time stamp.
94     *
95     * \param[out] position address at which the mmap read/write position should be returned.
96     *
97     * \return OK if the position is successfully returned.
98     *         NO_INIT in case of initialization error
99     *         NOT_ENOUGH_DATA if the position cannot be retrieved
100     *         INVALID_OPERATION if called before createMmapBuffer()
101     */
102    virtual status_t getMmapPosition(struct audio_mmap_position *position) = 0;
103
104    /**
105     * Start a stream operating in mmap mode.
106     * createMmapBuffer() must be called before calling start()
107     *
108     * \param[in] client a Client struct describing the client starting on this stream.
109     * \param[out] handle unique handle for this instance. Used with stop().
110     * \return OK in case of success.
111     *         NO_INIT in case of initialization error
112     *         INVALID_OPERATION if called out of sequence
113     */
114    virtual status_t start(const Client& client, audio_port_handle_t *handle) = 0;
115
116    /**
117     * Stop a stream operating in mmap mode.
118     * Must be called after start()
119     *
120     * \param[in] handle unique handle allocated by start().
121     * \return OK in case of success.
122     *         NO_INIT in case of initialization error
123     *         INVALID_OPERATION if called out of sequence
124     */
125    virtual status_t stop(audio_port_handle_t handle) = 0;
126
127    /**
128     * Put a stream operating in mmap mode into standby.
129     * Must be called after createMmapBuffer(). Cannot be called if any client is active.
130     * It is recommended to place a mmap stream into standby as often as possible when no client is
131     * active to save power.
132     *
133     * \return OK in case of success.
134     *         NO_INIT in case of initialization error
135     *         INVALID_OPERATION if called out of sequence
136     */
137    virtual status_t standby() = 0;
138
139  protected:
140    // Subclasses can not be constructed directly by clients.
141    MmapStreamInterface() {}
142
143    // The destructor automatically closes the stream.
144    virtual ~MmapStreamInterface() {}
145};
146
147} // namespace android
148
149#endif // ANDROID_AUDIO_MMAP_STREAM_INTERFACE_H
150