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