documentation.tex

BlackFin处理器视频演示代码

\documentclass[11pt]{article}

\usepackage[latin1]{inputenc}
\usepackage{graphicx}
\usepackage{hyperref}
\usepackage[all]{xy}
\usepackage{tabularx}

\setlength{\parindent}{0pt}
\setlength{\parskip}{1ex}

\begin{document}

\title{AnalogVideo device driver documentation}
\author{Zlatan Stanojevi\'c}
\date{\today}
\maketitle

\tableofcontents

\clearpage

\section{Introduction}
This is the documentation of the AnalogVideo device driver for the Analog Devices' Blackfin DSP.

\paragraph{Targeted hardware:}  The device driver is intended for (but not limited to) the use with the CM-BF533, CM-BF537 and CM-BF561 core modules.  The driver is recommended to be used in conjunction with an EVAL-BF5xx Blackfin Evaluation Board and the EXT-BF5xx-Video Blackfin Extender Board.  Other configurations, such as the Analog Devices EZ-Kits, are reported to work but haven't been thoroughly tested.  The video interface chips currently supported are:
\begin{itemize}
\item ADV-7171 \emph{video encoder}
\item ADV-7183A and ADV-7183B \emph{video decoders}
\end{itemize}
The documentation of these chips is publicly available so there is no need to provide any detailed information on them here.


\paragraph{Software components:}  The device driver represents a thin abstraction layer and serves several functions:
\begin{enumerate}
\item One-time configuration and further interaction with the video interface chips via the either built-in (BF537) or emulated (BF533 and BF561) I$^2$C interface.
\item Abstraction of the processor's PPI and and DMA units.
\item The additional \emph{blt} module provides easy handling of block transfers between two dimensional buffers.
\end{enumerate}
These functions are very loosely integrated in order to provide a maximum of flexibility.  E.g. You can use only the AnalogVideo's I$^2$C configuration functions and provide Your own PPI/DMA handling routines.
Figure \ref{fig:module-dependencies} shows the dependency graph between the AnalogVideo device driver and other software modules.
\begin{figure}[h]
\begin{center}
\begin{displaymath}
\framebox{
\xymatrix{
			& 	\txt{analog\_video} \ar[ld]\ar[d]\ar[rd]\ar[r]	&	\txt{blt} \ar[d]\ar[rd]  	\\
\txt{i2c}			&	\txt{PPIConfig, ppi\_global}		&	\txt{adi\_int}	&	\txt{adi\_dma}	
}
}
\end{displaymath}
\caption{Module dependency graph}
\label{fig:module-dependencies}
\end{center}
\end{figure}


\section{File structure and project requirements}

\subsection{Source files}

Table \ref{tab:files} displays the source files that are considered part of the AnalogVideo device driver.

\begin{table}[h]
\caption{Source files}
\begin{center}
\begin{tabular}{|l|l|}
\hline
Filename & Purpose \\\hline\hline
\multicolumn{2}{|c|}{\bf Driver files} \\\hline
\tt analog\_video.c 		& configuring devices and PPI/DMA \\\hline
\tt analog\_video.h 		& interface definition for {\tt analog\_video.c}\\\hline
\tt video\_boards.h 		& input socket configuration for supported boards\\\hline	
\tt blt.c		 			& service functions for working with 2D surfaces\\\hline
\tt blt.h		 			& interface definition for {\tt blt.c}\\\hline
\tt dma.h		 			& additional macros for internal use\\\hline
\tt itu-r-656.h 			& service functions for generating ITU-R-656 syncs\\\hline\hline
\multicolumn{2}{|c|}{\bf Miscellaneous files} \\\hline
\tt main.c 					& test environment \\\hline	
\tt testpic.c 				& 720 by 576 test picture written as C-array \\\hline	
\tt video\_example\_bf533.c & example configuration for CM-BF533 \\\hline	
\tt video\_example\_bf537.c & example configuration for CM-BF537 \\\hline	
\tt video\_example\_bf561.c & example configuration for CM-BF561 \\\hline
\end{tabular}
\end{center}
\label{tab:files}
\end{table}%

\subsection{Initialization procedure}

Before employing the device driver three steps in the program must be taken:
\begin{enumerate}
\item adjust core and system clocks (CCLK \& SCLK) as needed by DMA,
\item initialize the {\tt adi\_int}-module and
\item initialize the I$^2$C driver.
\end{enumerate}
See the {\tt main.c} file for an exemplary setup.  Please note that before modifying the clock frequencies on a BF561 the second core must be put to sleep.  Note also that the I$^2$C setup is likely to be different for each core module.

\subsection{I$^2$C driver}

The AnalogVideo device driver is intended to be used with the I$^2$C driver shipped with Blacksheep VDK.  Other drivers can be substituted as long as they obey the requirements described below.  However other I$^2$C haven't been tested with AnalogVideo.

A driver that is to be used with the AnalogVideo device driver has to expose the following interface:
\begin{verbatim}
typedef struct
{
    unsigned char address, value;
} I2CConfig;

void I2CControl( unsigned char hwid, 
                 I2CConfig *config, 
                 short len );

void I2CStatus( unsigned char hwid, 
                I2CConfig *config, 
                short len );
\end{verbatim}
\begin{description}
\item[I2CControl] Sets the registers of the device specified by \emph{hwid} according to the supplied list of \emph{address-value} pairs \emph{config}.  \emph{len} specifies the list's length.
\item[I2CStatus] Retrieves values from the registers of the device specified by \emph{hwid} according to the \emph{address} elements  of \emph{config} and writes the values into the corresponding \emph{value} elements.  Again, \emph{len} specifies the list's length.
\end{description}
The two functions are supposed to block execution until the I$^2$C transfer is completed.

\textbf{Please note:} Special care must be taken when addressing the Analog Devices' video interface chips via I$^2$C.  As with most devices the first byte transmitted after the device's bus address is a pointer to one of the device's internal registers followed by the register values with each transmitted value incrementing the pointer.  However after receiving the first register value ADI's chips refuse to acknowledge any further bytes.  This anomaly can be worked around by transmitting one byte for each address; that means the transmissions in the \emph{config} parameter of the above functions must not be grouped into fewer transmissions.

\subsection{Limitations}
\paragraph{SD-RAM bottlenecks}  Because of the huge amounts of raw data that come along with uncompressed video, the driver is most likely to have and operate on buffers in SD-RAM.  Please note that SD-RAM read/write operations are slow requiring many cycles.  With too much of traffic in and out of the SD-RAM, parallel DMA operations will fail to finish in time and visual artifacts will become apparent.

\paragraph{Pixel formats}  The analog video signal and thus its digital representation impose a certain format for storing pixel data.  The colors are represented by YUV tuples which themselves are arranged in a two-pixel U-Y-V-Y pattern, effectively reducing the density of color information by two.  The AnalogVideo device driver is not consequently holds on to this format; there is no way to use the driver to perform pixel conversions.




\section{Driver functionality}

\subsection{Ports description}

The Blackfin processor and the video interface chips are connected by means of the I$^2$C bus and an eight bit wide parallel port with separate port clock.  The I$^2$C is for configuring the devices, the parallel port is for video data streaming.  The driver uses the ITU-R-656 format for transferring the digital video data.  The advantage of this format is that the video synchronization is achieved by symbols embedded into the digital video stream thus requiring no external synchronization signals.  The ITU-R-656's synchronization symbols are four-byte sequences, where the the last of the four bytes contains flags such as
\begin{itemize}
\item start of active video (SAV)
\item end of active video (EAV)
\item blanking
\item field selection (field 1 or field 2)
\end{itemize}
An introduction to the ITU-R-656 format can be found in the Blackfin Processors' reference manuals.

Although modes other than ITU-R-656 are supported by the processor and the video interface chips, the driver only supports ITU-R-656.  The ITU-R-656 mode is the most economical in terms of pin usage and wiring as it doesn't require the synchronization to be done via additional electrical signals.  Another advantage is that the Blackfin's parallel peripheral interface (PPI) has support for ITU-R-656 streams built in and so extracting a picture from a ITU-R-656 stream requires no overhead.  Anyway the current versions of the video extender board only support ITU-R-656 mode only.

The port width of eight bit requires a port clock of approximately 27MHz to be used.  The clock on the video extender board is fed by two possible sources:
\begin{itemize}
\item the ADV-7183A/B (video decoder),
\item a 27MHz on board oscillator.
\end{itemize}
Although the video decoder itself uses the 27MHz as reference clock the decoder's clock output differs from the reference oscillator and is synchronized to the analogous input signal.  Therefore data transfer between the video decoder and the processor must always use the decoders output clock, for using the reference oscillator will result in sample errors.  The video encoder uses the reference clock as input clock.  Figure \ref{fig:clock} shows the constellation.
\begin{figure}[h]
\begin{center}
\includegraphics[width=0.8\textwidth]{clock}
\caption{{\bf Parallel ports configuration}}
\label{fig:clock}
\end{center}
\end{figure}
Note that the port clock is the encoder's only time reference; this implies that a highly stable port clock is required otherwise the encoder's output will be corrupted.


\subsection{Initialization procedures}

The AnalogVideo device driver is initialized by calling the \verb|av_base_init| function.  The function sets the IVG for PPI and DMA events.  At this point the video interface chips are still not initialized.

\subsubsection{Video encoder setup}

Configuring the the video encoder is quite straightforward.  The video encoder setup basically consists of calling the \verb|av_setup_output| function.  Information such as wiring of the RESET and BLANK pins as well as the output video standard are passed to the function call.  The configuration of the encoder's DACs is tailored to the video extender board meaning that all three available physical connections (two CVBS and one S-Video) feed the same video signal.

In case the processor and the encoder are out of sync, the encoder's timing unit can be reset by calling \verb|av_reset_output_timing|.


\subsubsection{Video decoder setup}

The configuration of the video decoder is a more complex issue.  First the function \verb|av_init_input| must be called.  Again the wiring of RESET and OE must be passed to the call.  Even if You don't mean to use the decoder in Your application, if the decoder is present, you must call this function and set the additional \verb|pa_bDisable| parameter to \verb|true|.  This turns off the decoder's parallel port.  The main purpose of the \verb|av_init_input| function is to detect which version of the decoder chip is present and to initialize it accordingly.

The video decoder supports a total of 16 recommended configurations for the input multiplexer -- 11 CVBS, 3 YC (S-Video) and 2 YPrPb configurations.  However the inputs that can practically be used on a board, form only a subset of these configurations.  To select valid input configurations the driver uses 16-bit masks.  These masks are shown in Table \ref{tab:mask}

\begin{table}[h]
  \caption{Input masks}\label{tab:mask}
\begin{center}
 \begin{tabular}{|l|l|l|l|}
\hline
Mask name 		& Mask Value	& Signal type	& Input \\\hline\hline
 \verb"AV_CVBS_AIN1" &    \verb"0x0001"
 &  Composite  &  AIN1 \\\hline
 \verb"AV_CVBS_AIN2" &    \verb"0x0002"
 &  Composite  &  AIN2 \\\hline
 \verb"AV_CVBS_AIN3" &    \verb"0x0004"
 &  Composite  &  AIN3 \\\hline
 \verb"AV_CVBS_AIN4" &    \verb"0x0008"
 &  Composite  &  AIN4 \\\hline
 \verb"AV_CVBS_AIN5" &    \verb"0x0010"
 &  Composite  &  AIN5 \\\hline
 \verb"AV_CVBS_AIN6" &    \verb"0x0020"
 &  Composite  &  AIN6 \\\hline
 \verb"AV_YC_AIN14" &     \verb"0x0040"
 &  YC  &  AIN1 and AIN4 \\\hline
 \verb"AV_YC_AIN25" &     \verb"0x0080"
 &  YC  &  AIN2 and AIN5 \\\hline
 \verb"AV_YC_AIN36" &     \verb"0x0100"
 &  YC  &  AIN3 and AIN6 \\\hline
 \verb"AV_YPrPb_AIN145" & \verb"0x0200"
 &  YPrPb  &  AIN1, AIN4 and AIN5 \\\hline
 \verb"AV_YPrPb_AIN236" & \verb"0x0400"
 &  YPrPb  &  AIN2, AIN3 and AIN6 \\\hline
 \verb"AV_CVBS_AIN7" &    \verb"0x0800"
 &  Composite  &  AIN7 \\\hline
 \verb"AV_CVBS_AIN8" &    \verb"0x1000"
 &  Composite  &  AIN8 \\\hline
 \verb"AV_CVBS_AIN9" &    \verb"0x2000"
 &  Composite  &  AIN9 \\\hline
 \verb"AV_CVBS_AIN10" &   \verb"0x4000"
 &  Composite  &  AIN10 \\\hline
 \verb"AV_CVBS_AIN11" &   \verb"0x8000"
 &  Composite  &  AIN11 \\\hline
 \verb"AV_CVBS_ALL" &     \verb"0xf83f"
 &  Composite & all \\\hline
 \verb"AV_YC_ALL" &       \verb"0x01c0"
 &  YC & all \\\hline
 \verb"AV_YPrPb_ALL" &    \verb"0x0600"
 &  YPrPb & all \\\hline
\end{tabular}
\end{center}
\end{table}

The easiest way to get the video decoder decode something is to call the function \verb|av_find_input| with a mask of allowed inputs.  The function will let the decoder cycle through the selected inputs and look for an input signal.  This procedure can take several seconds to finish.  If one single input source has been found the driver will tell the decoder to use this one.  If there's more than one source or no sources at all, the function will return with an error code.

If You want to omit input source auto-detection and specify the decoder's input directly, use the \verb|av_configure_input| function.  This function is also implicitly called by \verb|av_find_input| after it finishes the source detection.  When the input source is configured, the driver automatically reduces the decoder's power consumption by turning off the ADCs that aren't needed -- see Table \ref{tab:adc_pow}.

\begin{table}[h]
\caption{ADC recruitment}
\begin{center}
\begin{tabular}{|c|c|}
\hline
Input 	& ADCs needed \\\hline\hline
CVBS	& 1 \\\hline
YC (S-Video) & 2 \\\hline
YPrPb & 3 \\\hline
\end{tabular}
\end{center}
\label{tab:adc_pow}
\end{table}%

To determine whether the decoder is currently locked onto an analogous input signal the function \verb|av_input_locked| can be used.


\subsection{Working with the driver}

\subsubsection{Video standards}
\label{sec:standard}
The driver is capable of working with multiple video standards.  Support for PAL and NTSC\footnote{NTSC support not thoroughly tested} is built-in but other standards can be easily added -- even without having to modify the driver's code.

The driver stores all the data necessary to describe a video standard in \verb|AVStandard| structures.  The layout of the structure is presented in Table \ref{tab:standard}

\begin{table}%[h]
\caption{AVStandard structure}