readme.txt

用于TM1300/PNX1300系列DSP（主要用于视频处理）的设备库的源码

TriMedia Image Coprocessor Device Library
December 6, 1996

Introduction

The image co-processor (ICP) connects to the TM-1 DSP-CPU and other 
peripherals through the TM-1 on-chip data highway. The ICP reads data from 
SDRAM and can write to SDRAM or directly to PCI interface. 

The ICP device library provides a set of functions to access the ICP 
functionality. In particular, this library provides functions to:

Load the filter coeffcients from SDRAM. 
Scale and filter image data in horizontal and vertical direction.
Perform image format conversion from YUV to RGB.

The library functions provided here are independant of the operating system. 
Sample driver programs are provided with the library which serves as an 
example to the user to write his/her own functions.

The TM-1 funcitons can be broadly classified into two categories. First are 
the devices which require buffered input/output, for example, IIC, Audio in, 
Audio out, etc. The other category does not require any buffred input/output. 
This includes ICP, variable length decoder etc. It is, therefore, difficult to 
adhere to a general device library functions over all the peripherals, however, 
the ICP library is consistent with other devices in the following respect:

Includes standard TriMedia include files.
Provides Init() and Term() functions for software initialization and termination, 
and Open() and Close() functions for hardware initializations and terminations.
Demonstrate the library function usage with the so-called driver program.

Current Status

A set of functions and applications have been written and tested on TM-1. The 
programs work in polled as well as the interrupt mode. The programs work only on 
static images and have not been tested on continuous video.

Limitations

The user should be aware of the following limitations which are present wither 
due to the software or hardware limitations.

All addresses, or pointer to images, must be 64 bytes aligned. The results are 
not guaranteed to be correct otherwise.
For the vertical filter, the source stride must be a multiple of 64. The results 
are incorrect otherwise.
For the color conversion filter if the RGB output is sent to PCI and if the source 
stride is not a multiple of 64 then the output image may have speckles in it. If 
the source stride is a multiple of 64 then the speckles are reduced or completely 
eliminated.

The starting address of the micro code must be 128 bytes aligned. This is 
automatically done in the icpLoadMicroCode() function. If the micro code is 64 
bytes aligned then ICP may hang in continuous video.
At present, color conversion functions do not have horizontal or vertical scaling 
options in them. These will be included in the later version.

API

The ICP is used exclusively by the user who initializes it. It is only made 
accessible to other users when the control is terminated using the Term() 
function. Loading of the micro code is transparent to the user. It is loaded 
inside the icpOpen() functions. The user, however, will have to load the filter 
coefficients explicitly before starting any processing. This is done in order 
for the user to be able to change the coefficients for different filtering 
operations. 

Following function are included in the library.

Data Structures

The main data structure is a control block.

typedef struct {
  int owner;                	/* Task ID */
  int cont;		/* Cont=0 -> go to user defined interrupt routine. For future use. */
  int icpMode;              	/* 1: Initialize ICP with interrupt enable */
  int irqMode;              	/* 0: Level, 1: Edge */
  int priority;            	/* 0-7 */ 
  void (*icp_isr) (void);   	/* Pointer to the user interrupt service routine */
} ICP_CB;

General

icpInit
icpTerm
icpOpen
icpClose
icpReset
icpReadStatus
icpLoadCoeff
icpLoadMicroCode

Scaling and Filtering

icpMove
icpHorzFilter
icpVertFilter
icpYUV2RGB

Others

	viewImage

Function Description

int icpInit (ICP_CB *icb);
Software initializations.
Assign owner for usage
Set up the little endian or big endian mode
   return 0 for success
 
  Errors:   ICP_ERR_DEVICE_IN_USE
 
int icpTerm(int owner);
  Give up device ownership. Acknowledge done.
 
  return 0 on success
 
  Errors:  ICP_ERR_DEVICE_IN_USE
 
int icpOpen(ICP_CB *icb);
   Prepare ICP for operation. Hardware initializations.
 
Install interrupt handler, if necessary.
Require icp_init to be called first.
Load micro code.
 
   return 0 for success.
 
   Errors:   ICP_ERR_INIT_REQUIRED
	  ICP_ERR_DEVICE_IN_USE
	  ICP_ERR_LOAD_MICRO_CODE
 
int icpClose(ICP_CB *icb); 
  Hardware close.
 
Deinstall the interrupt handler.
 
  return 0 for success.
 
  Errors:	  ICP_ERR_DEVICE_IN_USE
	  ICP_ERR_DEVICE_NOT_OPEN

int icpReset (int owner);
  Resets ICP by:
 
  Clearing interrupts and reseting busy bit.
  After reset and icp_init is required.
 
  return 0 on succes.
 
  Errors:	  ICP_ERR_DEVICE_IN_USE
 
int icpReadStatus(void);
  Returns ICP status register.
 
int icpLoadCoeff(unsigned long *coeff);
 
  Loads ICP with filter coefficients.
  This is called only when changing coefficients.
  Starts ICP and return without waiting.
 
  Assumptions:
      - Micro code already loaded.
      - Coefficients may not be in SDRAM.
      - All other ICP controls are set and checked outside
 
  Returns 0 for success.
 
  Errors: 	ICP_ERR_COEFF_TABLE       (Coeffcients are outside the range [-512,511].
 

int icpLoadMicroCode(void);
    Load the micro_code as specified in the file at the compile time. 
 
    Micro code needs to be copied back to memory only once
    unless there is any self-modifying code.

    returns 0 for success.
 
    Errors can only occur at the compile time, where the specified file may not exist.

Scaling and Filtering

int icpMove(unsigned char *srcImage, 
                      int srcStride,
                      int height,
                      int width, 
 	      unsigned char *destImage, 
                      int destStride);

  Moves an image from *scrImage in SDRAM to *destImage in SDRAM. It is
  assumed that: 

Micro code is already loaded.
ICP is initialized and open.
Source image is copied back in memory.
 
  return 0 for success.
 
  Errors:	ICP_ERR_DEVICE_NOT_OPEN
	ICP_ERR_INIT_REQUIRED
	ICP_ERR_INVALID_HEIGHT
	ICP_ERR_INVALID_WIDTH
	ICP_ERR_INVALID_STRIDE
	ICP_ERR_ADDRESS_NOT_64_ALIGNED

int icpVertFilter(	unsigned char *srcImage,  	/* Address of the source image */
                    	int srcStride,            		/* Source stride, line offset  */
                    	int height,               		/* Source height           */
                    	int width,                		/* Source width            */
                    	unsigned char *destImage, 	/* Address of the dest. image  */
                    	int destHeight            		/* Height of the dest. image   */
                    	);

  Vertical filter and scale an image given in *scrImage in SDRAM to *destImage in SDRAM.
 
Important 
  For vertical filtering, srcStride should be a multiple of 64, otherwise
  the output is not guaranteed to be correct. It is assumed that:
 
Micro code is already loaded (automatically done in icp_open).
Filter coefficients are already loaded.
ICP is initialized and open.
Source image is copied back in memory.
Destination stride is the image width.
 
  return 0 for success.
 
  Errors:	  ICP_ERR_DEVICE_NOT_OPEN
	  ICP_ERR_INIT_REQUIRED
	  ICP_ERR_INVALID_HEIGHT
	  ICP_ERR_INVALID_WIDTH
	  ICP_ERR_INVALID_STRIDE
	  ICP_ERR_ADDRESS_NOT_64_ALIGNED
	 
int icpHorzFilter(	unsigned char *srcImage,  	/* Address of the source image */
                    	int srcStride,            		/* Source stride, line offset  */
                    	int height,               		/* Source height           */
                    	int width,                		/* Source width            */
                    	unsigned char *destImage, 	/* Address of the dest. image  */
                    	int destWidth             		/* Width of the dest. image    */
                    	);

  Horizontal filter an image given in *scrImage in SDRAM to *destImage in SDRAM.
  It is assumed that:
 
Micro code is already loaded (automatically done in icp_open).
Filter coefficients are already loaded.
ICP is initialized and open.
Source image is copied back in memory.
Destination stride is the image width.
 
  return 0 for success.
 
  Errors:	  ICP_ERR_DEVICE_NOT_OPEN
	  ICP_ERR_INIT_REQUIRED
	  ICP_ERR_INVALID_HEIGHT
	  ICP_ERR_INVALID_WIDTH
	  ICP_ERR_INVALID_STRIDE
	  ICP_ERR_ADDRESS_NOT_64_ALIGNED
 
int icpYUV2RGB(	unsigned char *yStartAddr,      /* Start addr of Y block, 64 bytes aligned */
                	unsigned char *uStartAddr,      /* Start addr of U block, 64 bytes aligned */ 
                	unsigned char *vStartAddr,      /* Start addr of V block, 64 bytes aligned */
                	int yStride,		         /* Stide of the Y block */	
               		 int uvStride,		         /* Stide of the U/V blocks, assumed same */
                	int srcHeight,		         /* Source height */
                	int srcWidth,		         /* Source width */
               		unsigned char *destAddr,         /* Destination address, 64 bytes aligned */
               		int destStride,		         /* Destination stride */
 			int destWidth,			 /* Destination width */
                	int yuvType,		         /* 1 => YUV422, 0 => YUV420 */
                	int rgbType,		         /* 1 => RGB 24,  0 => RGB16 */
                	int outToPCI);		         /* 1 => PCI,         0 => SDRAM
 
  Convert yuv 422 or 420 planar image in memory (stride = width) into rgb 16 or 24 packed
  format using ICP and send the output to PCI/SDRAM.
  All other parametrs are derived from given parametrs or assumptions.
 
  Assumptions:
Images are already copied back.
no bit masking, no overlay
Filter coefficients are already loaded
Micro code is already loaded in SDRAM
ICP is ready initialized and open
No provision for horizontal scaling for the moment.
 
  Return 0 for success.
 
  Errors:	  ICP_ERR_DEVICE_NOT_OPEN
	  ICP_ERR_INIT_REQUIRED
	  ICP_ERR_INVALID_HEIGHT
	  ICP_ERR_INVALID_WIDTH
	  ICP_ERR_INVALID_STRIDE
	  ICP_ERR_ADDRESS_NOT_64_ALIGNED
	  ICP_ERR_IMAGE_TYPE
	  ICP_ERR_OUTPUT_NOT_DEFINED
	  ICP_ERR_CANT_WRITE_TO_BIUCTRL
 
int imageView (	unsigned char *srcAddr,
               		int width, 
		int height, 
		int bytesPerPixel, 
		int srcStride,
               		unsigned char *destAddr, 
		int destStride, 
		int adjustSize);

    Dump the source image into destination using memcpy.
    width in pixels, strides in bytes.
    if adjustSize is set, destination is assumed to be rgb24 and each byte is
    replicated three times.
    returns 0 for success, or errors.
 
    ICP_ERR_INVALID_HEIGHT
    ICP_ERR_INVALID_WIDTH
    ICP_ERR_INVALID_STRIDE
 
int errLogError( char *str, int module, int error);