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