/************************************************************/
/*  Readme for the new COM PORT driver, OS7_COM.Lib         */
/*                                                          */
/*  The readme includes FAQ1~FAQ7, and update history.      */
/*                                                          */
/*  Last updated on [2012,Sep.,28] by Tim Tsai              */
/************************************************************/


================================================================================
FAQ1: What is OS7_COM.lib ?
================================================================================
Ans: OS7_COM.lib is a new COM port driver for MiniOS7 based controllers. 


================================================================================
FAQ2: What are the benefits of the new method/driver ?
================================================================================
Ans:
* Occupies less memory then the old driver when using many COM ports.
   old driver: the COM port APIs included in the CPU library (uPAC5000.Lib)
   new driver: the COM port APIs included in the OS7_COM.lib.
   
* Easy maintainence for the driver developer.

================================================================================
FAQ3: Can I mix old and new drivers?
================================================================================
Ans: Yes. You can mix the old and new drivers in your code.
     For example, the following case can work well.
        InstallCom(1,115200,8,0,1); //COM1 use old driver
        ToCom(1,'a');               //COM1 use old driver
        
        OS7_COM *port;
        port=_InstallCom(2,115200,8,0,1); //COM2 use new driver
        _ToCom(port,'a');               //COM2 use new driver
        
     But you can not mix old and new API to the same COM port.
     For example, the following case can not work well.
        InstallCom(1,115200,8,0,1); //COM1 use old driver
        _ToCom(port,'a');              //COM1 use new driver
      
================================================================================
FAQ4: What MiniOS7 controller is avalible for the OS7_COM.lib ?
================================================================================
Ans: avalible controllers:
    (a) avalible for uPAC-5000 series
    (b) avalible for i-7186E/7188E/7188XB/7188XC series
    (c) avalible for COM1/COM2 of iView-100 (not tested)
    (d) avalible for the controller which HW is compatilbe to uPAC-7186EX

    not avalible functions/controllers:
    (a) DMA mode to receive data are not supported 
        for COM1/2(Internal UARTs of the 80186/188 CPU)
    (b) not avalible for i-8000 
    (c) not avalible for i-7188
    (d) not avalible for i-7188XA
    (e) not avalible for iP-8000
     
================================================================================
FAQ5: How to translate my code to use the new driver/method ?
================================================================================
Ans: Just need to proceed two steps to translate the code 
        (a) add one variable (OS7_COM * port)
        (b) add under line to the begining of the functions related to COM port.
        
    Following are the codes using old and new driver.
    You can see the difference.
--------------------------------------------------------------------------------
1. The old driver/method  (all functions are delclared in the CPU head file.)
--------------------------------------------------------------------------------

long baud=115200;
int parity=0;
int stop=1;
int port=1;
int data;

InstallCom(port,baud,parity,stop);

while(IsCom(port)){
    data=ReadCom(port);
    ToCom(port,data);
    //...
}

RestoreCom(port);


--------------------------------------------------------------------------------
2. The new driver/method (all functions are delclared in OS7_COM.h .)
--------------------------------------------------------------------------------

long baud=115200;
int parity=0;
int stop=1;
OS7_COM *port;  // (a)modify the declaration
int data;

port=_InstallCom(COM_1,baud,parity,stop); // (b) add one under line.

while(_IsCom(port)){        // (b) add one under line.
    data=_ReadCom(port);    // (b) add one under line.
    _ToCom(port,data);      // (b) add one under line.
    //...
}

_RestoreCom(port);      // (b) add one under line.



================================================================================
FAQ6: How to Change input/output buffer size
================================================================================
Ans: The default size of the input/output buffers are 1024 bytes.
     To change the size, you can call _SetComPortBufferSize.
     For example: reduce the size to 256 bytes
        _SetComPortBufferSize(COM_2,256,256);
        port=_InstallCom(COM_2,baud,parity,stop);

    How to get size of the input/output buffers ?
        port->_InBufSize  <=== to kown the input buffer size.
        port->_OutBufSize <=== to know the output buffer size.

================================================================================
FAQ7: How many COM ports are supported to using DMA? 
      How to use the DMA to receiv data ?
================================================================================
Ans: The COM ports that supported by the 80188/186 CPU can use DMA to receive data.
	 There are:
     i-7188XB/7188XC/7188E/7186E/uPAC5000/iView100 : COM1 and COM2
     i-7188/7188XA : COM3 and COM4
     i-8000/i-8000-80/iPAC8000 : COM0.(N/A)

     How to use ?
	 Just change _InstallCom() to _InstallCom_DMA(), 
	 and change _RestoreCom_DMA() to _RestoreCom_DMA().
	 
     [Examples]
	 For i-7188E use: 
     pCOM1=_InstallCom_DMA(COM_1,baud,parity,stop);
     ...
     _RestoreCom_DMA(pCOM1);
     
	 For 7188/7188XA use:
     pCOM4=_InstallCom_DMA(COM_4,baud,parity,stop);
     ...
     _RestoreCom_DMA(pCOM4);


================================================================================
[OS7_COM Revision History]
================================================================================
Ver 1.1.4 [2012/09/28] released
	New Support:
  (a) Support UART 16c850.
  
--------------------------------------------------------------------------------
Ver 1.1.3 [2012/05/18] released
	Bugs Fixed: 
	(a)Fix the function : int OS7_ReadComn(OS7_COM *com,unsigned char *buf,int maxno);
		When using COM1 or COM2 with the DMA mode will get the wrong result.

--------------------------------------------------------------------------------
Ver 1.1.2 [2011/03/21] released
	New Support:
	(a)CPU UART also support the data format: 7,M,1 and 7,S,1
	Bugs Fixed: 
	(a)Fix the function : void OS7_SetRtsActive(OS7_COM *com);

--------------------------------------------------------------------------------
Ver 1.1.1 [2010/08/25] released
    Bugs Fixed:  Fixed the problem for the ISR of the UART to work with floating point.   

    [2010/09/14] released
    Recompile: Modify some optimization options.  
--------------------------------------------------------------------------------
Ver 1.1.0 [2010/07/30] released
    New Support:
    (a): iPAC-8000 & i-8114W/8112W/8142W/8144W...
    Change: 
	(a).All functions change to start with "OS7_".
	(b).Needs new MiniOS7 library to support some H/W dependent functions.
	    The new library :
		iPAC-8000	:[2010/08/02] or later
		iPAC-5000	:[2010/08/03] or later
		i-7186E		:[2010/08/03] or later
		i-7188E		:[2010/08/03] or later
		i-7188XB	:[2010/08/03] or later
		i-7188XC	:[2010/08/03] or later
		i-7188XA	:[2010/08/03] or later
		i-7188		:[2010/08/03] or later
		G4500		  :[2010/08/04] or later
		P824A		  :[2010/08/05] or later
		i-8000		:[N/A]
		
--------------------------------------------------------------------------------
Ver 1.0.1 [2010/07/09] released
    New Support:
	(a) Add:Support i-7188 & i-7188XA
	(b) Add:Support using DMA to receive data for the COM ports inside the 186/188 CPU.
    New Functions:
	OS7_COM *_InstallCom_DMA(int port,long baud, int databit,int parity,int stopbit);
	int _RestoreCom_DMA(OS7_COM *pCom);
    Change:
	Add two variables into the structure "os7_com".

--------------------------------------------------------------------------------
Ver 1.0.0 [2010/04/02] first released
    (a) avalible for uPAC-5000 series
    (b) avalible for i-7186E/7188E/7188XB/7188XC series
    (c) avalible for COM1/COM2 of iView-100 (not tested)
    (d) avalible for the controller which has compatilbe HW of uPAC-7186EX
   
    Bugs Fixed:     none
    Change:         none
    New Functions:  none
    New Support:    none

--------------------------------------------------------------------------------

