OMAP3 HAL (changes)

Showing changes from revision #3 to #4: Added | Removed | Changed

This page contains technical details relating to the implementation of the OMAP3 HAL, specifically which source file does what. The source can be viewed online here in the CVS viewer.

Source overview

• Top.s – This contains the HAL entry points (one per board config), along with the related code to copy the right board config into SRAM¹, make sure the CPU is in a safe state, relocate the ROM image to the top of RAM (to avoid fragmenting the physical memory map), and to clear the rest of RAM. You’ll also note that it directly includes board.s² and RAM.s³
• board.s – Contains the board config structures
• RAM.s – Code to clear RAM using the DMA controller. At one point the file also contained code to initialise RAM, but that was quickly removed once it was realised that it was much easier just to allow u-boot to handle it for us (especially since the ROM runs on many different board types, each requiring their own unique RAM parameters)
• Boot.s – This is where execution goes to after Top.s. It contains the call to RISCOS_Start, along with the entry point table that RISC OS uses to call the HAL, and implementations of all the miscellaneous HAL entry points (HAL_Init, HAL_InitDevices, HAL_PlatformInfo, HAL_Reset, etc.)
• Audio.s – Implementation of the audio driver, as a HAL device (HALDeviceAudio_AudC and HALDeviceAudio_Mixer)
• CLibAsm.s – Assembler implementations of some functions that are typically required when using C within the HAL. I’m not sure how much of this is actually needed at the moment.
• CPUClk.s – Implementation of the CPU clock generator device (HALDeviceSysPeri_CPUClk) that the PortableHAL module uses to control the CPU speed.
• Debug.s – HAL_DebugTX and HAL_DebugRX implementations (as used by the kernel for the ‘DebugTerminal’ serial console), along with some other miscellaneous debugging functions used by the HAL.
• GPIO.s – A few utility functions for interacting with the various GPIOs – both the ones provided by the OMAP GPIO controller, and the ones provided by the TWL/TPS GPIO controller. There are also various GPIO related macros in GPIO.hdr. Also contains the implementation of the GPIO HAL device (HALDeviceComms_GPIO)
• GPMC.s – A few uility functions for configuring the OMAP GPMC bus – required for access to NICs, NAND, etc.
• I2C.s – I^2^C driver. It’s exposed to RISC OS via the HAL IIC API, not a HAL device (partly because the functions need to be used before HAL_InitDevices has been called, and partly because it predates the introduction of HAL devices)
• Interrupts.s – Implementation of the HAL interrupt handling API
• KbdScan.s – Implementation of the HAL keyboard API
• NIC.s – Code to expose any attached NIC to RISC OS as a HALDeviceComms_EtherNIC device.
• NVMemory.s – Assembler interface to the NVRAM code (via the HAL NVRAM API)
• PRCM.s – A few utility functions for calculating clock speed divisors and the like
• RTC.s – RTC driver, implemented as a HAL device (HALDeviceSysPeri_RTC)
• SDMA.s – DMA driver, implemented as a set of HAL devices – one HALDeviceSysPeri_DMAC and 31 HALDeviceSysPeri_DMAB (i.e one per DMA channel. The 32nd channel is reserved for direct use by the video driver, since the SDMA rectangle copy/fill functionality is a bit too exotic for DMAManager to understand)
• Stubs.s – Stub implementations of HAL entry points/APIs that (so far) don’t have full implementations.
• TPS.s – Some generic routines used by the HAL to read/write registers from the TWL/TPS
• Timers.s – HAL timer API implementation
• UART.s – HAL UART API implementation
• USB.s – HAL USB API implementation
• Video.s – Depends on the setting of the ‘HALDoesVideo’ switch in omap3530.hdr. If it’s TRUE, it contains a working implementation of the HAL Video API. If it’s FALSE, it contains a dummy implementation of that API, and instead exposes the video controller to RISC OS via a HALDeviceVideo_VDU device (which the OMAPVideo module then detects)
• Clib.c – Contains C implementations of various utility functions typically provided by the C library (strlen, sprintf, etc.). I don’t think any of this actually gets used at the moment.

Also, a few notable header files:

• omap3530.hdr – Contains general build options, the OMAP physical memory map, and some debugging macros
• Post.hdr – File inherited from the Tungsten HAL; isn’t strictly needed by the OMAP HAL³.
• StaticWS.hdr – Contains the layout of the HAL workspace pointed to by the ‘sb’ register.
• board.hdr – Contains the layout of the baord configuration structures, and the related video configuration structures.

Use of multiple entry points

Although boards such as the beagleboard provide well-defined methods for an OS to determine the board revision by probing the hardware, there is no such standard for determining board type/manufacturer. Thus the OMAP3 HAL provides one entry point per board type, allowing the OS to determine the board type merely by checking which entry point was used. This scheme works well for situations where a headerless ROM image is used (e.g. a ROM image produced by !Builder), and where it’s trivial to have the bootloader use the correct entry point (e.g. the standard u-boot scripts that use the ‘fatload’ and ‘go’ commands).

For situations where headerless ROMs are either not possible or not satisfactory (e.g. if the ROM has been written to a potentially volatile medium such as NAND, or if it’s impossible to reconfigure u-boot to not use a uImage), there is an additional entry point at offset &64 that assumes the ROM is being used as if it were a Linux kernel image. On entry to an ARM Linux kernel, the R2 register contains the machine type ID. the selectconfig_linux routine in Top.s utilises this fact to search the board config list for the correct configuration.

At present, the full list of entry points are as follows:

Footnotes

¹ At the moment there’s no defined way for the HAL to generate some data, call RISCOS_Start, and then access that data once RISC OS has initialised (i.e. when HAL_Init gets called). Which means that (unless I was to add that functionality) the easiest way of getting the HAL to remember what board config is in use is if it gets copied into the 64K of SRAM, which RISC OS currently has no knowledge of and thus doesn’t touch. HAL_Init actually copies the data back out of SRAM and into the HAL workspace pointed to by the sb register – this makes it slightly easier for the HAL to get at the data, since all the HAL entry points get called with sb pointing at the HAL workspace.

² board.s is included directly mainly just to make sure it’s kept within range of ADR. It also makes it slightly easier to check that the ROM entry point table contains the right number of entries.

³ The OMAP HAL was based around a stripped down version of the Iyonix (aka Tungsten) HAL, which contains the ROM entry point & RAM initialisation code within the first 8K of ROM, along with code which performs a checksum of the ROM image. If the checksum fails it flashes the floppy light and allows a new ROM image to be uploaded & programmed via the serial port. The recovery code (and I assume the official flash programmer) avoids overwriting the first 8K of flash, so this code (in theory) makes an Iyonix unbrickable. So although it’s now clear that this recovery code is unlikely to be needed by the OMAP ROM, some remnants of its existence still remain.