ARM ® FirmwareSuite Reference Guide

Version 1.4


Table of Contents

Preface
About this document
Intended audience
Using this book
Typographical conventions
Further reading
ARM publications
Other publications
Feedback
Feedback on this book
Feedback on the ARM Firmware Suite
1. Introduction to the ARM Firmware Suite
1.1. About the ARM Firmware Suite
1.2. AFS directories and files
1.2.1. AFS installation layout
1.2.2. AFS source code organization
2. µHAL Application Programming Interfaces
2.1. About the µHAL APIs
2.1.1. µHAL-specific function types
2.1.2. Simple and extended API functions
2.1.3. Rebuilding the µHAL library
2.2. Simple API memory functions
2.2.1. uHALr_StartOfRam()
2.2.2. uHALr_EndOfFreeRam()
2.2.3. uHALr_EndOfRam()
2.2.4. uHALr_HeapAvailable()
2.2.5. uHALr_InitHeap()
2.2.6. uHALr_malloc()
2.2.7. uHALr_free()
2.2.8. Example of heap allocation and de-allocation
2.3. Simple API interrupt functions
2.3.1. uHALr_InitInterrupts()
2.3.2. uHALr_RequestInterrupt()
2.3.3. uHALr_FreeInterrupt()
2.3.4. uHALr_EnableInterrupt()
2.3.5. uHALr_DisableInterrupt()
2.4. Simple API MMU and cache functions
2.4.1. uHALr_ResetMMU()
2.4.2. uHALr_InitMMU()
2.4.3. uHALr_EnableCache()
2.4.4. uHALr_DisableCache()
2.4.5. Memory management and cache code example
2.5. Simple API timer functions
2.5.1. uHALr_CountTimers()
2.5.2. uHALr_InitTimers()
2.5.3. uHALr_RequestSystemTimer()
2.5.4. uHALr_InstallSystemTimer()
2.5.5. System timer programming example
2.5.6. uHALr_RequestTimer()
2.5.7. uHALr_InstallTimer()
2.5.8. uHALr_FreeTimer()
2.5.9. uHALr_GetTimerInterval()
2.5.10. uHALr_SetTimerInterval()
2.5.11. uHALr_GetTimerState()
2.5.12. uHALr_SetTimerState()
2.5.13. uHALr_EnableTimer()
2.6. Simple API support functions
2.6.1. uHALr_memset()
2.6.2. uHALr_memcmp()
2.6.3. uHALr_memcpy()
2.6.4. uHALr_strlen()
2.7. Simple API LED control functions
2.7.1. LED states and addresses
2.7.2. uHALr_CountLEDs()
2.7.3. uHALr_InitLEDs()
2.7.4. uHALr_ResetLED()
2.7.5. uHALr_SetLED()
2.7.6. uHALr_ReadLED()
2.7.7. uHALr_WriteLED()
2.7.8. LED control code example
2.8. Serial input/output functions, definitions,and macros
2.8.1. uHALr_ResetPort()
2.8.2. uHALr_getchar()
2.8.3. uHALr_putchar()
2.8.4. uHALr_printf()
2.8.5. uHALir_InitSerial()
2.8.6. Serial input/output code example
2.8.7. Serial input output board-specific definitions andmacros
2.9. Extended API initialization functions
2.9.1. uHALir_InitTargetMem()
2.9.2. uHALir_InitBSSMemory()
2.9.3. uHALir_PlatformInit()
2.10. Extended API interrupt handling functions
2.10.1. uHALir_TrapIRQ()
2.10.2. uHALir_NewVector()
2.10.3. uHALir_NewIRQ()
2.10.4. uHALir_DefineIRQ()
2.10.5. uHALir_DispatchIRQ()
2.10.6. uHALir_UnexpectedIRQ()
2.11. Extended API software interrupt (SWI)function
2.11.1. uHALir_TrapSWI()
2.12. Extended API MMU and cache functions
2.12.1. uHALir_EnableICache()
2.12.2. uHALir_DisableICache()
2.12.3. uHALir_EnableDCache()
2.12.4. uHALir_DisableDCache()
2.12.5. uHALir_CleanCache()
2.12.6. uHALir_CleanDCache()
2.12.7. uHALir_CleanDCacheEntry()
2.12.8. uHALir_EnableWriteBuffer()
2.12.9. uHALir_DisableWriteBuffer()
2.12.10. uHALir_ReadCacheMode()
2.12.11. uHALir_WriteCacheMode()
2.13. Extended API processor execution modefunctions
2.13.1. uHALir_EnterSvcMode()
2.13.2. uHALir_ExitSvcMode()
2.13.3. uHALir_EnterLockedSvcMode()
2.13.4. uHALir_ReadMode()
2.13.5. uHALir_WriteMode()
2.14. Extended API timer functions
2.14.1. uHALir_TimeHandler()
2.14.2. uHALir_DisableTimer()
2.14.3. uHALir_GetTimerInterrupt()
2.14.4. uHALir_GetSystemTimer()
2.15. Extended API coprocessor access functions
2.15.1. uHALir_CpuIdRead()
2.15.2. uHALir_CpuControlRead()
2.15.3. uHALir_CpuControlWrite()
2.16. Library support functions
2.16.1. uHALr_LibraryInit()
2.16.2. uHALir_MMUSupported()
2.16.3. uHALir_MPUSupported()
2.16.4. uHALir_CacheSupported()
2.16.5. uHALir_CheckUnifiedCache()
3. ARM Boot Monitor
3.1. About the boot monitor
3.1.1. Hardware accesses
3.1.2. Setting up a serial connection
3.1.3. Boot monitor functions
3.2. Common commands for the boot monitor
3.2.1. B, Set baud rate
3.2.2. BI, Set default flash boot image number
3.2.3. D, Display system memory
3.2.4. E, Erase application flash
3.2.5. H or ?, Display help
3.2.6. I, Identify the system
3.2.7. L, Load S-records into flash
3.2.8. M, Download an image into RAM
3.2.9. T, System self tests
3.2.10. V, Validate flash
3.2.11. X, Enter board-specific command mode
3.3. Rebuilding the boot monitor
4. Operating Systems and µHAL
4.1. About porting operating systems
4.2. Simple operating systems
4.2.1. About µC/OS-II
4.2.2. Initializing the operating system
4.2.3. Context Switching
4.2.4. Efficiency considerations
4.3. Complex operating system
4.3.1. Reusing definitions
4.3.2. µHAL-based loader application
5. Angel
5.1. About Angel
5.1.1. Angel system resource requirements
5.1.2. Thumb support
5.1.3. Angel system features
5.1.4. Using Angel with a debugger
5.1.5. Downloading Angel to a development board
5.2. µHAL-based Angel
5.2.1. Source directory for Angel
5.2.2. Angel sources and definitions
5.3. Building a µHAL-based Angel
5.3.1. Angel project and makefiles
5.4. Source file descriptions
5.4.1. banner.h
5.4.2. devices.c
5.4.3. makelo.c
5.4.4. timerdev.c
5.4.5. serial.c
5.4.6. target.s
5.4.7. devconf.h
5.5. Device drivers
5.5.1. The SerialControl structure
5.5.2. angel_DeviceControlFn()
5.5.3. Transmit control (ControlTx)
5.5.4. Receive control (ControlRx)
5.5.5. Transmit kickstart (KickStart)
5.5.6. Interrupt handler
5.6. Developing applications with Angel
5.6.1. Planning your development project
5.6.2. Programming restrictions
5.6.3. Using Angel with an RTOS
5.6.4. Using Supervisor mode
5.6.5. Chaining exception handlers
5.6.6. Linking Angel C library functions
5.6.7. Using assertions when debugging
5.6.8. Setting breakpoints
5.6.9. Changing from little-endian to big-endianAngel
5.6.10. Application communications
5.7. Angel in operation
5.7.1. Initialization
5.7.2. Waiting for debug communications
5.7.3. Angel debugger functions
5.7.4. Angel task management
5.7.5. Context switching
5.7.6. Example of Angelprocessing: a simple IRQ
5.8. Angel communications architecture
5.8.1. Overview of the Angel communicationslayers
5.8.2. Boot support
5.8.3. Channels layer and buffer management
5.8.4. Device driver layer
5.8.5. Transmit sequence
5.8.6. Receive sequence
6. Flash Library Specification
6.1. About the flash library
6.2. About flash management
6.3. ARM flash library specifications
6.3.1. Code portability
6.3.2. Accessing flash
6.3.3. flashPhysicalType structure
6.3.4. flashType structure
6.3.5. Flash types
6.3.6. Image management
6.3.7. Porting the Flash Library
6.4. Functions listed by type
6.4.1. Flash library functions, listed bytype
6.4.2. File processing functions, listedby type
6.4.3. SIB functions
6.5. Flash library functions
6.5.1. Flash_Write_Enable()
6.5.2. Flash_Write_Disable()
6.5.3. fLib_DefinePlat()
6.5.4. fLib_FindFlash()
6.5.5. fLib_OpenFlash()
6.5.6. fLib_CloseFlash()
6.5.7. fLib_ReadFlash32()
6.5.8. fLib_WriteFlash32()
6.5.9. fLib_ReadArea()
6.5.10. fLib_WriteArea()
6.5.11. fLib_DeleteArea()
6.5.12. fLib_GetBlockSize()
6.5.13. fLib_ReadImage()
6.5.14. fLib_WriteImage()
6.5.15. fLib_VerifyImage()
6.5.16. fLib_FindImage()
6.5.17. fLib_ExecuteImage()
6.5.18. fLib_DeleteImage()
6.5.19. fLib_ChecksumImage()
6.5.20. fLib_ChecksumFooter()
6.5.21. fLib_UpdateChecksum()
6.5.22. fLib_GetEmptyFlash()
6.5.23. fLib_GetEmptyArea()
6.5.24. fLib_initFooter()
6.5.25. fLib_ReadFooter()
6.5.26. fLib_WriteFooter()
6.5.27. fLib_VerifyFooter()
6.5.28. fLib_FindFooter()
6.5.29. fLib_BuildFooter()
6.6. File processing functions
6.6.1. fLib_ReadFileRaw()
6.6.2. fLib_WriteFileRaw()
6.6.3. fLib_OpenFile()
6.6.4. fLib_CloseFile()
6.6.5. fLib_ReadFileHead()
6.6.6. fLib_WriteFileHead()
6.6.7. fLib_ReadFile()
6.6.8. fLib_WriteFile()
6.7. SIB functions
6.7.1. The SIB flash block
6.7.2. SIB_Open()
6.7.3. SIB_Close()
6.7.4. SIB_GetPointer()
6.7.5. SIB_Copy()
6.7.6. SIB_Program()
6.7.7. SIB_GetSize()
6.7.8. SIB_Verify()
6.7.9. SIB_Erase()
6.8. Using the library
6.8.1. Starting up and finding flash
6.8.2. Reading a file into memory
6.8.3. Preparing and programming an image
6.8.4. Reading an image to a file
6.8.5. Executing an image
7. Using the ARM Flash Utilities
7.1. About the AFU
7.2. Starting the AFU
7.3. AFU commands
7.3.1. User command explanation
7.3.2. List
7.3.3. DiagnosticList
7.3.4. TestBlock
7.3.5. Delete
7.3.6. DeleteBlock
7.3.7. DeleteAll
7.3.8. Program
7.3.9. Read
7.3.10. Quit
7.3.11. Help
7.3.12. Identify
7.4. The Boot Flash Utility
7.4.1. File Types
7.4.2. Setup
7.5. BootFU commands
7.5.1. Help
7.5.2. List
7.5.3. DiagnosticList
7.5.4. Program
7.5.5. Read
7.5.6. Quit
7.5.7. Identify
7.5.8. ClearBackup
7.5.9. BootFU Warning messages
8. PCI Management Library
8.1. About PCI
8.2. PCI configuration
8.2.1. PCI address spaces
8.2.2. PCI-PCI bridges
8.3. The PCI library
8.3.1. Initializing the PCI subsystem
8.3.2. Data structures
8.3.3. Host bridge initialization
8.3.4. Scanning the PCI system
8.3.5. Assigning resources to PCI devices
8.3.6. Rebuilding the PCI library
8.4. PCI library functions and definitions
8.4.1. PCIr_Init
8.4.2. PCIr_ForEveryDevice
8.4.3. PCIr_FindDevice
8.4.4. PCI definitions
8.5. About µHAL PCI extensions
8.6. µHAL PCI function descriptions
8.6.1. uHALir_PCIInit
8.6.2. uHALr_PCIHost
8.6.3. uHALr_PCICfgRead8
8.6.4. uHALr_PCICfgRead16
8.6.5. uHALr_PCICfgRead32
8.6.6. uHALr_PCICfgWrite8
8.6.7. uHALr_PCICfgWrite16
8.6.8. uHALr_PCICfgWrite32
8.6.9. uHALr_PCIIORead8
8.6.10. uHALr_PCIIORead16
8.6.11. uHALr_PCIIORead32
8.6.12. uHALr_PCIIOWrite8
8.6.13. uHALr_PCIIOWrite16
8.6.14. uHALr_PCIIOWrite32
8.6.15. uHALir_PCIMapInterrupt
8.7. Example PCI device driver
9. Using the DHCP Utility
9.1. DHCP overview
9.1.1. Requirements
9.2. Using DHCP
9.3. Configuration files
10. Chaining Library
10.1. About exception chaining
10.2. The SWI interface
10.2.1. 0x35, SYS_AGENTINFO
10.2.2. 0x36, SYS_VECTORCHAIN
10.3. Chain structure
10.4. Owners and users
10.4.1. Element owners
10.4.2. Element users
10.5. Rebuilding the chaining library
10.5.1. PC project files
10.5.2. Unix makefile
11. Libraries and Support Code
11.1. Library naming
11.2. Rebuilding libraries
11.2.1. Using the CodeWarrior IDE
11.2.2. Using makefiles
11.2.3. Output formats
11.3. Support for VFP
11.3.1. Introduction
11.3.2. Implementation in µHAL
11.3.3. Library support for VFP
11.3.4. VFP images
11.3.5. User trap handlers
11.4. Support for the ADS C library
11.4.1. Introduction
11.4.2. Build variants
11.4.3. Retargetting
A. ARM Firmware Suite on Integrator
A.1. About Integrator
A.1.1. Integrator/AP
A.1.2. Integrator/CP
A.1.3. Logic modules
A.1.4. Build variants
A.2. Integrator-specific commands for bootmonitor
A.2.1. I, Initialize or re-initialize thePCI subsystem
A.2.2. V, Display V3 chip setup
A.2.3. P, Display PCI topology
A.2.4. DPI, Display PCI I/O space
A.2.5. DPM, Display PCI memory space
A.2.6. DPC, Display PCI configuration space
A.2.7. CC, Set clocks from SIB
A.2.8. DC, Display clock frequencies
A.2.9. SC, Set clock frequencies in SIB
A.2.10. DH, Display hardware
A.2.11. G, Go to address
A.2.12. X, Exit board-specific command mode
A.2.13. PEEK, Display memory at address
A.2.14. POKE, Write memory at address
A.2.15. MEM, Enable on-chip memory
A.2.16. ESIB, Erase SIB
A.2.17. R, Run image from flash
A.2.18. H or ?, Display help
A.3. Using the boot monitor on Integrator
A.3.1. Flash on Integrator
A.3.2. Boot switcher
A.3.3. Safe mode
A.3.4. Integrator clocks
A.3.5. LEDs
A.3.6. Multiple core modules with the Integrator/AP
A.3.7. Loading images using the boot monitor
A.4. Angel on Integrator
A.4.1. Location in memory
A.4.2. Caches
A.4.3. Line speed
A.4.4. Downloading Angel
A.5. PCI initialization on Integrator (Integrator/APonly)
A.5.1. Integrator PCI subsystem overview
A.5.2. Initializing the host bridge
A.5.3. PCI configuration cycles
A.5.4. Interrupt routing
B. ARM Firmware Suite on Prospector
B.1. About Prospector
B.2. Prospector-specific commands for bootmonitor
B.2.1. D, Display memory at address
B.2.2. G, Go to address
B.2.3. H or ?, Display help
B.2.4. P, Poke memory at address
B.2.5. R, Run image from flash
B.2.6. V, View images in flash
B.2.7. X, Exit board-specific command mode
B.3. Using boot monitor on Prospector
B.3.1. Connecting to boot monitor
B.3.2. Flash on Prospector
B.3.3. Image formats
B.3.4. Start-up sequence
B.3.5. Prospector system-specific boot monitor
B.3.6. Loading images using boot monitor
B.4. Angel on Prospector
B.4.1. Image format
B.4.2. Location in memory
B.4.3. Caches
B.4.4. Line speed
C. ARM Firmware Suite on the Intel IQ80310 and IQ80321
C.1. About the IQ80310 development kit
C.1.1. AFS support
C.2. About the IQ80321 development kit
C.2.1. AFS support
C.3. IQ-specific commands for boot monitor
C.3.1. D, Display memory at address
C.3.2. G, Go to address
C.3.3. H or ?, Display help
C.3.4. P, Poke memory at address
C.3.5. R, Run image from flash
C.3.6. V, View images in flash
C.3.7. X, Exit board-specific command mode
C.4. Using boot monitor on the Intel IQsystems
C.4.1. Connecting to boot monitor
C.4.2. Flash memory
C.4.3. Boot switcher
C.4.4. Start-up sequence
C.4.5. System-specific boot monitor
C.4.6. Loading images using boot monitor
C.5. Angel on the Intel IQ systems
C.5.1. Image format
C.5.2. Location in memory
C.5.3. Caches
C.5.4. Line speed
C.5.5. Initial loading of Angel into flash
C.6. Flash recovery
C.6.1. IQ80310 Coyanosa
C.6.2. IQ80321 Worcester
D. ARM Firmware Suite on the ARM Evaluator-7T
D.1. About Evaluator-7T
D.1.1. AFS on the Evaluator-7T
D.2. Evaluator-7T-specific commands forboot monitor
D.2.1. D, Display memory at address
D.2.2. G, Go to address
D.2.3. H or ?, Display help
D.2.4. P, Poke memory at address
D.2.5. R, Run image from flash
D.2.6. V, View images in flash
D.2.7. X, Exit board-specific command mode
D.3. Using boot monitor on the Evaluator-7T
D.3.1. Connecting to boot monitor
D.3.2. Flash memory
D.3.3. Boot switcher
D.3.4. Start-up sequence
D.3.5. System-specific boot monitor
D.4. Angel on the Evaluator-7T
D.4.1. Image format
D.4.2. Caches
D.4.3. Location in memory
D.4.4. Line speed
D.4.5. Setting up Angel
D.5. Manufacturing image
E. ARM Firmware Suite on the Agilent AAED-2000
E.1. About AAED-2000
E.2. AAED-2000-specific commands for bootmonitor
E.2.1. D, Display memory at address
E.2.2. G, Go to address
E.2.3. H or ?, Display help
E.2.4. P, Poke memory at address
E.2.5. R, Run image from flash
E.2.6. V, View images in flash
E.2.7. X, Exit board-specific command mode
E.3. Using boot monitor on AAED-2000
E.3.1. Connecting to boot monitor
E.3.2. Flash on AAED-2000
E.3.3. Image formats
E.3.4. Start-up sequence
E.3.5. AAED-2000 system-specific boot monitor
E.3.6. Loading images
E.4. Angel on the AAED-2000
E.4.1. Image format
E.4.2. Location in memory
E.4.3. Caches
E.4.4. Line speed
E.4.5. Initial loading of Angel into flash
F. Integrator CM/922T-XA10
F.1. About the Integrator/CM922T-XA10
F.2. Excalibur922T system-specific commandsfor boot monitor
F.2.1. G, Go to address
F.2.2. X, Exit board-specific command mode
F.2.3. PEEK, Display memory at address
F.2.4. POKE, Write memory at address
F.2.5. ESIB, Erase SIB
F.2.6. R, Run image from Flash
F.2.7. H, or ?, Display help
F.3. Using the boot monitor on Excalibur922T
F.3.1. Flash on Excalibur922T
G. API Quick Reference
G.1. µHAL
G.1.1. µHAL-specific function types
G.1.2. µHAL APIs
G.2. Flash APIs
G.3. PCI APIs
Glossary

Proprietary Notice

Words and logos marked with ® or ™ are registered trademarks or trademarksowned by ARM Limited. Other brands and names mentioned herein maybe the trademarks of their respective owners.

Neither the whole nor any part of the information containedin, or the product described in, this document may be adapted orreproduced in any material form except with the prior written permissionof the copyright holder.

The product described in this document is subject to continuousdevelopments and improvements. All particulars of the product andits use contained in this document are given by ARM in good faith.However, all warranties implied or expressed, including but notlimited to implied warranties of merchantability, or fitness forpurpose, are excluded.

This document is intended only to assist the reader in theuse of the product. ARM Limited shall not be liable for any lossor damage arising from the use of any information in this document,or any error or omission in such information, or any incorrect useof the product.

Revision History
Revision A September1999 New document (internal release)
Revision B September1999 First release
Revision C February2000 Second release
Revision D October2000 Third release
Revision E March2001 Fourth release
Revision F March2002 Fifth release
Revision G September2002 Interim release for Excalibur support
Copyright © 1999-2002 ARM Limited. All rights reserved. ARM DUI 0102G
Non-Confidential