Configuration

Configuration
	Chapter 246. Keil MCB2387 Board Support

Overview

The mcb2387 platform HAL package is loaded automatically when eCos is configured for an mcb2387 target. It should never be necessary to load this package explicitly. Unloading the package should only happen as a side effect of switching target hardware.

Startup

The mcb2387 platform HAL package supports three separate startup types:

JTAG: This is the startup type which is normally used during JTAG based application development. arm-eabi-gdb is then used to connect to the JTAG device and load a JTAG startup application into memory and debug it. It is assumed that the basic hardware has already been initialized via the JTAG device's initialization script. Otherwise the application is entirly self contained and should contain drivers for all hardware used.
RAM: This is the startup type which is normally used during stubrom based application development. The board has the stubrom programmed into flash at location 0x0 in internal on-chip Flash and boots from that location. arm-eabi-gdb is then used to load a RAM startup application into memory and debug it. It is assumed that the basic hardware has already been initialized by the stubs. By default the application will use the eCos virtual vectors mechanism to obtain certain services from the stubrom, including diagnostic output.
ROM: This startup type can be used for finished applications which will be programmed into internal flash at location 0x0. The application will be self-contained with no dependencies on services provided by other software. eCos startup code will perform all necessary hardware initialization.

Virtual Vectors

If the application is intended to act as a ROM monitor, providing services for other applications, then the configuration option CYGSEM_HAL_ROM_MONITOR should be set. Typically this option is set only when building the stubrom.

If the application is supposed to make use of services provided by a ROM monitor, via the eCos virtual vector mechanism, then the configuration option CYGSEM_HAL_USE_ROM_MONITOR should be set. By default this option is enabled when building for a RAM startup, disabled otherwise. It can be manually disabled for a RAM startup, making the application self-contained, or as a testing step before switching to ROM startup.

If the application does not rely on a ROM monitor for diagnostic services then serial port UART0 will be claimed for HAL diagnostics.

Flash Driver

The CYGPKG_DEVS_FLASH_LPC2XXX package contains all the code necessary to support the on-chip flash.

System Clock

By default, the system clock interrupts once every 10ms, corresponding to a 100Hz clock. This can be changed by the configuration option CYGNUM_HAL_RTC_DENOMINATOR which corresponds to the clock frequency. Other clock-related settings are recalculated automatically if the denominator is changed. The PLL multipliers and dividers may be configured to allow a core clock (CCLK) speed of up to 72MHz. However, the platform HAL currently sets the clock to 48MHz, duplicating the configuration in the supplied example code as a consequence of CPU errata affecting various revisions of the LPC2387. Setting the CPU revision with the CYGHWR_HAL_ARM_LPC2XXX_MCB2387_CPU_REVISION configuration option can be used to provide default clock settings appropriate to the CPU revision in use. If the CPU revision cannot be guaranteed it should be left as "Initial". The description of the clock-related CDL options may be found in the LPC2xxx variant HAL documentation.

I²C Bus Configuration

The on-chip I²C devices are supported by a driver in the variant HAL package. Each bus for this driver needs to be configured in the platform HAL with the following options:

CYGPKG_HAL_ARM_LPC2XXX_I2CX: This is the master component, enabling this activates all the other configuration options and causes the driver to create the data structures to access this bus.
CYGPKG_HAL_ARM_LPC2XXX_I2CX_CLOCK: Bus clock speed in Hz. Usually frequencies of either 100kHz or 400kHz are chosen, the latter sometimes known as fast mode.
CYGPKG_HAL_ARM_LPC2XXX_I2CX_SDA: This option describes the pin used for SDA on this bus. This takes the form of an invocation of the macro __LPC2XXX_PINSEL_FUNC. Parameters are the port number, pin within that port, and the alternate select function for the pin. See the LPC2387 user manual for details of which pins may be used by each bus.
CYGPKG_HAL_ARM_LPC2XXX_I2CX_SCL: This option describes the pin used for SCL on this bus. Like SDA this takes the form of a call to __LPC2XXX_PINSEL_FUNC.

Note that "I2CX" is a placeholder for a given bus instance: "I2C0", "I2C1" or "I2C2". By default the platform HAL does not enable any I²C buses since there are no on-board devices.

SPI Bus Configuration

The on-chip SSP SPI devices (not the Legacy SPI device) are supported by the NXPSSP driver package, CYGPKG_DEVS_SPI_ARM_NXPSSP. This needs some configuration in the platform HAL:

CYGPKG_HAL_ARM_LPC2XXX_SPI: This is the master component, enabling this activates all the other configuration options. It also causes mcb2387_spi.c to be compiled, which contains descriptions of the devices on the SPI buses.
CYGPKG_HAL_ARM_LPC2XXX_SPIX: This is the master component for each bus. Enabling this activates the other configuration options for this bus, and causes the driver to support this bus.
CYGPKG_HAL_ARM_LPC2XXX_SPIX_SCLK: This option describes the pin used for SCLK on SPIX. It takes the form of an invocation of __LPC2XXX_PINSEL_FUNC. The parameters are the port number, pin within that port, and the alternate select function for the pin. See the LPC2387 user manual for details."
CYGPKG_HAL_ARM_LPC2XXX_SPIX_MISO: This option describes the pin used for MISO on SPIX. Like SCLK it takes the form of a call to __LPC2XXX_PINSEL_FUNC.
CYGPKG_HAL_ARM_LPC2XXX_SPIX_MOSI: This option describes the pin used for MOSI on SPIX. Like SCLK it takes the form of a call to __LPC2XXX_PINSEL_FUNC.
CYGPKG_HAL_ARM_LPC2XXX_SPIX_CS_PINS: This defines the pins to be uses as chip selects for this bus. It is a comma separated list of GPIO pin names, the first for device 0, the second for device 1, and so on. Pin names are defined in the var_io.h header in the LPC2xxx variant HAL.

Note that "SPIX" is a placeholder for a given bus instance: "SPI0" or "SPI1". By default the platform HAL does not enable any SPI busses since there are on on-chip devices.

MCI peripheral configuration

The on-chip Multimedia Card Interface (MCI) is supported to allow access to Multimedia Cards (MMC) or Secure Digital (SD) cards using the socket on the board. This support is provided in conjunction with the generic MMC/SD driver package (CYGPKG_DEVS_DISK_MMC), the Primecell MCI driver package (CYGPKG_DEVS_MMCSD_ARM_PRIMECELL_MCI) and the LPC2xxx variant HAL in order to provide some elements of the DMA support. Documentation and configuration options within those packages should also be consulted.

The following CDL configuration options are used to control the behaviour of the MMC/SD card support:

MMC/SD card support (CYGPKG_HAL_ARM_LPC2XXX_MCB2387_MCI)

This option allows the MMC/SD card support as a whole to be enabled or disabled, although the generic disk device driver package (CYGPKG_IO_DISK) must be loaded in order to enable the MMC/SD support.

Use on-chip USB memory for DMA (CYGSEM_HAL_ARM_LPC2XXX_MCB2387_MCI_USE_USB_MEM_FOR_DMA

The LPC2387 cannot always keep up with the data transfer requirements, especially at slower CPU clock speeds. This is because the DMA controller runs at the speed of the CPU clock (CCLK) along with the fact that some LPC2387 have errata which decreases their achievable CPU clock frequency.

Using on-chip memory dedicated to USB helps reduce or remove these problems, depending on CPU frequency. Clearly this option must be disabled if the on-chip USB peripheral is to be used. It is also desirable to disable this option if the CPU frequency is high enough, in order to remove an extra copy on every data transfer, thus improving performance. The USB memory used is 512 bytes at the start of the USB memory space (0x7FD00000).

If this option is disabled and the DMA is not able to proceed quickly enough, this will be visible in the form of I/O errors. In that case, if it is not possible to enable this option it is recommended to adjust the CYGDAT_HAL_ARM_LPC2XXX_MCB2387_MCI_BUS_SPEED_LIMIT configuration option.

Lock AHB bus during DMA transfer (CYGSEM_HAL_ARM_LPC2XXX_MCB2387_MCI_DMA_LOCKS_AHB)

The AMBA Hardware Bus (AHB) is used to connect AMBA peripherals within the LPC2387, including the ARM core, DMA controller and memory controllers. When this option is enabled, the AHB is locked for the duration of MCI DMA transfer bursts. If another AMBA host needs to make a transfer it may be delayed as a result, which may not be desirable.

Disabling this option allows the AHB arbiter to permit other AHB hosts to perform transfers. Of course this may mean the MCI DMA transfers can in turn themselves get delayed, risking data overruns or underruns in MCI transfers, resulting in I/O errors during block reads or writes. This is particularly likely on processors running at slower clock speeds where there may already be difficulties with the DMA servicing data transfers quickly enough.

MMC/SD bus frequency limit (CYGNUM_HAL_ARM_LPC2XXX_MCB2387_MCI_BUS_SPEED_LIMIT)

The LPC2387 cannot always keep up with the data transfer requirements, especially at slower CPU clock speeds. This is because the DMA controller runs at the speed of the CPU clock (CCLK) along with the fact that some LPC2387 have errata which decreases their achievable CPU clock frequency. The adjacent options to use on-chip USB memory and to lock the AHB bus can help prevent this, but sometimes they are insufficient to prevent data overruns or underruns resulting in I/O errors during block reads or writes. In which case the only remaining recourse is to reduce the required data transfer rate between the MCI and the card.

This option can be used to impose an upper limit on the MMC/SD bus frequency. The value used in this option is measured in Hertz, and the use of 4-bit mode with SD cards is not a factor - this option provides the bus frequency, so a 4-bit bus will transfer four times the amount of data as a 1-bit bus in the same time period.

Note that this option provides a limit, and does not mean the card bus will operate at that frequency. The frequency is also governed by what the card will support, and the resolution of the clock used to derive the MMC/SD clock signal, and how it can be divided down.

Compiler Flags

The platform HAL defines the default compiler and linker flags for all packages, although it is possible to override these on a per-package basis. Most of the flags used are the same as for other architectures supported by eCos.

However there are two flags that are used if Thumb mode is to be supported:

-mthumb: The arm-eabi-gcc compiler will compile C and C++ files into the Thumb instruction set when this option is used.
-mthumb-interwork: This option allows programs to be created that mix ARM and Thumb instruction sets. Without this option, some memory can be saved. This option should be used if -mthumb is used.


Setup		The HAL Port

Name