documentation.tex

BlackFin处理器视频演示代码

\begin{center}
\begin{tabularx}{\textwidth}{|l|X|}\hline
    \verb|long width|                    & active video width\\\hline
    \verb|long height|                   & active video height\\\hline
    \verb|long pixel_stride|             & address difference between two neighbouring pixels\\\hline
    \verb|long line_stride|              & address difference between two line starts\\\hline
    \verb|long field_stride|             & address difference between two field starts\\\hline
    \verb|long frame_stride|             & address difference between two frame starts\\\hline
    \verb|long active_video1_offset|     & active video start address offset in first field\\\hline
    \verb|long active_video2_offset|     & active video start address offset in second field\\\hline
    \verb|long active_video_line_size|   & size in bytes of an active video line\\\hline
    \verb|long blank_line_size|          & size in bytes of blanking region in a line\\\hline
    \verb|long total_lines|              & total number of lines (active \& blank)\\\hline
    \verb|struct| & \\
    \tt \{ & \\
    \qquad \verb|long line;|                 & \qquad line where flags change\\
    \qquad \verb|u32 flags;|                 & \qquad new flags or'ed together\\
    \tt \} flags[7]                    & flag change positions\\\hline
\end{tabularx}
\end{center}
\label{tab:standard}
\end{table}%

\verb|flags| is an array of tuples, each containing the line number\footnote{zero based numbering} where the field flags and vertical blanking flags should change.  In Table \ref{tab:exa_pal} is given an example for PAL.

\begin{table}[h]
\caption{PAL flags}
\begin{center}
  \begin{tabular}{|l|r@{~-~}r|c|c|}
    \hline
    Code & \multicolumn{2}{c|}{Lines} & Field & V-Blank \\ 
    \hline\hline
    \tt \{ 0,   FIELD\_1 | VERTICAL\_BLANK \}, & 0 & 21 & 1 & $\times$ \\ 
    \hline
    \tt \{ 22,  FIELD\_1                   \}, & 22 & 309 & 1 & \\ 
    \hline
    \tt \{ 310, FIELD\_1 | VERTICAL\_BLANK \}, & 310 & 311 & 1 & $\times$  \\ 
    \hline
    \tt \{ 312, FIELD\_2 | VERTICAL\_BLANK \}, & 312 & 334 & 2 & $\times$  \\ 
    \hline
    \tt \{ 335, FIELD\_2                   \}, & 335 & 622 & 2 & \\ 
    \hline
    \tt \{ 623, FIELD\_2 | VERTICAL\_BLANK \}, & 623 & 624 & 2 & $\times$  \\ 
    \hline
    \tt \{ -1, 0 \} & \multicolumn{4}{c|}{sentinel value} \\
    \hline
  \end{tabular}
\end{center}
\label{tab:exa_pal}
\end{table}%

The built-in standard definitions are accessed through the global pointers \verb|g_pPALstd| and \verb|g_pNTSCstd|.  Use the \verb|g_pInvalidStd| pointer to explicitly pass an invalid structure and the dynamic pointer \verb|g_pInputStd| to pass the same standard as detected by the video decoder chip.


\subsubsection{Video streams}

The driver uses DMA to handle the huge amounts of data required to transmit uncompressed video.  Generally the DMA transfers video data between the PPI(s) and buffers resident in the processor's memory.  The interface for both PPI to memory and memory to PPI transfers is unified and consists of these functions:
\begin{itemize}
\item \verb|av_open|
\item \verb|av_close|
\item \verb|av_start|
\item \verb|av_restart|
\item \verb|av_stop|
\end{itemize}
along with two helper functions
\begin{itemize}
\item \verb|av_tell|
\item \verb|av_init_matrix|
\end{itemize}
As the video input and output channels cannot be shared between threads, the functions \verb|av_open| and \verb|av_close| gain exclusive access to one channel and release it respectively.  The functions \verb|av_close|, \verb|av_start| and \verb|av_restart| control the video streams and operate only on open channels.

The system supports only as much channels as there are PPIs available with one channel per PPI.  The channels are numbered starting from zero.

When opening a stream the source/target buffer's address must be specified; apart from that several decisions must be made:
\begin{description}
\item[Direction:] (\verb|pa_bOutput|) determines if data should be transferred from buffer to PPI or vice versa
\item[Double buffering:] (\verb|pa_bDoubleBuffer|) should the buffer contain one or two consecutive frames? Mind the buffer-size!
\item[Buffer matrix:] (\verb|pa_bBufferMatrix|) a buffer matrix contains also sync patterns and blanking intervals not seen on the screen and is interlaced (see below)
\end{description}
Not all combinations of the above parameters are allowed.  Table \ref{tab:combinations} shows the allowed combinations.

\begin{table}[h]
\caption{Allowed video stream configurations}
\begin{center}
\begin{tabular}{|l|c|c|c|c|}
\hline
\verb|pa_bOutput| 			& $\phantom{\times}$	& 			& 			& $\times$ \\\hline
\verb|pa_bDoubleBuffer| 	& 						& $\times$	& 			& 			\\\hline
\verb|pa_bBufferMatrix| 	& 						& 			& $\times$	& $\times$ \\\hline
\end{tabular}
\end{center}
\label{tab:combinations}
\end{table}%

Additionally two event handlers must be specified: one for per-frame events and one for error conditions.

In case Your Application works uses double buffers (\verb"pa_bDoubleBuffer" is true), use the \verb"av_tell" function to find out which of the two frames the driver is currently reading from/writing to; the unused frame (not the one \verb"av_tell" returns) can be used safely by Your application.

Unless the source/target buffer is a buffer matrix the picture is un-interlaced.

\subsubsection{Buffer matrices}
In contrast to a plain surface, which is usually used to store pictures, where in memory the last pixel of line $n$ is immediately followed by the first pixel of line $n+1$, the data in a buffer matrix is arranged the way the CRT beam moves on the screen.

The use of buffer matrices is necessary for video output as the Blackfin's PPI only supports decoding of ITU-R-656 stream, not encoding.  Therefore all the parts of the stream that are omitted by the PPI at input must be added at output, which results in a buffer matrix.

Figure \ref{fig:buffer_matrix} shows how data is arranged in a buffer matrix. As can be seen from the figure buffer matrices always contain interlaced data.

\begin{figure}[htbp]
\begin{center}
\includegraphics[width = .6\textwidth]{buffer_matrix}\\
Taken from the BF561 hardware reference manual
\caption{Buffer matrix}
\label{fig:buffer_matrix}
\end{center}
\end{figure}

The blanking fields contain the pattern \verb|0x80108010| which represents \emph{black} pixels. The transitions between active video an blanking have the blank pixels replaced by ITU-R-656 sync patterns.

Although working with buffer matrices seems complicated it is greatly simplified by the \emph{blt}-functions.  To generate an empty buffer matrix in memory call the \verb|av_init_matrix| function.  The size of a buffer matrix is roughly 1MByte but strongly depends on the video standard (NTSC, PAL, \ldots).


\subsubsection{Block transfers}
To simplify working with different kinds of buffers (interlaced buffers, buffer matrices, \ldots) the driver offers the \emph{blt} module.  Essentially this module contains two main functions
\begin{itemize}
\item \verb|blt_init| called once to perform basic initialization
\item \verb|blt| performs the transfers
\end{itemize}
and several functions for generating and shrinking buffer descriptors
\begin{itemize}
\item \verb|blt_makeLinearSurface| 
\item \verb|blt_makeInterlacedSurface| same as above but interlaced
\item \verb|blt_makeFilledSurface| uses a color sample to generate a uniformly colored surfaces
\item \verb|blt_shrink| shrinks the image size by a whole number
\item \textbf{Note:} Surface descriptors for buffer matrices are obtained through the \verb|av_init_matrix| function.
\end{itemize}
It's important to understand that these functions do nothing more than generate/modify descriptors (structures containing information \emph{about} the buffers) not the buffers themselves.  E.g. if You shrink a buffer by let's say two, You simply tell the driver to omit every second pixel, but the omitted pixels still reside in memory.

The heart of the blt module is the \verb|BLTBufferDesc| structure which contains all the information necessary to provide a unified handling for all kinds of buffers.  Table \ref{tab:blt_descriptor} shows its contents.

\begin{table}[h]
\caption{BLTBufferDesc structure}
\begin{center}
\begin{tabularx}{\textwidth}{|l|X|}
\hline
     \verb|void *start_addr|                 & start address of buffer\\\hline
     \verb|unsigned short width|             & surface width\\\hline
     \verb|unsigned short height|            & surface height\\\hline
     \verb|unsigned long offset|             & address ofset of first visible pixel\\\hline
     \verb|unsigned short pixel_stride|      & address diffecence between neighbouring pixels\\\hline
     \verb|unsigned short line_stride|       & address difference between two consecutive line starts\\\hline
     \verb|unsigned long field_stride|       & address difference between the start of field 1 and 2\\\hline
     \verb|unsigned short interlaced|        & interlaced surface\\\hline
\end{tabularx}
\end{center}
\label{tab:blt_descriptor}
\end{table}%

The blt module uses ADI's \emph{adi\_dma} module to perform the transfer operations via DMA.  The module recruits a source-destination pair of MDMA channels for its transfers.  The \verb|blt| function is capable of selecting arbitrary rectangles from the source image and transfering it to any point in the destination image.  The function performs no boundary checks, so it's up to Your application to assure that the boundaries are kept.

\section{Driver reference}
For a detailed description of the driver interface see the reference manual.  The reference manual is generated using Doxygen; You can extract it from the source files by \verb|cd|'ing to the \verb|analog_video| directory and running \verb|doxygen| from there.  Use the Doxywizard to alter the settings for the generation of the source documentation.  Output can be generated in HTML, \LaTeX, RTF and other formats.

\section{Extending the driver}
The driver was made to be as extensible as possible.  In the following some examples will be picked how the driver might be extended.

\subsection{Extending processor support}
First look for a section in the \verb|analog_video.c| file marked as:
\begin{verbatim}
/*************** Cross-platform support ****************/
 ...
/*******************************************************/
\end{verbatim}
There You will find definitions already written for the BF533, BF537 and BF561.  To add another processor extend the \verb|#if ... #else ... #endif| construct accordingly.  If the processor is capable of 32-bit PPI and DMA operations\footnote{the BF561 is, the BF533 and BF537 are not} You may add the line
\begin{verbatim}
#define __AV32__
\end{verbatim}
to enable 32-bit support; otherwise You must type
\begin{verbatim}
#undef __AV32__
\end{verbatim}
to make sure the driver stays in 16-bit mode.

Next You should declare the internal DMA handlers.  This is done by adding the lines
\begin{verbatim}
DECLARE_DMA_HANDLER( 0 );
DECLARE_DMA_HANDLER( 1 );
 ...
DECLARE_DMA_HANDLER( n-1 );
\end{verbatim}
where $n$ is the number of PPIs on Your processor.

The next thing to do is to declare an array of status descriptors; start with
\begin{verbatim}
static PPIStat g_aPPIstat[] = 
{
 ...
}
\end{verbatim}
Within this array You must now put a descriptor for each PPI present on the processor starting with the lowest numbered.\\
{\tt
\begin{tabular}{@{}l}
   \verb|{|\\
\qquad        0,\\
\qquad        0,\\
\qquad        {\it ADI peripheral id for this PPI's error interrupts},\\
\qquad        {\it 1 for shared PPI error, else 0},\\
\qquad        \verb|DMA_HANDLER|( {\it PPI number} ),\\
\qquad        0,\\
\qquad        0,\\
\qquad        0\\
    \verb|}|,
\end{tabular}
}\\
Only three values are important here, the others must be zero.   The ADI peripheral ids are listed in \verb|adi_int.h|; pick the one that corresponds to the PPI the descriptor is assigned to.  On some processors\footnote{e.g. BF537} the the error interrupts share a common peripheral id; in this case use that common peripheral id and set the parameter below to 1.  The third relevant parameter is the DMA handler; here You must type \verb"DMA_HANDLER( ... )" and pass the number of the PPI which belongs to that descriptor.

Finally the previously declared handlers must be defined.  To do this add the lines
\begin{verbatim}
DEFINE_DMA_HANDLER( 0 );
DEFINE_DMA_HANDLER( 1 );
 ...
DEFINE_DMA_HANDLER( n-1 );
\end{verbatim}
for a total of $n$ PPIs.

Of course the other modules that AnalogVideo depends on, like the I$^2$C and PPI drivers, must also support the processor.


\subsection{Adding support for other video standards}
To perform this simple extension first find the section at the beginning of \verb"analog_video.c" where the video standard descriptors are placed.  Add Your standard descriptor there, see section \ref{sec:standard} for further information on the descriptors.  Finally define a pointer to the descriptor (a few lines below) and declare it in \verb"analog_video.h".


\subsection{Using other video interface hardware}
This is a rather difficult task.  The AnalogVideo driver was developed to support the ADV-7171 encoder and the ADV-7183 decoder.  There's no guarantee that the driver can be ported to other chips without having to rewrite half the driver code.  However following statements can be made:
\begin{itemize}
  \item The driver can be split in three parts: the configuration, the PPI/DMA interfacing and the block transfers.  Actually the only part that has to be modified is the configuration.  More precisely the following functions are affected and might have to be rewritten in the worst case:
  \begin{itemize}
     \item \verb"av_init_input",
     \item \verb"av_find_input",
     \item \verb"av_configure_input",
     \item \verb"av_input_locked",
     \item \verb"av_setup_output",
     \item \verb"av_reset_output_timing"
  \end{itemize}
  as well as the internal helper functions, definitions/macros and global variables used by these.
  \item Adapting the driver to support other encoders is much easier than the decoder case.  This is because the encoder setup is very likely to consist of a simple initialization sequence.  In this case only the configuration globals marked \begin{verbatim}
/****************** Encoder part *********************/
 ...
/*****************************************************/
\end{verbatim}
and the encoder's HWID have to be changed.
   \item Generally, other ADI's video interface chips are likely to behave similarly to the supported two.  Still there's no guarantee for that.
   \item A necessary condition for the driver to work with other video interface hardware at all is, of course, that the hardware supports the ITU-R-656 format.
\end{itemize}

\textbf{Conclusion:} If You really want to port the driver to other video hardware, You're probably better off with ADI's devices than with other.  However even ADI's devices can have properties or lack crucial features, which all together could render the porting process entirely impossible in the worst case.


\end{document}