drivers/staging/media/atomisp/pci/atomisp2/css2400/ia_css_stream_public.h

/*
 * Support for Intel Camera Imaging ISP subsystem.
 * Copyright (c) 2015, Intel Corporation.
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms and conditions of the GNU General Public License,
 * version 2, as published by the Free Software Foundation.
 *
 * This program is distributed in the hope 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.
 */

#ifndef __IA_CSS_STREAM_PUBLIC_H
#define __IA_CSS_STREAM_PUBLIC_H

/** @file
 * This file contains support for configuring and controlling streams
 */

#include <type_support.h>
#include "ia_css_types.h"
#include "ia_css_pipe_public.h"
#include "ia_css_metadata.h"
#include "ia_css_tpg.h"
#include "ia_css_prbs.h"
#include "ia_css_input_port.h"

/** Input modes, these enumerate all supported input modes.
 *  Note that not all ISP modes support all input modes.
 */
enum ia_css_input_mode {
	IA_CSS_INPUT_MODE_SENSOR, /**< data from sensor */
	IA_CSS_INPUT_MODE_FIFO,   /**< data from input-fifo */
	IA_CSS_INPUT_MODE_TPG,    /**< data from test-pattern generator */
	IA_CSS_INPUT_MODE_PRBS,   /**< data from pseudo-random bit stream */
	IA_CSS_INPUT_MODE_MEMORY, /**< data from a frame in memory */
	IA_CSS_INPUT_MODE_BUFFERED_SENSOR /**< data is sent through mipi buffer */
};

/** Structure of the MIPI buffer configuration
 */
struct ia_css_mipi_buffer_config {
	unsigned int size_mem_words; /**< The frame size in the system memory
					  words (32B) */
	bool contiguous;	     /**< Allocated memory physically
					  contiguously or not. \deprecated{Will be false always.}*/
	unsigned int nof_mipi_buffers; /**< The number of MIPI buffers required for this
					stream */
};

enum {
	IA_CSS_STREAM_ISYS_STREAM_0 = 0,
	IA_CSS_STREAM_DEFAULT_ISYS_STREAM_IDX = IA_CSS_STREAM_ISYS_STREAM_0,
	IA_CSS_STREAM_ISYS_STREAM_1,
	IA_CSS_STREAM_MAX_ISYS_STREAM_PER_CH
};

/** This is input data configuration for one MIPI data type. We can have
 *  multiple of this in one virtual channel.
 */
struct ia_css_stream_isys_stream_config {
	struct ia_css_resolution  input_res; /**< Resolution of input data */
	enum ia_css_stream_format format; /**< Format of input stream. This data
					       format will be mapped to MIPI data
					       type internally. */
	int linked_isys_stream_id; /**< default value is -1, other value means
							current isys_stream shares the same buffer with
							indicated isys_stream*/
	bool valid; /**< indicate whether other fields have valid value */
};

struct ia_css_stream_input_config {
	struct ia_css_resolution  input_res; /**< Resolution of input data */
	struct ia_css_resolution  effective_res; /**< Resolution of input data.
							Used for CSS 2400/1 System and deprecated for other
							systems (replaced by input_effective_res in
							ia_css_pipe_config) */
	enum ia_css_stream_format format; /**< Format of input stream. This data
					       format will be mapped to MIPI data
					       type internally. */
	enum ia_css_bayer_order bayer_order; /**< Bayer order for RAW streams */
};


/** Input stream description. This describes how input will flow into the
 *  CSS. This is used to program the CSS hardware.
 */
struct ia_css_stream_config {
	enum ia_css_input_mode    mode; /**< Input mode */
	union {
		struct ia_css_input_port  port; /**< Port, for sensor only. */
		struct ia_css_tpg_config  tpg;  /**< TPG configuration */
		struct ia_css_prbs_config prbs; /**< PRBS configuration */
	} source; /**< Source of input data */
	unsigned int	      channel_id; /**< Channel on which input data
						   will arrive. Use this field
						   to specify virtual channel id.
						   Valid values are: 0, 1, 2, 3 */
	struct ia_css_stream_isys_stream_config isys_config[IA_CSS_STREAM_MAX_ISYS_STREAM_PER_CH];
	struct ia_css_stream_input_config input_config;

#ifdef ISP2401
	/* Currently, Android and Windows platforms interpret the binning_factor parameter
	 * differently. In Android, the binning factor is expressed in the form
	 * 2^N * 2^N, whereas in Windows platform, the binning factor is N*N
	 * To use the Windows method of specification, the caller has to define
	 * macro USE_WINDOWS_BINNING_FACTOR. This is for backward compatibility only
	 * and will be deprecated. In the future,all platforms will use the N*N method
	 */
#endif
	unsigned int sensor_binning_factor; /**< Binning factor used by sensor
						 to produce image data. This is
						 used for shading correction. */
	unsigned int pixels_per_clock; /**< Number of pixels per clock, which can be
					    1, 2 or 4. */
	bool online; /**< offline will activate RAW copy on SP, use this for
			  continuous capture. */
		/* ISYS2401 usage: ISP receives data directly from sensor, no copy. */
	unsigned init_num_cont_raw_buf; /**< initial number of raw buffers to
					     allocate */
	unsigned target_num_cont_raw_buf; /**< total number of raw buffers to
					     allocate */
	bool pack_raw_pixels; /**< Pack pixels in the raw buffers */
	bool continuous; /**< Use SP copy feature to continuously capture frames
			      to system memory and run pipes in offline mode */
	bool disable_cont_viewfinder; /**< disable continous viewfinder for ZSL use case */
	int32_t flash_gpio_pin; /**< pin on which the flash is connected, -1 for no flash */
	int left_padding; /**< The number of input-formatter left-paddings, -1 for default from binary.*/
	struct ia_css_mipi_buffer_config mipi_buffer_config; /**< mipi buffer configuration */
	struct ia_css_metadata_config	metadata_config;     /**< Metadata configuration. */
	bool ia_css_enable_raw_buffer_locking; /**< Enable Raw Buffer Locking for HALv3 Support */
	bool lock_all;
	/**< Lock all RAW buffers (true) or lock only buffers processed by
	     video or preview pipe (false).
	     This setting needs to be enabled to allow raw buffer locking
	     without continuous viewfinder. */
};

struct ia_css_stream;

/** Stream info, this struct describes properties of a stream after it has been
 *  created.
 */
struct ia_css_stream_info {
	struct ia_css_metadata_info metadata_info;
	/**< Info about the metadata layout, this contains the stride. */
};

/** @brief Load default stream configuration
 * @param[in,out]	stream_config The stream configuration.
 * @return	None
 *
 * This function will reset the stream configuration to the default state:
@code
	memset(stream_config, 0, sizeof(*stream_config));
	stream_config->online = true;
	stream_config->left_padding = -1;
@endcode
 */
void ia_css_stream_config_defaults(struct ia_css_stream_config *stream_config);

/*
 * create the internal structures and fill in the configuration data and pipes
 */

 /** @brief Creates a stream
 * @param[in]	stream_config The stream configuration.
 * @param[in]	num_pipes The number of pipes to incorporate in the stream.
 * @param[in]	pipes The pipes.
 * @param[out]	stream The stream.
 * @return	IA_CSS_SUCCESS or the error code.
 *
 * This function will create a stream with a given configuration and given pipes.
 */
enum ia_css_err
ia_css_stream_create(const struct ia_css_stream_config *stream_config,
					 int num_pipes,
					 struct ia_css_pipe *pipes[],
					 struct ia_css_stream **stream);

/** @brief Destroys a stream
 * @param[in]	stream The stream.
 * @return	IA_CSS_SUCCESS or the error code.
 *
 * This function will destroy a given stream.
 */
enum ia_css_err
ia_css_stream_destroy(struct ia_css_stream *stream);

/** @brief Provides information about a stream
 * @param[in]	stream The stream.
 * @param[out]	stream_info The information about the stream.
 * @return	IA_CSS_SUCCESS or the error code.
 *
 * This function will destroy a given stream.
 */
enum ia_css_err
ia_css_stream_get_info(const struct ia_css_stream *stream,
		       struct ia_css_stream_info *stream_info);

/** @brief load (rebuild) a stream that was unloaded.
 * @param[in]	stream The stream
 * @return		IA_CSS_SUCCESS or the error code
 *
 * Rebuild a stream, including allocating structs, setting configuration and
 * building the required pipes.
 */
enum ia_css_err
ia_css_stream_load(struct ia_css_stream *stream);

/** @brief Starts the stream.
 * @param[in]	stream The stream.
 * @return IA_CSS_SUCCESS or the error code.
 *
 * The dynamic data in
 * the buffers are not used and need to be queued with a separate call
 * to ia_css_pipe_enqueue_buffer.
 * NOTE: this function will only send start event to corresponding
 * thread and will not start SP any more.
 */
enum ia_css_err
ia_css_stream_start(struct ia_css_stream *stream);

/** @brief Stop the stream.
 * @param[in]	stream The stream.
 * @return	IA_CSS_SUCCESS or the error code.
 *
 * NOTE: this function will send stop event to pipes belong to this
 * stream but will not terminate threads.
 */
enum ia_css_err
ia_css_stream_stop(struct ia_css_stream *stream);

/** @brief Check if a stream has stopped
 * @param[in]	stream The stream.
 * @return	boolean flag
 *
 * This function will check if the stream has stopped and return the correspondent boolean flag.
 */
bool
ia_css_stream_has_stopped(struct ia_css_stream *stream);

/** @brief	destroy a stream according to the stream seed previosly saved in the seed array.
 * @param[in]	stream The stream.
 * @return	IA_CSS_SUCCESS (no other errors are generated now)
 *
 * Destroy the stream and all the pipes related to it.
 */
enum ia_css_err
ia_css_stream_unload(struct ia_css_stream *stream);

/** @brief Returns stream format
 * @param[in]	stream The stream.
 * @return	format of the string
 *
 * This function will return the stream format.
 */
enum ia_css_stream_format
ia_css_stream_get_format(const struct ia_css_stream *stream);

/** @brief Check if the stream is configured for 2 pixels per clock
 * @param[in]	stream The stream.
 * @return	boolean flag
 *
 * This function will check if the stream is configured for 2 pixels per clock and
 * return the correspondent boolean flag.
 */
bool
ia_css_stream_get_two_pixels_per_clock(const struct ia_css_stream *stream);

/** @brief Sets the output frame stride (at the last pipe)
 * @param[in]	stream The stream
 * @param[in]	output_padded_width - the output buffer stride.
 * @return	ia_css_err
 *
 * This function will Set the output frame stride (at the last pipe)
 */
enum ia_css_err
ia_css_stream_set_output_padded_width(struct ia_css_stream *stream, unsigned int output_padded_width);

/** @brief Return max number of continuous RAW frames.
 * @param[in]	stream The stream.
 * @param[out]	buffer_depth The maximum number of continuous RAW frames.
 * @return	IA_CSS_SUCCESS or IA_CSS_ERR_INVALID_ARGUMENTS
 *
 * This function will return the maximum number of continuous RAW frames
 * the system can support.
 */
enum ia_css_err
ia_css_stream_get_max_buffer_depth(struct ia_css_stream *stream, int *buffer_depth);

/** @brief Set nr of continuous RAW frames to use.
 *
 * @param[in]	stream The stream.
 * @param[in]	buffer_depth	Number of frames to set.
 * @return	IA_CSS_SUCCESS or error code upon error.
 *
 * Set the number of continuous frames to use during continuous modes.
 */
enum ia_css_err
ia_css_stream_set_buffer_depth(struct ia_css_stream *stream, int buffer_depth);

/** @brief Get number of continuous RAW frames to use.
 * @param[in]	stream The stream.
 * @param[out]	buffer_depth The number of frames to use
 * @return	IA_CSS_SUCCESS or IA_CSS_ERR_INVALID_ARGUMENTS
 *
 * Get the currently set number of continuous frames
 * to use during continuous modes.
 */
enum ia_css_err
ia_css_stream_get_buffer_depth(struct ia_css_stream *stream, int *buffer_depth);

/* ===== CAPTURE ===== */

/** @brief Configure the continuous capture
 *
 * @param[in]	stream		The stream.
 * @param[in]	num_captures	The number of RAW frames to be processed to
 *				YUV. Setting this to -1 will make continuous
 *				capture run until it is stopped.
 *				This number will also be used to allocate RAW
 *				buffers. To allow the viewfinder to also
 *				keep operating, 2 extra buffers will always be
 *				allocated.
 *				If the offset is negative and the skip setting
 *				is greater than 0, additional buffers may be
 *				needed.
 * @param[in]	skip		Skip N frames in between captures. This can be
 *				used to select a slower capture frame rate than
 *				the sensor output frame rate.
 * @param[in]	offset		Start the RAW-to-YUV processing at RAW buffer
 *				with this offset. This allows the user to
 *				process RAW frames that were captured in the
 *				past or future.
 * @return			IA_CSS_SUCCESS or error code upon error.
 *
 *  For example, to capture the current frame plus the 2 previous
 *  frames and 2 subsequent frames, you would call
 *  ia_css_stream_capture(5, 0, -2).
 */
enum ia_css_err
ia_css_stream_capture(struct ia_css_stream *stream,
			int num_captures,
			unsigned int skip,
			int offset);

/** @brief Specify which raw frame to tag based on exp_id found in frame info
 *
 * @param[in]	stream The stream.
 * @param[in]	exp_id	The exposure id of the raw frame to tag.
 *
 * @return			IA_CSS_SUCCESS or error code upon error.
 *
 * This function allows the user to tag a raw frame based on the exposure id
 * found in the viewfinder frames' frame info.
 */
enum ia_css_err
ia_css_stream_capture_frame(struct ia_css_stream *stream,
			unsigned int exp_id);

/* ===== VIDEO ===== */

/** @brief Send streaming data into the css input FIFO
 *
 * @param[in]	stream	The stream.
 * @param[in]	data	Pointer to the pixels to be send.
 * @param[in]	width	Width of the input frame.
 * @param[in]	height	Height of the input frame.
 * @return	None
 *
 * Send streaming data into the css input FIFO. This is for testing purposes
 * only. This uses the channel ID and input format as set by the user with
 * the regular functions for this.
 * This function blocks until the entire frame has been written into the
 * input FIFO.
 *
 * Note:
 * For higher flexibility the ia_css_stream_send_input_frame is replaced by
 * three separate functions:
 * 1) ia_css_stream_start_input_frame
 * 2) ia_css_stream_send_input_line
 * 3) ia_css_stream_end_input_frame
 * In this way it is possible to stream multiple frames on different
 * channel ID's on a line basis. It will be possible to simulate
 * line-interleaved Stereo 3D muxed on 1 mipi port.
 * These 3 functions are for testing purpose only and can be used in
 * conjunction with ia_css_stream_send_input_frame
 */
void
ia_css_stream_send_input_frame(const struct ia_css_stream *stream,
			       const unsigned short *data,
			       unsigned int width,
			       unsigned int height);

/** @brief Start an input frame on the CSS input FIFO.
 *
 * @param[in]	stream The stream.
 * @return	None
 *
 * Starts the streaming to mipi frame by sending SoF for channel channel_id.
 * It will use the input_format and two_pixels_per_clock as provided by
 * the user.
 * For the "correct" use-case, input_format and two_pixels_per_clock must match
 * with the values as set by the user with the regular functions.
 * To simulate an error, the user can provide "incorrect" values for
 * input_format and/or two_pixels_per_clock.
 */
void
ia_css_stream_start_input_frame(const struct ia_css_stream *stream);

/** @brief Send a line of input data into the CSS input FIFO.
 *
 * @param[in]	stream		The stream.
 * @param[in]	data	Array of the first line of image data.
 * @param	width	The width (in pixels) of the first line.
 * @param[in]	data2	Array of the second line of image data.
 * @param	width2	The width (in pixels) of the second line.
 * @return	None
 *
 * Sends 1 frame line. Start with SoL followed by width bytes of data, followed
 * by width2 bytes of data2 and followed by and EoL
 * It will use the input_format and two_pixels_per_clock settings as provided
 * with the ia_css_stream_start_input_frame function call.
 *
 * This function blocks until the entire line has been written into the
 * input FIFO.
 */
void
ia_css_stream_send_input_line(const struct ia_css_stream *stream,
			      const unsigned short *data,
			      unsigned int width,
			      const unsigned short *data2,
			      unsigned int width2);

/** @brief Send a line of input embedded data into the CSS input FIFO.
 *
 * @param[in]	stream     Pointer of the stream.
 * @param[in]	format     Format of the embedded data.
 * @param[in]	data       Pointer of the embedded data line.
 * @param[in]	width      The width (in pixels) of the line.
 * @return		None
 *
 * Sends one embedded data line to input fifo. Start with SoL followed by
 * width bytes of data, and followed by and EoL.
 * It will use the two_pixels_per_clock settings as provided with the
 * ia_css_stream_start_input_frame function call.
 *
 * This function blocks until the entire line has been written into the
 * input FIFO.
 */
void
ia_css_stream_send_input_embedded_line(const struct ia_css_stream *stream,
			      enum ia_css_stream_format format,
			      const unsigned short *data,
			      unsigned int width);

/** @brief End an input frame on the CSS input FIFO.
 *
 * @param[in]	stream	The stream.
 * @return	None
 *
 * Send the end-of-frame signal into the CSS input FIFO.
 */
void
ia_css_stream_end_input_frame(const struct ia_css_stream *stream);

/** @brief send a request flash command to SP
 *
 * @param[in]	stream The stream.
 * @return	None
 *
 * Driver needs to call this function to send a flash request command
 * to SP, SP will be responsible for switching on/off the flash at proper
 * time. Due to the SP multi-threading environment, this request may have
 * one-frame delay, the driver needs to check the flashed flag in frame info
 * to determine which frame is being flashed.
 */
void
ia_css_stream_request_flash(struct ia_css_stream *stream);

/** @brief Configure a stream with filter coefficients.
 *  	   @deprecated {Replaced by
 *  				   ia_css_pipe_set_isp_config_on_pipe()}
 *
 * @param[in]	stream The stream.
 * @param[in]	config	The set of filter coefficients.
 * @param[in]   pipe Pipe to be updated when set isp config, NULL means to
 *		   update all pipes in the stream.
 * @return		IA_CSS_SUCCESS or error code upon error.
 *
 * This function configures the filter coefficients for an image
 * stream. For image pipes that do not execute any ISP filters, this
 * function will have no effect.
 * It is safe to call this function while the image stream is running,
 * in fact this is the expected behavior most of the time. Proper
 * resource locking and double buffering is in place to allow for this.
 */
enum ia_css_err
ia_css_stream_set_isp_config_on_pipe(struct ia_css_stream *stream,
			     const struct ia_css_isp_config *config,
			     struct ia_css_pipe *pipe);

/** @brief Configure a stream with filter coefficients.
 *  	   @deprecated {Replaced by
 *  				   ia_css_pipe_set_isp_config()}
 * @param[in]	stream	The stream.
 * @param[in]	config	The set of filter coefficients.
 * @return		IA_CSS_SUCCESS or error code upon error.
 *
 * This function configures the filter coefficients for an image
 * stream. For image pipes that do not execute any ISP filters, this
 * function will have no effect. All pipes of a stream will be updated.
 * See ::ia_css_stream_set_isp_config_on_pipe() for the per-pipe alternative.
 * It is safe to call this function while the image stream is running,
 * in fact this is the expected behaviour most of the time. Proper
 * resource locking and double buffering is in place to allow for this.
 */
enum ia_css_err
ia_css_stream_set_isp_config(
	struct ia_css_stream *stream,
	const struct ia_css_isp_config *config);

/** @brief Get selected configuration settings
 * @param[in]	stream	The stream.
 * @param[out]	config	Configuration settings.
 * @return		None
 */
void
ia_css_stream_get_isp_config(const struct ia_css_stream *stream,
			     struct ia_css_isp_config *config);

/** @brief allocate continuous raw frames for continuous capture
 * @param[in]	stream The stream.
 * @return IA_CSS_SUCCESS or error code.
 *
 *  because this allocation takes a long time (around 120ms per frame),
 *  we separate the allocation part and update part to let driver call
 *  this function without locking. This function is the allocation part
 *  and next one is update part
 */
enum ia_css_err
ia_css_alloc_continuous_frame_remain(struct ia_css_stream *stream);

/** @brief allocate continuous raw frames for continuous capture
 * @param[in]	stream The stream.
 * @return	IA_CSS_SUCCESS or error code.
 *
 *  because this allocation takes a long time (around 120ms per frame),
 *  we separate the allocation part and update part to let driver call
 *  this function without locking. This function is the update part
 */
enum ia_css_err
ia_css_update_continuous_frames(struct ia_css_stream *stream);

/** @brief ia_css_unlock_raw_frame . unlock a raw frame (HALv3 Support)
 * @param[in]	stream The stream.
 * @param[in]   exp_id exposure id that uniquely identifies the locked Raw Frame Buffer
 * @return      ia_css_err IA_CSS_SUCCESS or error code
 *
 * As part of HALv3 Feature requirement, SP locks raw buffer until the Application
 * releases its reference to a raw buffer (which are managed by SP), this function allows
 * application to explicitly unlock that buffer in SP.
 */
enum ia_css_err
ia_css_unlock_raw_frame(struct ia_css_stream *stream, uint32_t exp_id);

/** @brief ia_css_en_dz_capt_pipe . Enable/Disable digital zoom for capture pipe
 * @param[in]   stream The stream.
 * @param[in]   enable - true, disable - false
 * @return      None
 *
 * Enables or disables digital zoom for capture pipe in provided stream, if capture pipe
 * exists. This function sets enable_zoom flag in CAPTURE_PP stage of the capture pipe.
 * In process_zoom_and_motion(), decision to enable or disable zoom for every stage depends
 * on this flag.
 */
void
ia_css_en_dz_capt_pipe(struct ia_css_stream *stream, bool enable);
#endif /* __IA_CSS_STREAM_PUBLIC_H */