Adding New Targets to DRAMA

Last Update 16-Feb-2006

Valid from DRAMA Version 1.3b3 Only

Really just a quick summary - could have more detail

This page attempts to demonstrate how to add support for a new TARGET to DRAMA. There is a farily consistent approach for each new UNIX target and for each new VxWorks target. Other targets are far harder and will not be documented here.

Adding New Unix Targets to DRAMA

You need to port DRAMA for a Unix host if you get the following error when attempting the build 
Target not known to DRAMA
    Please see http://drama.aao.org.au/html/DramaNewTarget.html
       for details on how to port DRAMA
This indicates your host machine is not known by DRAMA. DRAMA uses a scheme which requires that it be explicitly ported to each architecture to be supported. Normally, for a new UNIX host, there is not much work to do.

Select "hosttype" string

DRAMA requires that there be a string which uniquely identifies the combination of architecture and operating system. Because the same operating system may run on different architectures and a given architecture may support different operating systems, this string must indicate the combination of both.

For example, on OSF (Digital Unix) running on an Alpha, we use alpha_osf1. For VMS running on an Alpha, the equivalent is alphavms. Whilst we don't support it as yet, linux on an Alpha would be alpha_linux, whilst the supported linux on x86 is linux_x86. (I must admit to not having been consistent in the past with the structure of these names, but I currently suggest operating system, followed by underscore followed by architecture).

The standard way of determining the operating system and architecture under Unix is using the uname command. We are interested in the output of this command when using the -s and -h options. For example, using both these options on a Alpha running OSF, I get. 
OSF1 alpha
For a Sparc running Solaris, things are more complicated. I get 
SunOS sun4u
The complication is in two parts. First, the hardware name always starts with sun4 but may have a different following letter. Secondly, I can't tell the difference between the old SunOS system (SunOs V 4 and older) and the newer Solaris systems (SunOs V 5 and onwards), which is significant as they have different executable formats. The combination of awk on the machine type and use of the uname -r command can sort this out.

But normally just the use of uname -s and uname -h are sufficent to sort it out and our example assumes it is. The DRAMA source code shows how the more complicated examples are handled.

Our example is porting DRAMA to Mac OS X - the new unix based operating system for the Machintosh. Here, uname -s -m returns 
Darwin Power Machintosh
So, the software name is Darwin whist the hardware name is Power Machintosh. I will choose the name macosx_ppc for the DRAMA port. Note that whilst uname may include a string with spaces, the DRAMA name should not. It should be noted at this point that I can't tell the difference between the Darwin OS on which Mac OS X is based and Mac OS X - but I don't believe this matters, as DRAMA does not use Mac OS X specific items.

To implement this, I have to edit the file drama_source/config/hosttype . The main part of this file currently contains something like this 
HARDWARE=`uname -m`
SOFTWARE=`uname -s`
HOSTTYPE=unknown
if [ "${SOFTWARE}" = "Linux" ]; then

    if [ "${HARDWARE}" = "ppc" ]; then
        HOSTTYPE=linux_ppc
    elif [ `echo ${HARDWARE} | awk '{print substr($1,3,4)}'` = "86" ]; then
        HOSTTYPE=linux_x86
    fi
elif [ "${HARDWARE}_${SOFTWARE}" = "RISC_ULTRIX" ]; then
    HOSTTYPE=decstation
elif [ "${HARDWARE}_${SOFTWARE}" = "alpha_OSF1" ]; then
    HOSTTYPE=alpha_osf1
elif [ `echo ${HARDWARE} | awk '{print substr($1,1,4)}'` = "sun4" ]; then
#    We are on a sun4.  May be Solaris 1 (Sun OS 4) or Solaris 2
    if [ `uname -r | awk '{print substr($1,1,1)}'` = "4" ]; then
        HOSTTYPE=sun4
    else
        HOSTTYPE=sun4_solaris
    fi
fi
You can see the uname is used to get the hardware and software names and then the "if" statement sets the variable HOSTTYPE to the correct DRAMA type. I will add the following line just before the last fi shown above 
elif [ "${HARDWARE} ${SOFTWARE}" = "Power Machintosh Drawin" ]; then
    HOSTTYPE=macosx_ppc

Note for AAO source code management

The ACMM archive for this is DramaConfig and the file name is hosttype.

IMAKE makefile

The DRAMA IMAKE system is based on the system of the same name in the X11 environment. The program imake runs the C preprocessor over a user makefile description (DRAMA's dmakefile's), using information about the target machine and generates the appropiate Makefile. But before this can happen, you must build imake, so imake is the one part of DRAMA that has a makefile specific to each architecture.

The files in question are in drama_source/config. You will see there is a file of the format makefile.imake.target for each support unix target, where target is the value returned by hosttype for each target. There are few differences between these files, often just the compiler name and/or flags and possibly the value of the macro BOOTSTRAPCFLAGS. Select one and copy it to the appropiate name for your new target. For Mac Os X, I will use makefile.imake.linux_ppc, copying it to makefile.imake.macosx_ppc.

Having done this, you may need to edit the file to ensure each of the commands are correct, but this is normally ok. The only other thing to do is determine if there is a C compiler macro which uniquely identifies your operating system. For example, __linux__ will be defined under linux. You must ensure this macro is defined under all compiler options - for example, linux is defined by GCC under linux but not when the -ansi flag is specified. If your compiler is GCC then execute the following commands to list the macros available 
touch junk.c
gcc -ansi -E -dM junk.c 
gcc -traditional -E -dM junk.c 
rm junk.c
You can now see what the two iterations of the gcc compiler produce. Normally something defined under -ansi is also defined under -traditional but you should check to be sure

For other compilers, look at the documentation. If no such macro is defined, define one yourself and use the makefile BOOTSTRAPCFLAGS variable to define it. E.g. 
BOOTSTRAPCFLAGS = -D__MACOSX_PPC__=1
In Mac OS X, when I used the "-ansi" flag, nothing was output.  But when I used "-traditional" the following was output
#define __MACH__ 1
#define __NATURAL_ALIGNMENT__ 1
#define __APPLE__ 1
#define __GNUC_MINOR__ 95
#define __ppc__ 1
#define __GNUC__ 2
#define __DYNAMIC__ 1
#define __APPLE_CC__ 937
#define __BIG_ENDIAN__ 1

A little experiement using "#ifdef" and "#warning" confirmed that these were in fact defined for the "-ansi" case and that there appears to be an error in the compiler for this case.  So we can assume the above are defined.

Note that there is nothing in this case which says both Machintosh and PPC and Mac OS X in one macro.    The operating system is indicated by "__MACH__", which MacOSX is a version of.  You have to combine that with __ppc__ and __APPLE__ work out it is a Mac OSX PPC machine.  So I will defined the makefile BOOTSTRAPCFLAGS variable as above. Note that this definition is only used when imake is built, not when DRAMA programs are built

Now remember the appropiate macro name (__MACOSX_PPC__) for the next stage.

Note for AAO source code management

The ACMM archive for this is DramaConfig. The file should be added to this sub-system and to makefile.release within that sub-system.

Adding the new target to IMAKE

Once you have the name of a Compiler macro specific to your operating system, you must modify IMAKE to support it. Since IMAKE was taken from the X11 source tree, it may already support your machine, check imakemdep.h for any indication of that.

In the directory drama_source/config, edit the file imakemdep.h. Work through this file, obeying the instructions within it to add support for your target. Hopefully, the only changes will be in steps 4, 5 and 6 where the changes will be roughly equivalent to the changes required for Linux.

In this example, I had to make the following changes
You now try to build "imake" using the target specific makefile.  E.g
    
    make -f makefile.imake.macosx_pcc


You may have to modify imake.c to get it to compile.  Be carefull that these changes, if any, are dependent on your __MACOSX_PPC__ macro so that other ports are not impaced.  For the Mac OSX case,  fuction LogFatal() had to be modified such that sys_errlist[] is not declared for Mac OSX, as per the linux case.

Note for AAO source code management

The modified files imakemdep.h and if required, imake.c, should be put back in the DramaConfig ACMM archive.

Generate Target Configuration File

The Target Conqfiguration File defines various details about the target which are not dependent on the local configuration. For example, standard compiler options etc. In this case, we are again using the linux_ppc target as the template.

Goto the drama_source/config sub-directory. Copy the file linux.cf to macosx.cf. Note that here we re using and operating system specific target file. We could also make this operating+architecture specific, but it is normally not required for UNIX OSes.

Work through the file changing things as appropiate. For example, set the values for things such as HasGcc. If the default compiler is gcc then this should be YES.

You should only define in this file things availble on a standard configuration for the target in question. For example, LINUX has Tcl/Tk as standard so has HasTcl and HasTk set to YES, but most UNIX systems will have this to NO . For each of the standard libraries defined which may be used by DRAMA, set the standard location. For Mac OS X, have a look at the file in question.

You also have to set the Target and Host type macros. For a UNIX machine, these have the same value. In the linux.cf file, this is where I pick up my two different linux ports (x86 and PPC).

For Mac OS X, both Target and Host are set to macosx_ppc. There was also another specific issue - Mac OS X uses GCC as the default compiler, but installs it under the command cc rather then gcc (for compatility with standard UNIX. So if the HasGcc macro is set to false, then I set it to yes so the GNU C specific things are enabled, but set the C and C++ compiler commands to use cc and c++.

Then the default options required to compile the DRAMA source on this machine is defined - DefaultCCOptions - and the standard set of defines required for the compliation - StdDefines . Note that for UNIX systems, the -Dunix should always be part of the value of StdDefines. For Mac OS X, I removed the linux specific stuff.

for Mac OS X I had to set the C Pre-Preprocessor related macros CppCmd and DefaultCpp() appropiately, as it is found in /usr/bin/cpp rather then /usr/lib/cpp as in many other architectures.

Add target to the CONFIG sub-system makefile

The DRAMA config sub-system makefile needs to know about the new target. Goto the drama_source/config sub-directory and edit the file makefile

Simply add macosx.cf to the list of files for the FILES macro definition.

Note for AAO source code management

The ACMM archive for this is DramaConfig. You must also add the file (macosx.cf in this case) to the archive and to the list for the RELEASE macro of the file makefile.release.

Add target to target selection file - Target.sel

The Target.sel file is used by the imake scheme to select the target of a DRAMA build

Goto the drama_source/config sub-directory and edit the file Target.sel. In this example, we are basing our changes on the code support Linux PPC.

Search for T_linux_ppc which should be found in the header comments. Duplicate that line and replace T_linux_ppc with T_macosx_ppc and modify the coments as appropiate.

Again search for T_linux_ppc. You should find the following lines 
#ifdef T_linux_ppc
#ifndef linux
#define linux
#endif
#ifndef PPC
#define PPC
#endif
#undef T_linux_ppc
#define ImakeTarget -DTarget -DT_linux_ppc
#define TargetFound
#ifdef Verbose
XCOMM Imake targeting Linux/PPC
#endif
#endif
Duplicate these lines and replace appropiate components. In this case producing 
#ifdef T_macosx_ppc
#ifndef macosx
#define macosx
#endif
#ifndef PPC
#define PPC
#endif
#undef T_macosx_ppc
#define ImakeTarget -DTarget -DT_macosx_ppc
#define TargetFound
#ifdef Verbose
XCOMM Imake targeting Mac OS X/PPC
#endif
#endif

Note for AAO source code management

This file is found in the DramaConfig ACMM archive.

Add target to platform selection file - Platform.sel

The Platform.sel file is used by the imake scheme to select the architecture file we are building for. It requires the macros defined in the Target.sel file - macosx and PPC in our example.

Note that the reason for having both Target.sel and Platform.sel is that DRAMA support cross compiling and hence a different Target machine from the Host platform.

Goto the drama_source/config sub-directory and edit the file Platform.sel. Search for linux You should find the following 
#ifdef linux
#define MacroIncludeFile 
#define MacroFile linux.cf
#define LinuxArchitecture
#undef linux
#ifdef x86
#define X86Architecture
#undef x86
#endif
 
#ifdef PPC
#define PPCArchitecture
#undef PPC
#endif
 
#endif

You can see how by selecting on operating system only, we are selecting an operating system specific version of the architecture file. The linux example then defines a second marco to indicate the hardware architecture, and this macro is used in linux.cf to work out the architecture.

Duplicate these lines, replacing linux as appropiate. Also define a macro which represents the Architecture of the machine (This is used in dmakefiles to select functions dependent on this architecture. In this example, we get 
#ifdef macosx
#define MacroIncludeFile 
#define MacroFile macosx.cf
#define MacOSXArchitecture
#undef macosx

#ifdef PPC
#define PPCArchitecture
#undef PPC
#endif
 
#endif

Note how I defined PPCArchitecture, the same macro used to in the Linux PPC port. This ensures that any code specific to the chip (such as byte order for example) only needs to test the one non operating system specific macro.

Note for AAO source code management

The ACMM archive for this is DramaConfig.

Makedepend

Changes may be required in the drama_source/makedepend sub-system. This sub-system is used to create the "makedepend" command. The source code originated with the X11 command of the same name. I often try to build to see if it fails and if it does, work from there. for Mac OS X, it turned out that the SIGBUS macro is not defined by signal.h if the _POSIX_SOURCE macro is defined, as it is when compling makedepend. I think this is a mistake but am unsure. For a temp fix, I define SIGBUS explictly in makedepend/main.c if __APPLE__ is defined. This is not a good solution but was a quick one. The build will fail if this problem is later fixed but SIGBUG ends up with a different value.

Note for AAO source code management

The ACMM archive for this is DramaMakedepend.

StatusType

DRAMA uses a variable of type StatusType throughout. This is defined by the include file status/status.h. You may need to edit this file to ensure that StatusType is correctly typedefed for the architure. Note that if the architecture is not correctly defined then an error will normally be produced when compiling the first part of DRAMA which uses it (messgen). This should be the same type used by IMP for IMPZ_INT4.

For MacOsX, I added the following 

#elif defined(__APPLE__)
typedef int StatusType;
The reason for using the __APPLE__ macro as the trigger is that this is available regardless of the use of the DRAMA config files.

Note for AAO source code management

The ACMM archive for this is DramaStatus. File status.h.

Messgen byte order

Some files in the messgen library need to know about the byte order of the machine. If you are compiling for an unknown little endian format machine, then messgen will fail. You will need to edit mess.c and messgen.c to support the new machine type. Search for BIGEND in these files and ensure it is set to 0 for this machine. You will need to chose an appropiate C compiler macro to base you test on - note, this should be on the machine architecture, not the operating system.

Note for AAO source code management

The ACMM archive for this is messgen. Files mess.c and messgen.c.

SDS integer and floating point formats

See SDS integer and floating point formats below at this point.

Porting IMP to the new Architecture

The IMP library contains the major DRAMA porting layer. In other areas of DRAMA, porting specific code is fairly minor, but in IMP, the port specific code is quite significant.

The IMP porting layer consists of three files specific to each port, impz.c, impz.h and impz_load.c. When Imp is built, these files are created by coping them from versions specific to the port in question. For example, if building for vxworks impz_vxworks.h is copied to impz.h, impz_vxworks.c is copied to impz.c and impz_load_vxworks.c is copied to impz_load.c. These three files provide Macros and Routines which are or may be different between architectures.

For UNIX machines, the core IMPZ files are largely the same. Differences between different versions of UNIX should be minor so a slightly different structure is used. impz_unix.c and impz_load.c are common to all versions of UNIX. There is a impz.h for each version of UNIX but all of these include a common file, impz_unix_common.h which has most of the information required in the standard impz.h file. The system specific version of impz.h for each version of UNIX serves to parameterize impz_uniz_common.h, impz.c and impz_load.c appropiately for each version of UNIX.

For example, for Alpha OSF, the system specific impz.h is impz_alpha.h, the version of linux is impz_linux.h .

Note that the IMP porting layer is operating system specific, it does not normally need to change for different hardware, although if you go from say a 32 bit machine to a 64 bit machine, there may be some changes. The requirement for these changes can often be picked up from compiler macros.

So what do you do. You need to select an existing impz.h file for a version of UNIX similar to the one you are building for. impz_alpha.h and impz_sunos are for UNIX versions based on BSD UNIX. Whilst impz_solaris.h is for a version of unix based on System V. There is also impz_linux.h. I think linux started off as more BSD compatible but is moving towards System 

Now you need to modify the IMP library dmakefile file to support this operating system. This relies on the IMAKE macro defined in the plateform selection file to indicate this operating system, in this case MacOSXArchitecture . Edit dmakefile to add the following lines after similar lines for the other operating systems 
#if defined(MacOSXArchitecture)
impz.c : impz_unix.c
        $(CP) impz_unix.c impz.c

impz.h : impz_macos.h
        $(CP) impz_macos.h impz.h

impz_load.c : impz_load_unix.c
        $(CP) impz_load_unix.c impz_load.c 
#endif
Note - I would have chosen impz_macosx.h as the name of the file here, but Keith (who maintains IMP) had separately chosen impz_macos.h - hence the use of that name.

Note for AAO source code management

The new impz_target.h file should be added to the imp ACMM sub-system and the makefile.release in that directory modified to release the new file.

The dmakefile modified is found in the same ACMM archive directory

Building DRAMA

You are now ready to build try to build DRAMA on your machine. Enter the drama_make command. E.g. 
./drama_make
You may find various standard porting problems at this stage. Include files that are not found or have different format, imperfection in the IMPZ code.

Please see Installing and Building DRAMA for help from here. In particular, the Build Problems topic on that page will be useful.

imake problem (Linux and Mac OS X)

I had a particular issue with imake under both Linux and Mac OS X. It appears the version of imake I have does not work with the version of the C pre-processor on these platforms. I will at some point fix this problem correctly, bit it so happens that Linux and the Mac OS X both have their own versions of imake which will work. So I modified drama_source/config/dmkmf to pick up the installed version of imake.

Files to be returned to AAO

If you want you port to be part of future DRAMA releases, you will need to send your results back to tony.farrell@mq.edu.au  . Please send the new files you have generated. In this example, these are the files 
drama_source/config/imake.makefile.macosx_ppc
drama_source/config/macosx.cf
drama_source/imp/impz_macos.h
Also send diffs for each of the modified files, which may include the following 
drama_source/config/hosttype
drama_source/config/makefile
drama_source/config/Target.sel
drama_source/config/Platform.sel
drama_source/config/imakemdep.h
drama_source/config/imake.c
drama_source/status/status.h
drama_source/imp/dmakefile
drama_source/sds/sds.h
drama_source/sds/sds.c

Adding a New VxWorks Target

This is normally easy most of it involves copying and then modifying if necessary an existing configuration.

Select a name for the target

Current names include vw68k for VxWorks on a 68K processor, vwppc for VxWorks on a Power PC (PPC) processor. Lets assume we are doing the Gismo 98X port and have chosen the name vw98x as the target name. (Lower case is perferred as you will be typing this name a bit). We are going to largely clone vw68k to generate this.

Add support to drama_make

Support for the specified target needs to be added to the drama_make build script in the top level DRAMA directory

Edit the file and search for vw68k. The first entry is in the comments for the support target. Duplicate that entry and change vw68k to vw98x in the duplicate line and comment accordingly.

Search for the second occurance of vw68k. This has the form 
    vw68k)
        echo "$0:Targeting vw68k"
        target="-t vw68k"
        nocompcheck=true
        ;;
Duplicate these lines and then replace vw68k by vw98x .

That all that is required for drama_make.

Generate Target Configuration File

The Target Configuration File defines various details about the target which are not dependent on the local configuration. For example, standard compiler options etc. In this case, we are again using the vw68k target as the template.

Goto the drama_source/config sub-directory. Copy the file vw68k.cf to vw98x.cf. Now edit this file

Work through the file changing things as appropiate. For example, the VxWorks version stuff, define settings for the CpuMac, GccMOpt and Target macros (Target should be vw98x)

Define the value for the CcCmd macros etc (CcCmd defines the compiler name, AsCmd defines the assembler name, similarly for RanlibCmd, LdCmd and ArCmd.

Add target to the CONFIG sub-system Makefile

The config sub-system Makefile needs to know about the new target. Goto the drama_source/config sub-directory and edit the file Makefile

Simply add vw98x.cf to the list of files for the FILES macro definition.

Note that running this second Makefile will clobber the makefile by overwriting it with makefile.release.

Add target to target selection file - Target.sel

The Target.sel file is used by the imake scheme to select the target of a DRAMA build

Goto the drama_source/config sub-directory and edit the file Target.sel

Search for T_vw68k which should be found in the header comments. Duplicate that line and replace vw68k with vw98x and modify the coments as appropiate.

Again search for T_vw68k. You should find the following lines 
#ifdef T_vw68k
#define vw68k
#undef T_vw68k
#define ImakeTarget -DTarget -DT_vw68k
#define TargetFound
#ifdef Verbose
XCOMM Imake targeting VxWorks on 680x0
#endif
#ifdef sun_solaris
XCOMM sun solaris is defined - undefining it
#undef sun_solaris
#endif
#endif
Duplicate these lines and replace approopiate components. In this case producing 
#ifdef T_vw98x
#define vw98x
#undef T_vw98x
#define ImakeTarget -DTarget -DT_vw98x
#define TargetFound
#ifdef Verbose
XCOMM Imake targeting VxWorks on a Gismo 98X 
#endif
#ifdef sun_solaris
XCOMM sun solaris is defined - undefining it
#undef sun_solaris
#endif
#endif

Add target to platform selection file - Platform.sel

The Platform.sel file is used by the imake scheme to select the architecture file we are building for. It requires the macro defined in the Target.sel file - vw98x in this case.

Goto the drama_source/config sub-directory and edit the file Platform.sel. Search for vw68k You should find the following 
#ifdef vw68k
#define MacroIncludeFile 
#define MacroFile vw68k.cf
#define VxWorksArchitecture
#define Mc68020Architecture
#undef vw68k
#endif

Duplicate these lines, replacing vw68k as appropiate. Also define a macro which represents the Architecture of the machine (This is used in dmakefiles to select functions dependent on this architecture. In this example, we get 
#ifdef vw98x
#define MacroIncludeFile 
#define MacroFile vw98x.cf
#define VxWorksArchitecture
#define Gismo98XArchitecture
#undef vw98x
#endif

Add target to CONFIG sub-system dmkmf script

This is the script which implements the dmkmf command. All you need to do is edit the file to add the new target to the comments at the top of the file.

Goto the drama_source/config sub-directory and edit the file dmkmf. Search for vw68k. Duplicate the line and modify as appropiate

SDS integer and floating point formats

See SDS integer and floating point formats below at this point.

Building DRAMA

You are now ready for the build. This Assume you have build DRAMA for your HOST machine and then done a cleanup of the source directory as follows 
      ./drama_make
      ./drama_make -co
You are now ready to build your new VxWorks target. Execute the drama_make command using the -t option to select the target. E.g. 
      ./drama_make -t vw98x
Now the debugging starts. DRAMA itself should build easily for any VxWorks target.

Files to be returned to AAO If you want you port to be part of future DRAMA releases, you will need to send you results back to tony.farrell@mq.edu.au  . Please send the new VxWorks target file In this example, this is the file. 
drama_source/config/vw98x.cf
Also send diffs for each of the modified files, which may include the following 
drama_make
drama_source/config/Makefile
drama_source/config/Target.sel
drama_source/config/Platform.sel
drama_source/config/dmkmf
drama_source/sds/sds.h
drama_source/sds/sds.c

Items common to both UNIX and VxWorks

SDS integer and floating point formats

The SDS sub-system must know the integer and floating point formats of the architecture you are building for. It defaults to Big Endian integers and IEEE floating point in Big Endian format. If your machine uses this architecture, then there is nothing required. Otherwise, SDS is likely to fail during the build (whilst running the sdstest and/or sdsCppTest programs) and you will have to modify SDS appropriately to support your achitecture.

Goto drama_source/sds. If your target architecture is a little endian, then edit sdsport.h. Search for SDS_BIGEND. You will find a sequence of #ifdef statements looking for the architecture of the machine the source is being compiled for. Select an appropiate macro defined by your compiler and add an appropriate entry defineing SDS_BIGEND to be 0 on your architecture.

Whlst editing sdsport.h you should also check the 64 bit integer defines.

For both little endian integers or alternative floating formats, you must now edit sds.c. You need to fill in the local_format variable appropiately for your architecture. The M_I86 version is appropiate for most little endian format machines so copy that and select it based on the macro chosen above.

Ensure you do make clean after these edits to ensure that SDS is rebuilt from scratch.

Note for AAO source code management

The ACMM archive for this is sds.

Click here for the DRAMA home page and here for the AAO home page.

 For more information, contact tony.farrell@mq.edu.au