13.4.5. Modifying target-specific files

Target-specific files are dependent on the target system you are porting Angel to. You must modify these files for your system.

Overview of the target specific sources

Most of the work in porting is carried out on the code in the target specific source directory to set up the target and provide device drivers.

The target specific files are:

target.s

This file provides important startup macros specific to the hardware. You must check each macro in this file and change them for your board, if necessary.

This file also contains the GETSOURCE macro. GETSOURCE is used to identify which interrupt source has caused an interrupt. You must modify this macro to suit the interrupt-driven devices and interrupt scheme used by your hardware. Refer to target.s for details.

makelo.c

This is part of the Angel build environment. When built, makelo includes a number of Angel header files and produces an assembly language .s file that defines globals shared between C and assembly language routines.

This enables assembly language and C modules to access global constants without requiring separate copies for assembler use and for C compiler use.

If you introduce new constants that need to be shared by C and assembly language routines you must add them to makelo.c. Refer to makelo.c for details.

banner.h

This declares what board Angel is running on, and with what options. Refer to banner.h for details.

devices.c

This file #includes the headers for device drivers for the system. You must modify this file if you add, remove, or rename any device drivers. Refer to devices.c for details.

devconf.h

This is the main configuration file. It includes device declarations, memory layout details, stack sizes, and interrupt source information (IRQ or FIQ). You must check every item in this file to ensure that it is set up correctly for your board. Refer to devconf.h for details.

Device Drivers

All other files in the target specific source directory are device driver sources. You might need to modify these even if your board uses the same communications chips as those supported by the port you are using as a template. If you are using different communications hardware, you must rewrite these files for your own hardware. Refer to Writing the device drivers for more information on writing device drivers.

target.s

This file defines the code in the macros called from the initialization and interrupt routines in the main code in startrom.s and suppasm.s.

The following macros are defined:

UNMAPROM

This macro is called by the startrom.s ROM initialization code. The macro is called in systems that use ROM remapping to ensure that the ROM image is at 0 at reset. When the system initialization is complete, a remap is called to map the ROM to its physical address, and map RAM to 0.

This method is used in the PID board system where the memory management system aliases the ROM from its physical address to 0, in order to allow ROM-resident code to be available at reset.

STARTUPCODE

This macro is called from startrom.s for target specific startup. In the PID example, the startup macros reset both the ramsize counter and the interrupt controller.

INITMMU

This macro initializes the MMU for processors that include an MMU. The location of the pagetable is important to the operation of this code and you must be specify it correctly.

If the system is operating in big-endian mode and the MMU is responsible for the endianness of the core, it must be set up early to enable to code to operate correctly.

INITTIMER

This macro is not used by Angel. It is provided as a place holder to allow you to initialize any timers required by your application. It is called after interrupts are disabled and the processor is set to Supervisor mode. There is no code included in the example because it does not make use of system timers. Profiling support code contains its own timer initialization code.

GETSOURCE

This macro is called by the Angel support routines in interrupt.s. It determines whether the current interrupt is for an Angel device, and if so, which one.

The routine returns a small integer representing the current interrupt source, as defined in devconf.h (see devconf.h). These values are used by the interrupt handler for a jump table holding the individual Angel Interrupt source handler function pointers.

The PID board has the following possible interrupt sources:

TIMER

For polled device support, and profiling.

PARALLEL

For parallel code download, if this option is selected at compile time.

PCMCIA CARD A

Used by the Olicom Ethernet driver, if selected at compile time.

PCMCIA CARD B

Used by the Olicom Ethernet driver, if selected at compile time.

SERIAL A

This is the default for debug communications.

SERIAL B

This is optional for debug communications.

CACHE_IBR

This macro is called by Angel support routines in suppasm.s to set an Instruction Barrier Range. This is an option on the SA1100 processor. There is no code included in this macro for the PID example.

makelo.c

This file enables you to share variables and definitions between C and assembly language sources. The makelo.c source file is compiled with armcc and executed under armsd as part of the Angel build process. When executed, it reads the contents of the C header files #included at the start of makelo.c and produces an assembler header file named lolevel.s.

The assembler header file mirrors the C definitions in the #included C header files. For example, the processor mode defined in arm.h, such as:

#define USRmode 0

produce equivalent assembler EQU directives such as:

USRmode		EQU	0

Use a GET directive to include lolevel.s in any assembly language file that requires access to C variables or definitions.

To include your own C variables in the list contained in makelo.c, add lines in the format:

fprintf(outfile, "Variable_Name\t\tEQU\t%d\n", Variable_Name);

for each variable or definition.

banner.h

This header file contains macros that define the text that is displayed when the host and target connect after initialization. You can modify this file to suit your target, and the build options you use. Different ports can share components of this message by including the file configmacros.h. You should take care not to advertise a feature in the banner message that will not work correctly. The banner message is limited to 204 characters.

devices.c

This file defines the base address in memory for each available device. It enables C pointers to access the operational registers in each device.

It is helpful to use a structure, or #define offsets, describing the peripheral register layout symbolically. Symbolic definitions of bit fields can also be useful.

You must also define the interrupt handlers as the handler routine plus an optional parameter. The parameter is used for handlers that service more than one source. In the case of the PID, the same handler is responsible for the two serial ports and the parallel port.

Serial drivers must conform to the generic function calls defined in devdriv.h. This ensures that generic calls from the debug code and channels manager can access any valid device driver, without requiring information about the peripheral being used.

devconf.h

This is the main configuration file for the target image. It sets up the Angel resources for the specific target and defines the hardware configuration to Angel, including:

  • a memory map of available memory

  • interrupt operation

  • the peripherals and devices available to Angel.

All systems require a similar devconf.h to that used for the PID. The following explanation uses the PID devconf.h file as an example. It defines the following:

Number of Serial Ports

The PID has two serial ports. In the PID example, one port is defined to Angel. The other port is available for application use.

Board hardware setup

This option is defined if not minimal Angel:

  • Parallel is for the use of a parallel port for faster download

  • PCMCIA is to set up and use the PC card slots on the board

  • PROFILE makes use of one timer to allow code profiling if requested by the host debugger. This option is rarely used in final builds.

DCC and Cache Support

DCC and CACHE support are processor-dependent. You must take care when defining these. These options enable routines that will not work, and will halt the Angel Debugger, if your processor does not support them.

Debug Method

The DEBUG_METHOD option is only applicable if DEBUG=1 is specified in the makefile or APM project file.

The value of DEBUG_METHOD defines the channel that is used to pass debug messages. Some options require specific equipment or software, for example, pidulate, rombox, and e5 (see also Debugging your Angel port).

The logadp option should not be used.

In general, the safest option is panicblk. The most useful option is logterm, but this requires a spare serial port.

Use the #defines NO_LOG_INFO and NO_LOG_WARNING to increase execution speed and reduce the size of images created with debug enabled, when some or all debug messages are not required.

Interrupt source for ADP

You can select the interrupt source that is used to drive ADP channel communications and timer interrupts. You can select either or both of:

HANDLE_INTERRUPTS_ON_IRQ

Angel interrupt handlers will handle interrupts on IRQ

HANDLE_INTERRUPTS_ON_FIQ

Angel interrupt handlers will handle interrupts on FIQ.

The recommended option is to use IRQ because:

  • Angel interrupt operation is not time-critical.

  • you can use FIQ for your application

  • the Angel FIQ handler is slower than the IRQ handler.

Device Data Control

Device data control is dependent on the build options (minimal or not) and the number of ports controlled by Angel. The default options for full debug operation Angel on the PID board are:

  • serial port A for debug communications

  • serial port B for application use with raw (not packet) data

  • options for parallel download, and application use.

You can change any of these options to suit the communications requirements of your application by redefining the relevant label.

The memory map

You must define the memory map to allow the debugger to control illegal read/writes using the PERMITTED checks. These check that writes are not made to Angel data or code space and provide primitive memory protection.

These should reflect the permitted access of the system memory architecture. Refer to Configuring the memory map for detailed information on setting up an Angel memory map.

Setting up the stacks

You must define a stack for each processor mode used by Angel. These always include User, Supervisor, Undefined, and the selected Interrupt modes. The location of the stacks can be fixed, or can be set to the top of memory when this has been defined. Refer to Configuring the memory map for detailed information on setting up an Angel memory map.

All other Angel-defined memory spaces (fusion stack and heaps, profile work area, application stacks) can be defined to sit relative to the stacks, or can be given fixed locations. The default for the Application Heap space is above the run time Angel code, and the available space is to the lowest limit of the stacks.

Note

Angel stack space is different from the application stack space. However, Angel uses four words of application stack when it returns to the application from an exception.

The download agent area

The download agent area is a spare area of RAM to which new Angel images are downloaded.

The loadagent command writes the image to the download area. When complete, the agent is started with an ADP command. It relocates itself to another area if it has been compiled to do so. This enables the new Angel to overwrite the old Angel and release the download agent area. The download agent can be in the same RAM as an application, because the application and the download agent never run at the same time.

The DeviceIdent structure

The available devices must be defined in the DeviceIdent structure. You must ensure that the order of the devices in this structure is the same as that defined in devices.c, because this enables access to the register base of the specified ports.

The IntHandlerID structure

You must ensure that the order and number of entries in this structure is the same as defined in devices.s, because this is the basis for the jump table in suppasm.s.

You must also place the labels in makelo.c to ensure that they are available for suppasm.s.

Copyright © 1997, 1998 ARM Limited. All rights reserved.ARM DUI 0040D
Non-Confidential