sci.h

56f8300E系列dsp的BOOTloader

/*****************************************************************************
*
* Motorola Inc.
* (c) Copyright 2002 MOTOROLA
* ALL RIGHTS RESERVED.
*
******************************************************************************
*
* File Name:         sci.h
*
* Description:       API header file for DSP56838 SCI driver
*
* Modules Included:  
*                    
* 
*****************************************************************************/


#ifndef __SCI_H
#define __SCI_H


#include "port.h"
#include "arch.h"
#include "bsp.h"
#include "io.h"

/******************************************************************************
*
*                      General Interface Description
*
*  The SCI driver allows a user to read and write samples to/from the SCI
*  device. 
*
*  The DSP56838 processor has two SCI modules: SCI0 and SCI1. 
*
*  In SDK each SCI module is represented as a separate device so the 
*  application has to use the driver oriented API to work with SCI devices.
* 
*  The SCI driver supports both NonBlocking and Blocking modes.
* 
*  If Blocking is selected, API calls return control to the application when 
*  the required operation is completed. 
*
*  If the application opens a SCI device in NonBlocking mode, services
*  return control immediately after the start of the operation. There
*  are two ways to indicate completion of the operation.  The SCI driver
*  can call a user defined callback function at the end of operation, 
*  or the application can check the status of the operation via an 
*  "ioctl" call.
*
*  All SCI Driver API calls are re-entrant, as long as the parameters
*  being passed in are not referring to the same global data. 
*
*  Before using any of the SCI devices, the application must open the 
*  device via an "open" call and save the device descriptor. 
*  Use the "BSP_DEVICE_NAME_SCI_0" device name for SCI0 module and
*  "BSP_DEVICE_NAME_SCI_1" device name for SCI1 module. Open flags are
*  indicated in the second argument of the "open" function. 
*  Value of baud rate is indicated in the third argument of the "open"
*  function. These parameters cannot be changed via an "ioctl" call.
*  To change these parameters you should call "open" with new arguments.
*
*  To send data via SCI, the application should use a "write" call. In
*  Blocking mode, the "write" function does not return until all data
*  has been transferred by the SCI peripheral.  In NonBlocking mode,
*  the "write" function does not wait until all of the data has been 
*  transferred.  Instead, it writes as much data to the  SCI Device Driver
*  and returns immediately returning the actual number of bytes written
*  to the SCI Driver.  If a Write Callback function has been defined by
*  the user's application then it will be called once all of the data
*  in the SCI Driver has been transmitted (this is valid for both Blocking and
*  NonBlocking modes, however, it doesn't make sense for Blocking since
*  the driver doesn't return until all data has been transmitted.
*
*  To receive data from SCI, the application should use a "read" call. In
*  Blocking mode, the "read" function does not return until the requested
*  amount of data has been received from the SCI peripheral.
*  In NonBlocking mode, the "read" function returns whatever data has
*  already been received from the SCI peripheral.  It also returns
*  the length of the actual data received (in bytes).  To determine when
*  all the data has actually been received in NonBlocking mode, set the
*  required data length via an ioctl SCI_SET_RX_WATERMARK command.
*  Then install the Read Callback via an ioctl SCI_CALLBACK_RX command.
*  When the driver has received the required amount of data, it calls
*  the user's Read Callback function.  If any errors are detected while
*  receiving data, the Error Callback is called (if one is defined by the
*  user using an ioctl SCI_CALLBACK_EXCEPTION command. 
*
*  To disable or enable the device, use the "ioctl" call.
* 
*  After completing all SCI operations, close the SCI device with a call to 
*  "close".
* 
*  For more references, see this file and io.h file.
******************************************************************************/

/******************************************************************************
*
*  Static Configuration
*
*  The SCI Driver can be statically configured using the config.h
*  and appconfig.h files.  The config.h file contains the default configuration
*  for all drivers.  These defaults can be changed by the user via the
*  appconfig.h file.
*
*  The #defines that statically configure the SCI are shown below.
*  The defaults as defined in config.h have "default" after the statement.
*  
*      #define SCI_BYTE_BUFFER_LENGTH      16 (default) (value should be multiple to 2 a degree 1,2,...)
*
*      #define SCI0_RX_CALLBACK_FUNCTION    NULL (default)
*
*      #define SCI0_TX_CALLBACK_FUNCTION    NULL (default)
*
*      #define SCI0_ERROR_CALLBACK_FUNCTION NULL (default)
*
*      #define SCI0_READ_WATERMARK          0 (default)
*
*      #define SCI0_BAUD_RATE               9600 (default) ????
*
*
*      #define SCI1_RX_CALLBACK_FUNCTION    NULL (default)
*
*      #define SCI1_TX_CALLBACK_FUNCTION    NULL (default)
*
*      #define SCI1_ERROR_CALLBACK_FUNCTION NULL (default)
*
*      #define SCI1_READ_WATERMARK          0 (default)
*
*      #define SCI1_BAUD_RATE               9600 (default) ????
*
******************************************************************************/

/******************************************************************************
*
*  SCI Interfaces
* 
*     The SCI interface can be used at two alternative levels, a low level
*     SCI driver interface and the common IO layer interface.  The common IO 
*     layer interface invokes the lower level SCI driver interface. 
*
*     The low level SCI driver provides a non-standard interface that is
*     potentially more efficient that the IO layer calls, but less portable.  
*     The IO layer calls to the SCI interface are standard and more 
*     portable than the low level SCI interface, but potentially less efficient.
*    
*     Your application may use either the low level SCI driver interface or
*     the IO layer interface to the SCI driver, depending on your specific
*     goals for efficiency and portability.
*
*     The low level SCI driver interface defines functions as follows:
*  
*          int     sciOpen  (const char *pName, int OFlags);
*          int     sciClose (handle_t hndl);  
*          ssize_t sciRead  (handle_t hndl, void * pBuffer, size_t NBytes);
*          ssize_t sciWrite (handle_t hndl, const void * pBuffer, size_t NBytes);
*          UWord16 sciIoctlSCI_DEVICE_RESET( handle_t hndl, unsigned long params );
*          UWord16 sciIoctlSCI_SET_RX_WATERMARK( handle_t hndl, unsigned long params );
*          UWord16 sciIoctlSCI_GET_STATUS( handle_t hndl, unsigned long params );
*          UWord16 sciIoctlSCI_GET_EXCEPTION( handle_t hndl, unsigned long params );
*          UWord16 sciIoctlSCI_CALLBACK_RX( handle_t hndl, unsigned long params );
*          UWord16 sciIoctlSCI_CALLBACK_TX( handle_t hndl, unsigned long params );
*          UWord16 sciIoctlSCI_CALLBACK_EXCEPTION( handle_t hndl, unsigned long params );
*          UWord16 sciIoctlSCI_DEVICE_OFF( handle_t hndl, unsigned long params );
*          UWord16 sciIoctlSCI_DEVICE_ON( handle_t hndl, unsigned long params );
*          UWord16 sciIoctlSCI_CMD_SEND_BREAK( handle_t hndl, unsigned long params );
*          UWord16 sciIoctlSCI_CMD_WAIT( handle_t hndl, unsigned long params );
*          UWord16 sciIoctlSCI_CMD_WAKEUP( handle_t hndl, unsigned long params );
*          UWord16 sciIoctlSCI_SET_HIBIT( handle_t hndl, unsigned long params );
*          UWord16 sciIoctlSCI_CLEAR_HIBIT( handle_t hndl, unsigned long params );
*
*     The IO layer interface defines functions as follows:
*
*          int     open  (const char *pName, int OFlags, ...);
*          int     close (handle_t hndl);  
*          ssize_t read  (handle_t hndl, void * pBuffer, size_t NBytes);
*          ssize_t write (handle_t hndl, const void * pBuffer, size_t NBytes);
*          UWord16 ioctl (handle_t hndl, UWord16 Cmd, unsigned long params);      
*
******************************************************************************/

/*****************************************************************************
*
* LOW LEVEL SCI DRIVER INTERFACE
*
*   General Description:
*
*      A SCI device is configured by the following:
*  
*  		  1)  The device is created and initialized by selecting it by 
*             defining the INCLUDE_SCI variable in the appconfig.h file 
*             associatedwith the SDK Embedded Project created in
*             CodeWarrior. 
*
*         2)  An "sciOpen" call is made to initialize the SCI device
*
*         3)  "sciIoctl" calls are made to control the SCI device
*
*         4)  "sciWrite" calls are made to write data out of the SCI device.
* 
*         5)  "sciRead" calls are made to read data from the SCI device.
*
*         6)  After all SCI operations are completed, the SCI device
*             is closed via a "sciClose" call.
*
* 
*    sciOpen 
*
*       int sciOpen(const char *pName, int OFlags, long BaudRate);
*
*          Semantics:
*             The sciOpen function opens the SCI peripheral for operations. 
*             The SCI device is always opened for read and for write calls.
*             The sciOpen function establishes the handle for the SCI
*             driver.  It initializes the internal memory buffers used by
*             the SCI driver.  It configures the driver for Blocking or
*             NonBlocking modes, as defined in the OFlags parameter.  
*             Finally, it enables the SCI Receiver interrupts.  It does not
*             enable the SCI transmitter interrupts as this is done when
*             the "sciWrite" function is called.
*             Default mode for open, as defined in config.h and config.c, is the
*             following:
*
*                Default Baud Rate = 9600bps                     ???????
*                Default Data Mode = 8-bit with no parity
*                Default Data Polarity = Not Inverted
*                Default HiBit = 0
*                Default Loopback = Not Enabled
*
*             Argument pName identifies the particular SCI device name. See bsp.h
*             for a list of device names for this chip.  Typically, the SCI device
*             names include:
*                      BSP_DEVICE_NAME_SCI_0
*                      BSP_DEVICE_NAME_SCI_1
*                      ...
*
*          Parameters:
*             pName    - device name.  (See bsp.h for a list of SCI device names.)
*
*             OFlags   - open mode flags;
*                        O_RDONLY                               - ignored
*                        O_WRONLY                               - ignored
*                        O_RDWR                                 - default
*                        O_NONBLOCK                             - non-blocking mode
*                        O_BLOCK                                - blocking mode (default)
*                        O_SCI_DISABLE_IN_WAIT                  - SCI disabled in wait mode
*                        O_SCI_ENABLE_IN_WAIT                   - SCI enabled in wait mode (default)
*                        O_SCI_WAKE_BY_ADDRESS                  - address mark wake-up
*                        O_SCI_WAKE_BY_IDLE                     - idle line wake-up (default)
*                        O_SCI_WORD_9BIT                        - 1 start bit, 9 data bits, 1 stop bit
*                        O_SCI_WORD_8BIT                        - 1 start bit, 8 data bits, 1 stop bit (default)
*                        O_SCI_PARITY_NONE                      - parity function disabled (default)
*                        O_SCI_PARITY_ODD                       - odd parity
*                        O_SCI_PARITY_EVEN                      - even parity
*                        O_SCI_7_DATA_BITS_ODD_PARITY           - 7 data bits with odd parity
*                        O_SCI_7_DATA_BITS_EVEN_PARITY          - 7 data bits with even parity
*                        O_SCI_8_DATA_BITS_NO_PARITY            - 8 data bits without parity (default)
*                        O_SCI_8_DATA_BITS_ODD_PARITY           - 8 data bits with odd parity
*                        O_SCI_8_DATA_BITS_EVEN_PARITY          - 8 data bits with even parity
*                        O_SCI_9_DATA_BITS_NO_PARITY            - 9 data bits without parity
*                        O_SCI_TX_INVERTED                      - inverted mode
*                        O_SCI_TX_NOT_INVERTED                  - normal mode (default)
*                        O_SCI_INVERT_ALL_BITS                  - O_SCI_TX_INVERTED
*                        O_SCI_DONT_INVERT_ANY_BITS             - O_SCI_TX_NOT_INVERTED
*                        O_SCI_LOOPBACK_DISABLED                - loop operation disabled (default)
*                        O_SCI_LOOPBACK_ENABLED                 - loop operation enabled
*                        O_SCI_LOOPBACK_SINGLE_WIRE_ENABLED     - loop operation with single wire enabled
* 
*             BaudRate - value of baud rate (driver uses as a unsigned long)
*
*          Return Value: 
*             SCI device descriptor if open is successful.
*             -1 value if open failed.
*     
*       Example:
*     
*          open SCI0 in NonBlocking mode for 8 bit data, no parity, and 115200: