/*****************************************************************************
 *   readme.txt:  Description of the LPC288x Sample Software
 *
 *   Copyright(C) 2007, Philips Semiconductor
 *   All rights reserved.
 *
 *   History
 *   2007.03.20  ver 1.00    Preliminary version, first Release
 *   2007.05.15  ver 1.10    Updated LPC288x.h with new definition matching
 *                           with examples in LPC23xx/24xx, as some examples
 *                           share the same IP. The changes include MCI, RTC. 
 *                           Added Clock Generation Unit initialization in
 *                           common library.
 *                           SDRAM initialization and test module
 *                           Watchdog timer(WDT) using Event Router and test module.
 *                           MCI initialization and test module.
 *                           Minor fixes in timer, interrupt handler.
 *                           RTC software example
 *                           Added DMA support for UART and MCI. The MCI DMA bug
 *                           has been confirmed, once the H/W fix is in place, this
 *                           MCI DMA should work.
 *                           Fixes and improvement in USBMEM. Now, this test module
 *                           have passed USBCV compliance test.
 *   2007.07.16  ver 1.20    Fixes in USBMEM, state machine in usbcore.c and H/W
 *                           module change in usbhw.c. Now, the USB can pass the
 *                           USBCV test even when the USB peripheral clock runs at 
 *                           30Mhz. Now, the MSC class driver is configured as
 *                           a self-powered device with remote wakeup enabled.
 *   2007.09.05  ver 1.30    More fixes in USBMEM in usbcore.c.
 *                           Added logic to test USB suspend to put uC into low
 *                           power mode and USB resume to wake up uC.
 *                           Added USB Video Class driver support, both USBMEM
 *                           and USBUVC can pass the USBCV1.3 test.
 *                           Added I2S DAI/DAO and DDAC/DADC examples 
 *   
 *				
 *
******************************************************************************/

/*****************************************************************************/
Software that is described herein is for illustrative purposes only which 
provides customers with programming information regarding the products.
This software is supplied "AS IS" without any warranties. Philips Semiconductors 
assumes no responsibility or liability for the use of the software, conveys no 
license or title under any patent, copyright, or mask work right to the 
product. Philips Semiconductors reserves the right to make changes in the 
software without notification. Philips Semiconductors also make no representation 
or warranty that such application will be suitable for the specified use without 
further testing or modification.
/*****************************************************************************/


The Description of the sample software
===================

The sample software have been tested on Keil uVision MDK software development 
platform(RealView compiler in the backend). The target board is Nohau's LPC2800 
Eval. board.
 
The sample software includes, common library, peripheral APIs, and test modules
for the APIs. The common library include startup file, standard definition and
header files, processor specific setup module including PLL and CGU setup, 
generic interrupt handler and related APIs, timer routine, and scatter loading file. 

The peripheral directories included so far are USBMEM, USBUVC, MCI, timer, SDRAM, 
WDT, UART, RTC, I2S, DADC_DDAC, etc. 

Keil USB device Mass Storage Class(MSC) and Video Class(UVC) example for 
LPC23xx/lpc24xx have been used as the base for the LPC288x USB high-speed USB driver 
porting. http://www.keil.com/download/docs/336.asp
In the USB example, the device is configured as a self-powered with remote wakeup
enabled. For the compliance test, GPIO2 or GPIO3 is used as remote wakeup source.
As a self-configured device, JP20 jumper should be closed onto the "arrow"(delta) 
side, not on the "VCC" side.
To test low power mode and USB resume to wake up the uC, set USB_LOW_POWER_EVENT 
to 1 in usbcfg.h.
For I2S DAI/DAO, DDAC, DADC test, some H/W modification is needed, an usage note in 
MS Word format is provided. 

Known issues:

(1) In the existing silicon on Nohau board, DMA for MCI controller is not working 
due to a H/W issue. MCI_DMA_ENABLED should be defined as 0.

(2) All the Keil MDK projects have been tested. Although, RVDS project has been 
created for USMMEM, but not tested. Keil has the configuration Wizard to configure 
CGU and PLL. If Keil tool is not used, you can use the startup.s attached in the
COMMON directory and add the PLL configuration examples from "target.c".


The directory tree and content of the sample software
===================

common
    -- inc
	-- lpc288x.h		Definition file of all the registers of LPC28xx
	-- irq.h		Interrupt related definitions and API prototyping
	-- type.h		Type definition
	-- target.h		Target specific definition for Nohau's LPC2800 board
	-- timer.h		Definition and header file for timer module
	-- ex_sdram.h		definition for EMC and SDRAM related.
	-- dma.h		definition for DMA related.
	-- mem_b.scf		Scatter loader for code running in SRAM, used by RVDK 
				project only
	-- mem_c.scf		Scatter loader for code running in internal flash, 
				used by RVDK project only.
    -- src
	-- lpc28xx.s		Startup entry
				Due to the new configuration wizard on Keil MDK.
				This new startup is provided by Keil.
	-- startup.s		Code start up entry, (not used for now)
	-- heap.s		Heap entry definition(not used for now) 
	-- stack.s		Stack entry definition(not used for now)
	-- swi_handler.s	SWI handler(not used) 
	-- irq.c		Generic interrupt handler related APIs 
	-- target.c		Target specific modules including CGU configuration.
	-- timer.c		Timer related APIs
	-- ex_sdram.c		EMC initialization for SDRAM
	-- dma.c		DMA initialization and ISR APIs, SDRAM is used for DMA 
				transfer. 

USBMEM
    -- memory.c			Main entry, USB MSC test module
    -- diskimg.c		Disk image file act as a RAM drive
    -- usbhw.h			USB device configuration header 
    -- usbhw.c			USB device configuration APIs
    -- usbuser.h		USB device endpoints related and misc. definition
    -- usbuser.c		USB device customerization APIs
    -- mscuser.c		USB MSC related APIs
    -- usbdesc.h		USB descriptor related definition
    -- usbdesc.c		USB descriptor related APIs
    -- usbcfg.h			USB device related configuration such as EPs,
				classes, DMA, etc.
    -- usb.h			USB device related definition
    -- msc.h			USB Mass Storage Class related header
    -- mscuser.h		USB MSC customerization and definition
    -- usbcore.c		USB device core APIs
    -- usbcore.h		USB device core definition
    -- fromelf.exe		RVDS ELF conversion program to convert from AXF to BIN, HEX, etc.
				Please note: this FROMELF has many revisions from ARM, it works
				on Keil MDK, but may not work on some other IDEs!!!
    -- Hostcryptv2.exe		LPC288x DFU conversion utility
    -- memory.uV2		Keil uVision Project file
    -- memory.opt		Keil uVision Project supporting file
    -- memory.prj		RVDK project file, unsure it's support for RVDS or not.
    -- conv.bat			Conversion DOS script file to convert *.axf to *.bin then to *.ebn
				for DFU programming.
    -- flash.ini		Keil uVision script file to load code to Flash and execute

USBUVC
    -- uvcdemo.c		Main entry, USB UVC test module
    -- uvcdemo.h		UVC demo header	
    -- usbhw.h			USB device configuration header 
    -- usbhw.c			USB device configuration APIs
    -- usbuser.h		USB device endpoints related and misc. definition
    -- usbuser.c		USB device customerization APIs
    -- uvcuser.c		USB UVC related APIs
    -- uvcuser.h		USB UVC related header
    -- usbdesc.c		USB descriptor related APIs
    -- usbdesc.h		USB descriptor related definition
    -- usbcfg.h			USB device related configuration such as EPs,
				classes, DMA, etc.
    -- usb.h			USB device related definition
    -- uvc.h			USB Video Class related header
    -- usbcore.c		USB device core APIs
    -- usbcore.h		USB device core definition
    -- Hostcryptv2.exe		LPC288x DFU conversion utility
    -- uvc.uV2			Keil uVision Project file
    -- uvc.opt			Keil uVision Project supporting file
    -- conv.bat			Conversion DOS script file to convert *.axf to *.bin then to *.ebn
				for DFU programming.
    -- flash.ini		Keil uVision script file to load code to Flash and execute

Timer
    -- tmrtest.c		Timer test module, note: API modules are in the COMMON directory 
				and shared and used by some other peripheral testing.
    -- timer.uv2		uVision project file
    -- ram.ini			Keil uVision script file to load code to RAM and execute
    -- flash.ini		Keil uVision script file to load code to Flash and execute

UART
    -- uart.h			UART header
    -- uart.c			UART APIs, if DMA is enabled, DMA APIs from the common library
				will be used. SDRAM will be needed as well for DMA.
    -- uarttest.c		UART test module
    -- uart.uv2			uVision project file
    -- ram.ini			Keil uVision script file to load code to RAM and execute
    -- flash.ini		Keil uVision script file to load code to Flash and execute

MCI
    -- mci.h			MCI header
    -- mci.c			MCI APIs, if DMA is enabled, DMA APIs from the common library
				will be used. SDRAM will be needed as well for DMA.
				(currently DMA is not working due to H/W issue.)
    -- mcitest.c		MCI test module
    -- mci.uv2			uVision project file
    -- ram.ini			Keil uVision script file to load code to RAM and execute
    -- flash.ini		Keil uVision script file to load code to Flash and execute

EXTMEM 
    -- SDRAM
    	-- uart.h		UART debugging header file for stand-alone SDRAM test
	-- uart.c		UART debugging file for stand-alone SDRAM test 
	-- sdram_test.c		SDRAM test module. note: API modules are in the COMMON 
				directory and shared and used by some other peripheral testing.
	-- ex_sdram.uv2		uVision project file
	-- ram.ini		Keil uVision script file to load code to RAM and execute
	-- flash.ini		Keil uVision script file to load code to Flash and execute

WDT
    -- wdt.h			Watchdog timer header
    -- wdt.c			Watchdog timer APIs including Event Router setup.
    -- wdttest.c		Watchdog timer test module
    -- wdt.uv2			uVision project file
    -- ram.ini			Keil uVision script file to load code to RAM and execute
    -- flash.ini		Keil uVision script file to load code to Flash and execute

RTC
    -- rtc.h			Real-time clock header
    -- rtc.c			Real-time clock APIs.
    -- rtctest.c		Real-time clock test module
    -- rtc.uv2			uVision project file
    -- ram.ini			Keil uVision script file to load code to RAM and execute
    -- flash.ini		Keil uVision script file to load code to Flash and execute

I2S
    -- DAI
	-- dai_test.c		I2S DAI test module
	-- dai.uv2		uVision project file
	-- ram.ini		Keil uVision script file to load code to RAM and execute
	-- flash.ini		Keil uVision script file to load code to Flash and execute
    -- DAO
	-- dao_test.c		I2S DAO test module
	-- dao.uv2		uVision project file
	-- ram.ini		Keil uVision script file to load code to RAM and execute
	-- flash.ini		Keil uVision script file to load code to Flash and execute
    
DADC_DDAC
    -- DADC
	-- dadc_test.c		Dual-channel ADC test module
	-- dadc.uv2		uVision project file
	-- ram.ini		Keil uVision script file to load code to RAM and execute
	-- flash.ini		Keil uVision script file to load code to Flash and execute
    -- DDAC
	-- ddac_test.c		Dual-channel DAC test module
	-- ddac.uv2		uVision project file
	-- ram.ini		Keil uVision script file to load code to RAM and execute
	-- flash.ini		Keil uVision script file to load code to Flash and execute
        
Usage notes for I2S_DADC_DDAC.doc
				The MS Words usage note for I2S DAI/DAO, DADC, DDAC modules.
				Some H/W change will be needed to conduct the tests.
 
readme.txt			This file