1fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent/* 2fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * Copyright (C) 2016 The Android Open Source Project 3fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * 4fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * Licensed under the Apache License, Version 2.0 (the "License"); 5fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * you may not use this file except in compliance with the License. 6fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * You may obtain a copy of the License at 7fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * 8fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * http://www.apache.org/licenses/LICENSE-2.0 9fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * 10fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * Unless required by applicable law or agreed to in writing, software 11fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * distributed under the License is distributed on an "AS IS" BASIS, 12fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * See the License for the specific language governing permissions and 14fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * limitations under the License. 15fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent */ 16fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent 17fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent#ifndef ANDROID_AUDIO_MMAP_STREAM_INTERFACE_H 18fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent#define ANDROID_AUDIO_MMAP_STREAM_INTERFACE_H 19fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent 20fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent#include <system/audio.h> 21a54f1283fdd9adbd64ecca4e14af56aaa0e8c825Eric Laurent#include <media/AudioClient.h> 22fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent#include <utils/Errors.h> 23fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent#include <utils/RefBase.h> 24fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent 25fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurentnamespace android { 26fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent 27fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurentclass MmapStreamCallback; 28fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent 29fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurentclass MmapStreamInterface : public virtual RefBase 30fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent{ 31fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent public: 32fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent 33fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent /** 34fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * Values for direction argument passed to openMmapStream() 35fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent */ 36fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent typedef enum { 37fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent DIRECTION_OUTPUT = 0, /**< open a playback mmap stream */ 38fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent DIRECTION_INPUT, /**< open a capture mmap stream */ 39fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent } stream_direction_t; 40fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent 41fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent /** 42fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * Open a playback or capture stream in MMAP mode at the audio HAL. 43fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * 44fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * \note This method is implemented by AudioFlinger 45fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * 46fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * \param[in] direction open a playback or capture stream. 47fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * \param[in] attr audio attributes defining the main use case for this stream 48fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * \param[in,out] config audio parameters (sampling rate, format ...) for the stream. 49fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * Requested parameters as input, 50fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * Actual parameters as output 51a54f1283fdd9adbd64ecca4e14af56aaa0e8c825Eric Laurent * \param[in] client a AudioClient struct describing the first client using this stream. 52fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * \param[in,out] deviceId audio device the stream should preferably be routed to/from 53fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * Requested as input, 54fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * Actual as output 554e1af9fc9c1108d4514e92774f750bcd434dbbccPhil Burk * \param[in,out] sessionId audio sessionId for the stream 564e1af9fc9c1108d4514e92774f750bcd434dbbccPhil Burk * Requested as input, may be AUDIO_SESSION_ALLOCATE 574e1af9fc9c1108d4514e92774f750bcd434dbbccPhil Burk * Actual as output 58fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * \param[in] callback the MmapStreamCallback interface used by AudioFlinger to notify 59fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * condition changes affecting the stream operation 60fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * \param[out] interface the MmapStreamInterface interface controlling the created stream 61a54f1283fdd9adbd64ecca4e14af56aaa0e8c825Eric Laurent * \param[out] same unique handle as the one used for the first client stream started. 62fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * \return OK if the stream was successfully created. 63fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * NO_INIT if AudioFlinger is not properly initialized 64fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * BAD_VALUE if the stream cannot be opened because of invalid arguments 65fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * INVALID_OPERATION if the stream cannot be opened because of platform limitations 66fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent */ 67fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent static status_t openMmapStream(stream_direction_t direction, 68fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent const audio_attributes_t *attr, 69fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent audio_config_base_t *config, 70a54f1283fdd9adbd64ecca4e14af56aaa0e8c825Eric Laurent const AudioClient& client, 71fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent audio_port_handle_t *deviceId, 724e1af9fc9c1108d4514e92774f750bcd434dbbccPhil Burk audio_session_t *sessionId, 73fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent const sp<MmapStreamCallback>& callback, 74a54f1283fdd9adbd64ecca4e14af56aaa0e8c825Eric Laurent sp<MmapStreamInterface>& interface, 75a54f1283fdd9adbd64ecca4e14af56aaa0e8c825Eric Laurent audio_port_handle_t *handle); 76fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent 77fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent /** 78fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * Retrieve information on the mmap buffer used for audio samples transfer. 7918b570146c971fe729c391bfbb869391084e623dEric Laurent * Must be called before any other method after opening the stream or entering standby. 80fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * 81fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * \param[in] min_size_frames minimum buffer size requested. The actual buffer 82fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * size returned in struct audio_mmap_buffer_info can be larger. 83fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * \param[out] info address at which the mmap buffer information should be returned. 84fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * 85fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * \return OK if the buffer was allocated. 86fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * NO_INIT in case of initialization error 87fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * BAD_VALUE if the requested buffer size is too large 88fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * INVALID_OPERATION if called out of sequence (e.g. buffer already allocated) 89fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent */ 90fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent virtual status_t createMmapBuffer(int32_t minSizeFrames, 91fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent struct audio_mmap_buffer_info *info) = 0; 92fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent 93fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent /** 94fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * Read current read/write position in the mmap buffer with associated time stamp. 95fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * 96fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * \param[out] position address at which the mmap read/write position should be returned. 97fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * 98fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * \return OK if the position is successfully returned. 9918b570146c971fe729c391bfbb869391084e623dEric Laurent * NO_INIT in case of initialization error 100fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * NOT_ENOUGH_DATA if the position cannot be retrieved 101fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * INVALID_OPERATION if called before createMmapBuffer() 102fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent */ 103fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent virtual status_t getMmapPosition(struct audio_mmap_position *position) = 0; 104fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent 105fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent /** 106fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * Start a stream operating in mmap mode. 107fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * createMmapBuffer() must be called before calling start() 108fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * 109a54f1283fdd9adbd64ecca4e14af56aaa0e8c825Eric Laurent * \param[in] client a AudioClient struct describing the client starting on this stream. 110fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * \param[out] handle unique handle for this instance. Used with stop(). 111fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * \return OK in case of success. 11218b570146c971fe729c391bfbb869391084e623dEric Laurent * NO_INIT in case of initialization error 113fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * INVALID_OPERATION if called out of sequence 114fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent */ 115a54f1283fdd9adbd64ecca4e14af56aaa0e8c825Eric Laurent virtual status_t start(const AudioClient& client, audio_port_handle_t *handle) = 0; 116fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent 117fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent /** 118fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * Stop a stream operating in mmap mode. 119fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * Must be called after start() 120fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * 121fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * \param[in] handle unique handle allocated by start(). 122fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * \return OK in case of success. 12318b570146c971fe729c391bfbb869391084e623dEric Laurent * NO_INIT in case of initialization error 124fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent * INVALID_OPERATION if called out of sequence 125fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent */ 126fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent virtual status_t stop(audio_port_handle_t handle) = 0; 127fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent 12818b570146c971fe729c391bfbb869391084e623dEric Laurent /** 12918b570146c971fe729c391bfbb869391084e623dEric Laurent * Put a stream operating in mmap mode into standby. 13018b570146c971fe729c391bfbb869391084e623dEric Laurent * Must be called after createMmapBuffer(). Cannot be called if any client is active. 13118b570146c971fe729c391bfbb869391084e623dEric Laurent * It is recommended to place a mmap stream into standby as often as possible when no client is 13218b570146c971fe729c391bfbb869391084e623dEric Laurent * active to save power. 13318b570146c971fe729c391bfbb869391084e623dEric Laurent * 13418b570146c971fe729c391bfbb869391084e623dEric Laurent * \return OK in case of success. 13518b570146c971fe729c391bfbb869391084e623dEric Laurent * NO_INIT in case of initialization error 13618b570146c971fe729c391bfbb869391084e623dEric Laurent * INVALID_OPERATION if called out of sequence 13718b570146c971fe729c391bfbb869391084e623dEric Laurent */ 13818b570146c971fe729c391bfbb869391084e623dEric Laurent virtual status_t standby() = 0; 13918b570146c971fe729c391bfbb869391084e623dEric Laurent 140fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent protected: 141fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent // Subclasses can not be constructed directly by clients. 142fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent MmapStreamInterface() {} 143fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent 144fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent // The destructor automatically closes the stream. 145fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent virtual ~MmapStreamInterface() {} 146fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent}; 147fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent 148fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent} // namespace android 149fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent 150fc23520d9c3f15e28baa81de5f7dfa6c1b0af426Eric Laurent#endif // ANDROID_AUDIO_MMAP_STREAM_INTERFACE_H 151