[deliverable/linux.git] / include / sound / compress_driver.h

/*
 *  compress_driver.h - compress offload driver definations
 *
 *  Copyright (C) 2011 Intel Corporation
 *  Authors:	Vinod Koul <vinod.koul@linux.intel.com>
 *		Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
 *  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; version 2 of the License.
 *
 *  This program is distributed in the hope that it will be useful, but
 *  WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License along
 *  with this program; if not, write to the Free Software Foundation, Inc.,
 *  59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
 *
 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 *
 */
#ifndef __COMPRESS_DRIVER_H
#define __COMPRESS_DRIVER_H

#include <linux/types.h>
#include <linux/sched.h>
#include <sound/compress_offload.h>
#include <sound/asound.h>
#include <sound/pcm.h>

struct snd_compr_ops;

/**
 * struct snd_compr_runtime: runtime stream description
 * @state: stream state
 * @ops: pointer to DSP callbacks
 * @buffer: pointer to kernel buffer, valid only when not in mmap mode or
 *	DSP doesn't implement copy
 * @buffer_size: size of the above buffer
 * @fragment_size: size of buffer fragment in bytes
 * @fragments: number of such fragments
 * @hw_pointer: offset of last location in buffer where DSP copied data
 * @app_pointer: offset of last location in buffer where app wrote data
 * @total_bytes_available: cumulative number of bytes made available in
 *	the ring buffer
 * @total_bytes_transferred: cumulative bytes transferred by offload DSP
 * @sleep: poll sleep
 * @wait: drain wait queue
 * @drain_wake: condition for drain wake
 */
struct snd_compr_runtime {
	snd_pcm_state_t state;
	struct snd_compr_ops *ops;
	void *buffer;
	u64 buffer_size;
	u32 fragment_size;
	u32 fragments;
	u64 total_bytes_available;
	u64 total_bytes_transferred;
	wait_queue_head_t sleep;
	wait_queue_head_t wait;
	unsigned int drain_wake;
	void *private_data;
};

/**
 * struct snd_compr_stream: compressed stream
 * @name: device name
 * @ops: pointer to DSP callbacks
 * @runtime: pointer to runtime structure
 * @device: device pointer
 * @direction: stream direction, playback/recording
 * @metadata_set: metadata set flag, true when set
 * @next_track: has userspace signall next track transistion, true when set
 * @private_data: pointer to DSP private data
 */
struct snd_compr_stream {
	const char *name;
	struct snd_compr_ops *ops;
	struct snd_compr_runtime *runtime;
	struct snd_compr *device;
	enum snd_compr_direction direction;
	bool metadata_set;
	bool next_track;
	void *private_data;
};

/**
 * struct snd_compr_ops: compressed path DSP operations
 * @open: Open the compressed stream
 * This callback is mandatory and shall keep dsp ready to receive the stream
 * parameter
 * @free: Close the compressed stream, mandatory
 * @set_params: Sets the compressed stream parameters, mandatory
 * This can be called in during stream creation only to set codec params
 * and the stream properties
 * @get_params: retrieve the codec parameters, mandatory
 * @trigger: Trigger operations like start, pause, resume, drain, stop.
 * This callback is mandatory
 * @pointer: Retrieve current h/w pointer information. Mandatory
 * @copy: Copy the compressed data to/from userspace, Optional
 * Can't be implemented if DSP supports mmap
 * @mmap: DSP mmap method to mmap DSP memory
 * @ack: Ack for DSP when data is written to audio buffer, Optional
 * Not valid if copy is implemented
 * @get_caps: Retrieve DSP capabilities, mandatory
 * @get_codec_caps: Retrieve capabilities for a specific codec, mandatory
 */
struct snd_compr_ops {
	int (*open)(struct snd_compr_stream *stream);
	int (*free)(struct snd_compr_stream *stream);
	int (*set_params)(struct snd_compr_stream *stream,
			struct snd_compr_params *params);
	int (*get_params)(struct snd_compr_stream *stream,
			struct snd_codec *params);
	int (*set_metadata)(struct snd_compr_stream *stream,
			struct snd_compr_metadata *metadata);
	int (*get_metadata)(struct snd_compr_stream *stream,
			struct snd_compr_metadata *metadata);
	int (*trigger)(struct snd_compr_stream *stream, int cmd);
	int (*pointer)(struct snd_compr_stream *stream,
			struct snd_compr_tstamp *tstamp);
	int (*copy)(struct snd_compr_stream *stream, char __user *buf,
		       size_t count);
	int (*mmap)(struct snd_compr_stream *stream,
			struct vm_area_struct *vma);
	int (*ack)(struct snd_compr_stream *stream, size_t bytes);
	int (*get_caps) (struct snd_compr_stream *stream,
			struct snd_compr_caps *caps);
	int (*get_codec_caps) (struct snd_compr_stream *stream,
			struct snd_compr_codec_caps *codec);
};

/**
 * struct snd_compr: Compressed device
 * @name: DSP device name
 * @dev: Device pointer
 * @ops: pointer to DSP callbacks
 * @private_data: pointer to DSP pvt data
 * @card: sound card pointer
 * @direction: Playback or capture direction
 * @lock: device lock
 * @device: device id
 */
struct snd_compr {
	const char *name;
	struct device *dev;
	struct snd_compr_ops *ops;
	void *private_data;
	struct snd_card *card;
	unsigned int direction;
	struct mutex lock;
	int device;
};

/* compress device register APIs */
int snd_compress_register(struct snd_compr *device);
int snd_compress_deregister(struct snd_compr *device);
int snd_compress_new(struct snd_card *card, int device,
			int type, struct snd_compr *compr);

/* dsp driver callback apis
 * For playback: driver should call snd_compress_fragment_elapsed() to let the
 * framework know that a fragment has been consumed from the ring buffer
 *
 * For recording: we want to know when a frame is available or when
 * at least one frame is available so snd_compress_frame_elapsed()
 * callback should be called when a encodeded frame is available
 */
static inline void snd_compr_fragment_elapsed(struct snd_compr_stream *stream)
{
	wake_up(&stream->runtime->sleep);
}

static inline void snd_compr_drain_notify(struct snd_compr_stream *stream)
{
	snd_BUG_ON(!stream);

	stream->runtime->drain_wake = 1;
	wake_up(&stream->runtime->wait);
}

#endif
Commit	Line	Data
e60061a3 VK	1	/*
	2	* compress_driver.h - compress offload driver definations
	3	*
	4	* Copyright (C) 2011 Intel Corporation
	5	* Authors: Vinod Koul <vinod.koul@linux.intel.com>
	6	* Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
	7	* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	8	*
	9	* This program is free software; you can redistribute it and/or modify
	10	* it under the terms of the GNU General Public License as published by
	11	* the Free Software Foundation; version 2 of the License.
	12	*
	13	* This program is distributed in the hope that it will be useful, but
	14	* WITHOUT ANY WARRANTY; without even the implied warranty of
	15	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	16	* General Public License for more details.
	17	*
	18	* You should have received a copy of the GNU General Public License along
	19	* with this program; if not, write to the Free Software Foundation, Inc.,
	20	* 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
	21	*
	22	* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	23	*
	24	*/
	25	#ifndef __COMPRESS_DRIVER_H
	26	#define __COMPRESS_DRIVER_H
	27
	28	#include <linux/types.h>
	29	#include <linux/sched.h>
	30	#include <sound/compress_offload.h>
	31	#include <sound/asound.h>
	32	#include <sound/pcm.h>
	33
	34	struct snd_compr_ops;
	35
	36	/**
	37	* struct snd_compr_runtime: runtime stream description
	38	* @state: stream state
	39	* @ops: pointer to DSP callbacks
	40	* @buffer: pointer to kernel buffer, valid only when not in mmap mode or
	41	* DSP doesn't implement copy
	42	* @buffer_size: size of the above buffer
	43	* @fragment_size: size of buffer fragment in bytes
	44	* @fragments: number of such fragments
	45	* @hw_pointer: offset of last location in buffer where DSP copied data
	46	* @app_pointer: offset of last location in buffer where app wrote data
	47	* @total_bytes_available: cumulative number of bytes made available in
	48	* the ring buffer
	49	* @total_bytes_transferred: cumulative bytes transferred by offload DSP
	50	* @sleep: poll sleep
917f4b5c VK	51	* @wait: drain wait queue
917f4b5c VK	52	* @drain_wake: condition for drain wake
e60061a3 VK	53	*/
	54	struct snd_compr_runtime {
	55	snd_pcm_state_t state;
	56	struct snd_compr_ops *ops;
	57	void *buffer;
	58	u64 buffer_size;
	59	u32 fragment_size;
	60	u32 fragments;
e60061a3 VK	61	u64 total_bytes_available;
	62	u64 total_bytes_transferred;
	63	wait_queue_head_t sleep;
917f4b5c VK	64	wait_queue_head_t wait;
917f4b5c VK	65	unsigned int drain_wake;
49681077	66	void *private_data;
e60061a3 VK	67	};
	68
	69	/**
	70	* struct snd_compr_stream: compressed stream
	71	* @name: device name
	72	* @ops: pointer to DSP callbacks
	73	* @runtime: pointer to runtime structure
	74	* @device: device pointer
	75	* @direction: stream direction, playback/recording
9727b490 JK	76	* @metadata_set: metadata set flag, true when set
9727b490 JK	77	* @next_track: has userspace signall next track transistion, true when set
e60061a3 VK	78	* @private_data: pointer to DSP private data
	79	*/
	80	struct snd_compr_stream {
	81	const char *name;
	82	struct snd_compr_ops *ops;
	83	struct snd_compr_runtime *runtime;
	84	struct snd_compr *device;
	85	enum snd_compr_direction direction;
9727b490 JK	86	bool metadata_set;
9727b490 JK	87	bool next_track;
e60061a3 VK	88	void *private_data;
	89	};
	90
	91	/**
	92	* struct snd_compr_ops: compressed path DSP operations
	93	* @open: Open the compressed stream
	94	* This callback is mandatory and shall keep dsp ready to receive the stream
	95	* parameter
	96	* @free: Close the compressed stream, mandatory
	97	* @set_params: Sets the compressed stream parameters, mandatory
	98	* This can be called in during stream creation only to set codec params
	99	* and the stream properties
	100	* @get_params: retrieve the codec parameters, mandatory
	101	* @trigger: Trigger operations like start, pause, resume, drain, stop.
	102	* This callback is mandatory
	103	* @pointer: Retrieve current h/w pointer information. Mandatory
	104	* @copy: Copy the compressed data to/from userspace, Optional
	105	* Can't be implemented if DSP supports mmap
	106	* @mmap: DSP mmap method to mmap DSP memory
	107	* @ack: Ack for DSP when data is written to audio buffer, Optional
	108	* Not valid if copy is implemented
	109	* @get_caps: Retrieve DSP capabilities, mandatory
	110	* @get_codec_caps: Retrieve capabilities for a specific codec, mandatory
	111	*/
	112	struct snd_compr_ops {
	113	int (open)(struct snd_compr_stream stream);
	114	int (free)(struct snd_compr_stream stream);
	115	int (set_params)(struct snd_compr_stream stream,
	116	struct snd_compr_params *params);
	117	int (get_params)(struct snd_compr_stream stream,
	118	struct snd_codec *params);
9727b490 JK	119	int (set_metadata)(struct snd_compr_stream stream,
	120	struct snd_compr_metadata *metadata);
	121	int (get_metadata)(struct snd_compr_stream stream,
	122	struct snd_compr_metadata *metadata);
e60061a3 VK	123	int (trigger)(struct snd_compr_stream stream, int cmd);
	124	int (pointer)(struct snd_compr_stream stream,
	125	struct snd_compr_tstamp *tstamp);
4daf891c	126	int (copy)(struct snd_compr_stream stream, char __user *buf,
e60061a3 VK	127	size_t count);
	128	int (mmap)(struct snd_compr_stream stream,
	129	struct vm_area_struct *vma);
	130	int (ack)(struct snd_compr_stream stream, size_t bytes);
	131	int (get_caps) (struct snd_compr_stream stream,
	132	struct snd_compr_caps *caps);
	133	int (get_codec_caps) (struct snd_compr_stream stream,
	134	struct snd_compr_codec_caps *codec);
	135	};
	136
	137	/**
	138	* struct snd_compr: Compressed device
	139	* @name: DSP device name
	140	* @dev: Device pointer
	141	* @ops: pointer to DSP callbacks
	142	* @private_data: pointer to DSP pvt data
	143	* @card: sound card pointer
	144	* @direction: Playback or capture direction
	145	* @lock: device lock
	146	* @device: device id
	147	*/
	148	struct snd_compr {
	149	const char *name;
	150	struct device *dev;
	151	struct snd_compr_ops *ops;
	152	void *private_data;
	153	struct snd_card *card;
	154	unsigned int direction;
	155	struct mutex lock;
	156	int device;
	157	};
	158
	159	/* compress device register APIs */
	160	int snd_compress_register(struct snd_compr *device);
	161	int snd_compress_deregister(struct snd_compr *device);
	162	int snd_compress_new(struct snd_card *card, int device,
	163	int type, struct snd_compr *compr);
	164
	165	/* dsp driver callback apis
	166	* For playback: driver should call snd_compress_fragment_elapsed() to let the
	167	* framework know that a fragment has been consumed from the ring buffer
	168	*
	169	* For recording: we want to know when a frame is available or when
	170	* at least one frame is available so snd_compress_frame_elapsed()
	171	* callback should be called when a encodeded frame is available
	172	*/
	173	static inline void snd_compr_fragment_elapsed(struct snd_compr_stream *stream)
	174	{
	175	wake_up(&stream->runtime->sleep);
	176	}
	177
917f4b5c VK	178	static inline void snd_compr_drain_notify(struct snd_compr_stream *stream)
	179	{
	180	snd_BUG_ON(!stream);
	181
	182	stream->runtime->drain_wake = 1;
	183	wake_up(&stream->runtime->wait);
	184	}
	185
e60061a3	186	#endif