WarpUp hardware driver protocol version 1 © 4.2.1998 HAAGE&PARTNER Gmbh Written by Sam Jordan $VER: WarpHW.txt 1.0 (4.2.98) ----------------------------------------- 1. Introduction --------------- This document describes the WarpUp hardware driver protocol which allows anyone to write driver software for PowerPC hardware supporting the WarpUp-HAL for dual processor systems. The WarpUp-HAL was splitted up since version 3 into two parts, the main HAL (warp.library) and the hardware driver (warpHW.library). The warp.library now opens the warpHW.library and calls its functions to get control over the specific hardware. Note that the hardware drivers only work with warp.library version 3 and higher. Every hardware which provides a driver named 'warpHW.library' will work with the WarpUp-HAL (and therefore with WarpOS). These different libraries can be distinguished by the tool program 'GetDriverInfo' which prints out the identification string and the largest protocol number supported. This tool should always be found with this documentation together. Just run it and it will print out the information, if the warpHW.library was found. 2. Requirements --------------- To write a WarpUp hardware driver you need a 68K C compiler, a PPC C compiler supporting WarpUp and a linker which can deal with the extended hunk format. StormC supports all this and other compilers might support it in future. Of course, it's possible to write the driver completely in assembler, but better use C instead. The WarpHW.library is a mixed shared library, since it provides functions for the 68K side and the PowerPC side. 3. API notes ------------ This document describes the protocol version 1, which is the first version released. If anyone needs more API functions because of special hardware features or for other reasons, this protocol will be enhanced and new versions will be released. In this case it's very likely that the HAL itself must be updated to support the new API. But older hardware drivers will work without modification, since the WarpUp-HAL will ask the driver for the maximal protocol version which is supported. Anyone which requires enhancements to the protocol should contact us, the appropriate links can be found at the bottom of this document. 4. Template ----------- In the directory there is a template for a new hardware driver which should be helpful for development. You will find the following files of importance: - WarpHW.¶ : 68K-Storm-Project, which is the main project here - WarpHW_PPC.¶ : PPC-Storm-Project, which is a subproject of WarpHW.¶ - WarpHW.c : C source compiled for 68K, containing the 68K API functions - WarpHW_PPC.c : C source compiled for PPC, containing the PPC API functions - WarpHW_68K.s : A small 68K assembler function to perform NOP synchronisation - WarpHW_PPC_asm.p : Some small PPC assembler functions to perform ISYNC/SYNC synchronisation and to provide some important functions for the linker. - WarpHW_lib.fd : The FD file for the WarpHW.library First compile the PPC project to gain the object files 'WarpHW_PPC.o' and 'WarpHW_PPC_asm.o'. Afterwards add those object files to the 68K project and compile the main project. Finally link everything together to a shared library. Important Note: Never create a Storm-Project with 'Mixed Binary' option to write a hardware driver. This can't work because of callbacks to the powerpc.library/warp.library in the library initialisation of the warpHW.library. It's the best way to take the template project and to add the code. 5. Protocol description ----------------------- This chapter discusses the interaction between the WarpUp-HAL and the hardware drivers. a) Evaluating the address of the PowerPC exception area The WarpUp-HAL needs the location of the PowerPC exception area and therefore calls the WarpHW API function 'InitBootArea'. This function must return this location and should set up the hardware so that the address space of the exception area (starting from 0xfff00000) is mapped to the real location. This mapping can't be done by the MMU since the exception area is located at physical address 0xfff00000. Hardware logic should perform this mapping. The exception area has to be located in writeable address space. The API function is allowed to allocate the required memory. Note that the exception area has to be aligned on a 64KB boundary and must be at least 64KB large. Note that the first 256 bytes of the exception area space are reserved for the WarpUp HAL itself. b) Resetting the PowerPC After step a) the reset exception routine is prepared and some fields of the exception area are initialized. After that, the PowerPC is reset by calling the WarpHW API function 'BootPowerPC'. This function should initialize all hardware registers and reset the PPC processor which should start execution at 0xfff00100, where the reset routine is located. c) Causing the PowerPC interrupt On dual processor systems, the WarpUp-HAL needs the possibility to cause an external PPC interrupt by the 68K processor. In this case the WarpHW API function 'CauseInterrupt' is called. This function should drive the INT signal of the PPC to active state. The signal should be kept in active state, until the interrupt was confirmed by the PPC interrupt handler (by calling 'ConfirmInterrupt', see below). d) Confirming the PowerPC interrupt After an external interrupt was caused from the 68K side, the PowerPC enters into the external interrupt handler. This handler calls the WarpHW API function 'ConfirmInterrupt' to confirm the interrupt. This function should drive the INT signal to inactive state. 6. API description ------------------ This chapter dicusses the API functions in more detail. For better readability, they are written in autodoc format. Note, that all API functions should preserve the smalldata base. Use the keyword __saveds in the function declaration or use the template sources. Also note, that you can use the functions 'sync' (68K) and 'syncPPC' (PPC) to perform memory/command synchronisation. 'sync' executes one NOP instruction, 'syncPPC' an ISYNC/SYNC pair. Both functions can be found in the template project as assembler sources. If the appropriate objects are present, just take them and link with the other objects. warpHW.library/GetDriverID warpHW.library/GetDriverID NAME GetDriverID - returns a driver identification string (V1) CPU 680x0 MANDATORY Yes SYNOPSIS IDstring = GetDriverID(void) d0 char* GetDriverID(void) FUNCTION This function returns a string identifying this WarpUp hardware driver. The string should be of the following format: "WarpUp hardware driver for " The hardware identification must be unique across several PPC hardware. RESULT IDstring - The identification string of this WarpUp hardware driver warpHW.library/SupportedProtocol warpHW.library/SupportedProtocol NAME SupportedProtocol - returns the max. protocol version supported (V1) CPU 680x0 MANDATORY Yes SYNOPSIS Version = SupportedProtocol(void) d0 int SupportedProtocol(void) FUNCTION This function returns a version number telling the WarpUp HAL the highest driver protocol version which is supported by this driver. This function exists for backward compatibility, so that the WarpUp HAL won't call functions which don't exist in older hardware drivers. RESULT Version - The max. driver protocol version number supported warpHW.library/InitBootArea warpHW.library/InitBootArea NAME InitBootArea - evaluates the address of the PowerPC exception area (V1) CPU 680x0 MANDATORY Yes SYNOPSIS ExcArea = InitBootArea(void) d0 void *InitBootArea(void) FUNCTION This function returns the address of the PowerPC exception area. This area must be in writeable address space and must be aligned to a 64KB boundary and must be at least 64KB large. The function should setup the hardware so that it maps the physical address space of the exception area (starting with address 0xfff00000) to the real location of the exception area. This function can allocate the memory itself and doesn't have to care for memory freeing. RESULT ExcArea - Address of the PowerPC exception area warpHW.library/BootPowerPC warpHW.library/BootPowerPC NAME BootPowerPC - resets the PowerPC (V1) CPU 680x0 MANDATORY Yes SYNOPSIS void BootPowerPC(void) void BootPowerPC(void) FUNCTION This function resets the PowerPC processor which should start execution at physical address 0xfff00100, where the reset routine was installed by the WarpUp HAL. In this function, all hardware registers which require initialization, should be initialized. warpHW.library/CauseInterrupt warpHW.library/CauseInterrupt NAME CauseInterrupt - trigger the PowerPC' external interrupt (V1) CPU 680x0 MANDATORY Yes SYNOPSIS void CauseInterrupt(void) void CauseInterrupt(void) FUNCTION This function causes a PowerPC external interrupt. It should drive the INT signal of the PowerPC to active state and should keep it active, until the interrupt was confirmed from the PPC side (see 'ConfirmInterrupt') warpHW.library/ConfirmInterrupt warpHW.library/ConfirmInterrupt NAME ConfirmInterrupt - confirms the external interrupt (V1) CPU PowerPC MANDATORY Yes SYNOPSIS void ConfirmInterrupt(void) void ConfirmInterrupt(void) FUNCTION This function is called from the WarpUp-HAL in the external interrupt exception handler to confirm the interrupt. The function should drive the INT signal to inactive state. NOTES This function is called with data cache frozen, therefore any accesses which don't hit the cache are noncachable. And the hardware registers should never be located in the cache, since they are never accessed outside of 'ConfirmInterrupt' by the PowerPC. 7. Contact addresses -------------------- regular mail: eMail: HAAGE&PARTNER GmbH s.jordan@haage-partner.com Mainzer Starße 10A 61191 Rosbach Tel: 06007/930050 Fax: 06007/7543