EPICS on ETRAX cris architecture
- Step-by-Step documentation

1. Basic data

Host (GSI)
<Host architecture>	x86
<Host OS>	linux (Debian sarge)
<User>	zumbruch (preliminary)
<Project Directory>	~/playground/ETRAX/EPICS
<EPICS version>	3.14.9

Target ( HADControl )
<Target architecture>	crisv10	(ETRAX 100LX MCM4+16 (little endian))
<Target OS>	linux (Axis)
<Test device>	de-etrax041
<Project Directory>	/home/hadaq/peter/playground
<User>	root
<mount point>	hadaq@lxhadesdaq:/var/diskless/etrax on /home/hadaq

Target ( e.g. TRBv2 )
<Target architecture>	crisv32	(ETRAX FS (little endian))
<Target OS>	linux (Axis)
<Test device>	?
<Project Directory>	?
<User>	?
<Mount Point>	?

2. Installation of EPICS on the host system (without cross compiler)

1. Install EPICS base:
   Following the description on Epics Installations at GSI Base install EPICS base and compile:
   • a small script myepicslogin.sh in the <Project directory>, gives a shortcut to epicslogin.sh call
2. Install Prerequisites for extensions (optionally):
   See Prerequisites for Extensions for instructions

---

2.1. Test EPICS installations & learn

Following the example given in chapter 2 section 2.2 of the EPICS IOC Application Developer's Guide:

1. Creation of a new IOC Application named <My Example Application>:
   
   $> mkdir <top>
$> cd <top>
$> $EPICS_BASE/bin/${EPICS_HOST_ARCH}/makeBaseApp.pl -t example <My Example Application>
$> $EPICS_BASE/bin/${EPICS_HOST_ARCH}/makeBaseApp.pl -i -t example <My Example Application>
$> make
$> cd iocBoot/ioc<My Example Application>
2. Starting the IOC:
   (<Target> (e.g.: linux-x86, or ${EPICS_HOST_ARCH}), <My Example Application>, <Top>, <Epics Base Directory> and <User> have been replaced in the output )
   
   $> ../../bin/<Target>/<My Example Application> st.cmd
   

       #!../../bin/<target>/<My Example Application>
       ## You may have to change <My Example Application> to something else
       ## everywhere it appears in this file
       < envPaths
       epicsEnvSet(ARCH,"<Target>")
       epicsEnvSet(IOC,"ioc<My Example Application>")
       epicsEnvSet(TOP,"<top>")
       epicsEnvSet(EPICS_BASE,"<Epics Base Directory>")
       cd <top>
       ## Register all support components
       dbLoadDatabase("dbd/<My Example Application>.dbd")
       <My Example Application>_registerRecordDeviceDriver(pdbbase)
       ## Load record instances
       dbLoadTemplate "db/userHost.substitutions"
       dbLoadRecords("db/dbSubExample.db","user=<user>Host")
       ## Set this to see messages from mySub
       #var mySubDebug 1
       cd <top>/iocBoot/ioc<My Example Application>
       iocInit()
       Starting iocInit
       ############################################################################
       ## EPICS R3.14.9 $R3-14-9$ $2007/02/05 16:31:45$
       ## EPICS Base built Aug  6 2007
       ############################################################################
       iocInit: All initialization complete
       ## Start any sequence programs
       #seq sncExample,"user=<user>Host"
       epics>
       

3. Listing the available PVs:
   
   epics> dbl
   

      <user>Host:aiExample
      <user>Host:aiExample1
      ...
      <user>Host:xxxExample
      

4. Any EPICS client should be able to see those PVs, e.g.:
   
   $> camonitor <User>Host:aiExample1
   

      <user>Host:aiExample1        2007-08-09 10:42:00.037941 4 LOW MINOR
      <user>Host:aiExample1        2007-08-09 10:42:01.039624 5
      <user>Host:aiExample1        2007-08-09 10:42:02.041629 6 HIGH MINOR
      

---

3. Install ETRAX cross-compiler environment (SDK)

Overview: Installation of SDK

3.1. Cross compiler installation

1. compiler download from axis
2. Compiler Installation guide

---

3.2. Debugger

1. debugger download from axis
2. Debugger Installation
3. Usage

---

3.3. Software Distribution

1. software distribution download from axis
2. Software Distribution Install HowTo

or
Have a look at Installation of Axis Developer Board Devixe Server SDK

If you intend to create the include files and libraries for both architectures (cris_v10 (LS 100) and cris_v32 (FS)) you have to do the process twice:

• either by doing this in the same <SDK Base Path> by accepting that not used parts are overwritten
• or by doing it in seperate paths which would imply more settings in the later cross compile.

---

3.4. Test Cross Compiler installations & learn

---

3.4.1. Introduction Compiling for cris

see:

• How to compile for cris - "Hello world"
• How to compile for cris - Application (most unlikely to be used for EPICS)

---

4. Create IOC cross-compiled for target architectures:

After having read chapter 4 of the EPICS: IOC Applicaton Developer's Guide and several tech-talk topics and more over having deeply digged into the business of Makefiles/ CONFIG files / RULES files (sorry for this long sentence) just follow those comprehensive recipes.

The strategy now is to first test this for already supported operating system - target architecture sets (<Target>) to learn, e.g.:

• linux-686
• linux-586
• linux-arm

It is assumed that we always stay on the same and only host system (<Host>): linux-x86
otherwise it's just a little bit different.

4.1. Supported operating system - target architecture sets

This seems to be the first (and only) step for an already supported target system:

4.1.1. Modify the host specific configuration file(s)

Define/Modify CROSS_COMPILER_TARGET_ARCHS in the file $EPICS_BASE/${CONFIG}/os/CONFIG_SITE.<host>.Common to hold <Target>:

   # CONFIG_SITE.linux-x86.Common
   #
   # CONFIG_SITE.linux-x86.Common,v 1.7.2.4 2005/02/01 20:51:44 norume Exp
   # This file is maintained by the build community.
   #
   # Site override definitions for linux-x86 host builds
   #-------------------------------------------------------

   CROSS_COMPILER_TARGET_ARCHS =  <Target 1> <Target 2>
   

1. e. in this example (linux-arm is taken out for a moment, since the cross-compilers are not defined):
CROSS_COMPILER_TARGET_ARCHS = linux-686 linux-586

Afterwards compile:

4.1.2. Compile base

$> cd $EPICS_BASE
$> make
You don't have to clean before-hand.

4.1.3. Compile applications

$> cd <Top>
$> make
You don't have to clean before-hand.

Then test:

4.1.4. Run the application

Run as shown in previous section Test EPICS installations & learn with <Target> correspondingly set.

---

4.2. New operating system - target architecture sets

The new operating system - target architecture sets shall be:

• linux-cris_v10 (ETRAX 100LX)
• linux-cris_v32 (ETRAX FX)

Meanwhile I managed to finish the work, so I see it from the past what had to be modified, created and to be done.

The global understanding or the basic problem in implementing a new architecture is to know what is already done and does not have to be written once again. Almost every configuration file contains include commands to implement features already defined elsewhere and switches (if statements) to decide on what to implement and what not. Those two links show this multiple nesting hierarchy for those case:

• Configuration Hierarchy for EPICS cross compiled for crisv10
• Configuration Hierarchy for EPICS cross compiled for crisv32

4.2.1. Files which had to created/modified

File	Description	File location relative to <Epics Base directory>	NEW / Modified	configuration hierarchy
README.cris	README for EPICS build 3.14.9	${CONFIG}/os/CONFIG.Common.linux-cris/README	NEW	--
CONFIG.linux-x86.linux-cris_v10	configuration file	${CONFIG}/os/CONFIG.linux-x86.linux-cris_v10	NEW	EpicsV3149CONFIGLinuxX86LinuxCrisV10
CONFIG.linux-x86.linux-cris_v32	configuration file	${CONFIG}/os/CONFIG.linux-x86.linux-cris_v32	NEW	EpicsV3149CONFIGLinuxX86LinuxCrisV32
CONFIG_SITE.linux-x86.Common	site configuration file	${CONFIG}/os/CONFIG_SITE.linux-x86.Common	M	--
CONFIG.Common.linux-cris	configuration file	${CONFIG}/os/CONFIG.Common.linux-cris	NEW	EpicsV3149CONFIGCommonLinuxCris
CONFIG_SITE.Common.linux-cris	site configuration file	${CONFIG}/os/CONFIG_SITE.Common.linux-cris	NEW	EpicsV3149CONFIGSITECommonLinuxCris
CONFIG.linux-x86.linux-cris	configuration file	${CONFIG}/os/CONFIG.linux-x86.linux-cris	NEW	EpicsV3149CONFIGLinuxX86LinuxCris
CONFIG_SITE.linux-x86.linux-cris	site configuration file	${CONFIG}/os/CONFIG_SITE.linux-x86.linux-cris	NEW	EpicsV3149CONFIGSITELinuxX86LinuxCris
osdWireFormat.h	optional settings for Endianness	src/libCom/osi/os/default/osdWireFormat.h	M	--
cris.patch.3.14.9	patch file to 3.14.9 version		NEW	--

The nested includes thus look this way

${CONFIG}/os/CONFIG.linux-x86.linux-cris_v10/32

${CONFIG}/os/CONFIG.Common.linux-cris

( ${CONFIG}/os/CONFIG.Common.linuxCommon, already there, no changes needed)

${CONFIG}/os/CONFIG_SITE.Common.linux-cris

${CONFIG}/os/CONFIG.linux-x86.linux-cris

${CONFIG}/os/CONFIG_SITE.linux-x86.linux-cris

Now in detail the following steps have been persued ... For most of the newly created files the linux-arm files for used as a template.

4.2.2. Host only specific configuration file(s)

4.2.2.1. ${CONFIG}/os/CONFIG_SITE.<Host>.Common

• Modify ${CONFIG}/os/CONFIG_SITE.<Host>.Common
  • add target architecture to be cross-compiled:
    • in general:
      CROSS_COMPILER_TARGET_ARCHS += <Target>
    • here: ${CONFIG}/os/CONFIG_SITE.linux-x86.Common
      CROSS_COMPILER_TARGET_ARCHS += linux-cris_v10
CROSS_COMPILER_TARGET_ARCHS += linux-cris_v32
• CONFIG_SITE.linux-x86.Common

---

4.2.3. Target only specific configuration files

4.2.3.1. ${CONFIG}/os/CONFIG.Common.linux-cris

Since many of the settings of the two targets are the same it made sense to create a Common configuration file for the “target” class of linux-cris include by the “real” target files. Thus most settings are done within here. Since this file includes itself $(CONFIG)/os/CONFIG.Common.linuxCommon some settings might be overwritten.
• Create ${CONFIG}/os/CONFIG.Common.linux-cris
The following settings are implemented:

4.2.3.1.1. target architecture class

%begin makefile% ARCH_CLASS = cris %end%
The following parts are only defined if the BUILD_CLASS is CROSS:
%begin makefile% ifeq ($(BUILD_CLASS),CROSS) %end%

4.2.3.1.2. gnu target

%begin makefile% GNU_TARGET = cris-axis-linux-gnu
# prefix of compiler tools CMPLR_SUFFIX = CMPLR_PREFIX = $(addsuffix -,$(GNU_TARGET)) %end%

4.2.3.1.3. Axis general directories

Default setting is UNDEFINED_ENV__AXIS_TOP_DIR since it is expected to be set from outside via the environment variable AXIS_TOP_DIR. Usually AXIS_TOP_DIR is defined via the init_env script of the SDK provided by Axis. If not, the compilation will not crash but will not produce a code. The makefile output should contain lines with UNDEFINED_ENV__AXIS_TOP_DIR.
If not otherwise defined the AXIS_SDK_DIR variable is identical to AXIS_TOP_DIR.
%begin makefile% # CROSS_TOP_DIR # usually AXIS_TOP_DIR is defined via # the init_env script of the SDK provided by Axis # ## AXIS_TOP_DIR defined? Make missing mandatory variable visible AXIS_TOP_DIR?=UNDEFINED_ENV__AXIS_TOP_DIR AXIS_SDK_DIR?=$(AXIS_TOP_DIR) %end%

4.2.3.1.4. cross compiler include directories

%begin makefile% # CROSS_INCLUDES AXIS_SDK_TARGET_INCLUDE_DIR = $(AXIS_SDK_DIR)/target/$(GNU_TARGET)/include AXIS_SDK_TARGET_INCLUDE_DIR +=$(AXIS_SDK_DIR)/target/$(GNU_TARGET)/usr/include
CROSS_INCLUDES = $(addprefix -isystem ,$(AXIS_SDK_TARGET_INCLUDE_DIR)) %end%

4.2.3.1.5. cross compiler linker flags

%begin makefile% # CROSS_LDFLAGS AXIS_SDK_TARGET_LIB_DIR = $(AXIS_SDK_DIR)/target/$(GNU_TARGET)/lib AXIS_SDK_TARGET_LIB_DIR += $(AXIS_SDK_DIR)/target/$(GNU_TARGET)/usr/lib
CROSS_LDFLAGS = $(addprefix -L,$(AXIS_SDK_TARGET_LIB_DIR)) %end%

4.2.3.1.6. include other makefiles

• Site specific common linux-cris settings
%begin makefile% -include $(CONFIG)/os/CONFIG_SITE.Common.linux-cris %end%
• Host specific linux-cris settings
%begin makefile% ifeq ($(EPICS_HOST_ARCH), linux-x86) -include $(CONFIG)/os/CONFIG.linux-x86.linux-cris -include $(CONFIG)/os/CONFIG_SITE.linux-x86.linux-cris endif %end%
%begin makefile% endif %end%
The following settings are again without any condition on BUILD_CLASS:

4.2.3.1.7. No shared libraries and static build

%begin makefile% SHARED_LIBRARIES=NO STATIC_BUILD=YES %end%

4.2.3.1.8. Architecture and operating system dependent flags

%begin makefile% ARCH_DEP_CFLAGS += -mno-mul-bug-workaround OP_SYS_CFLAGS += -mlinux ARCH_DEP_CPPFLAGS += -D_cris_ -mlinux %end%

4.2.3.1.9. optional debugging

%begin makefile% #uncomment CRIS_COMPILER_DEBUG for debugging cris-compiled code #CRIS_COMPILER_DEBUG %end%
Finally resulting in
• CONFIG.Common.linux-cris

---

4.2.3.2. ${CONFIG}/os/CONFIG_SITE.Common.linux-cris

• Create ${CONFIG}/os/CONFIG_SITE.Common.linux-cris

4.2.3.2.1. Readline library

Since the Readline library is not installed, comment it out:
%begin makefile%
# If readline is not installed comment the following line # to omit command-line editing and history support
#COMMANDLINE_LIBRARY = READLINE %end%

4.2.3.2.2. Debugging information added to operating system's CFLAGS

%begin makefile% OP_SYS_CFLAGS += -g %end%
Finally resulting in
• CONFIG_SITE.Common.linux-cris

---

4.2.4. Host and Target specific configuration files

4.2.4.1. ${CONFIG}/os/CONFIG.linux-x86.linux-cris

• Create ${CONFIG}/os/CONFIG.linux-x86.linux-cris

4.2.4.1.1. Gnu base directory of cross compiler

%begin makefile% GNU_DIR = $(CRIS_CROSS_COMPILER) %end%

4.2.4.1.2. Static build settings

To be really static while linking not only the gcc linker option -Wl,-Bstatic (Do not link against shared libraries) has to be set for the (default) static build, but also explicitly extended for the libgcc to -static-libgcc due to a debian-gcc bug
%begin makefile% #STATIC_... STATIC_LDFLAGS_YES= -Wl,-Bstatic
## debian-gcc Bug#438641 GNU_LDLIBS_YES = STATIC_LDFLAGS_YES += -static-libgcc %end%

4.2.4.1.3. Strip symbols

If not in debug mode than strip all symbols from the generated code by adding --strip-all (Omit all symbol information from the output file) to the linker flags, typically tremendously reducing the file size.
%begin makefile% # if not in debug mode strip all symbols ifndef CRIS_COMPILER_DEBUG STATIC_LDFLAGS_YES += -Wl,--strip-all endif %end%

4.2.4.1.4. Non-Gnu libraries

If Gnu isn't used add gnu library to linker option -lgcc
%begin makefile% ifeq ($(GNU),YES) STATIC_LDFLAGS_NO = -lgcc else STATIC_LDFLAGS_NO = endif %end%

4.2.4.1.5. (Non)Static libraries

%begin makefile% STATIC_LDLIBS_YES= STATIC_LDLIBS_NO= %end%

4.2.4.1.6. Shared Library settings

In case of the non-default case of shared libraries add the linker flag -shared -fPIC.
%begin makefile% SHRLIB_LDFLAGS += -shared -fPIC LOADABLE_SHRLIB_LDFLAGS = -shared -fPIC %end%

4.2.4.1.7. Optimization down to -Os

• See this Tech-Talk thread especially this reply or this Core-Talk thread.
• See GCC Manual for the optimization options.
%begin makefile% OPT_CXXFLAGS_YES = -Os %end%

4.2.4.1.8. echo 'yes' if in static build

Maybe a relict from testing. TODO: check!
%begin makefile% ifeq ($(STATIC_BUILD), YES) $(shell echo yes) endif %end%

Finally resulting in
• CONFIG.linux-x86.linux-cris

---

4.2.4.2. ${CONFIG}/os/CONFIG_SITE.linux-x86.linux-cris

Site specific definitions for linux-x86 host - linux-cris target builds
• Create ${CONFIG}/os/CONFIG_SITE.linux-x86.linux-cris

4.2.4.2.1. CRIS cross compiler's base directory

Default setting is UNDEFINED_ENV__CRIS_CROSS_COMPILER since it is expected to be set from outside via the environment variable CRIS_CROSS_COMPILER. If not the compilation will crash when trying to use UNDEFINED_ENV__CRIS_CROSS_COMPILER as compiler, which shouldn't be existing.
%begin makefile% # define site specific location of cris cross compiler's gnu directory # but without bin sub directory, this will be added automatically.
CRIS_CROSS_COMPILER ?= UNDEFINED_ENV__CRIS_CROSS_COMPILER %end%
Finally resulting in
• CONFIG_SITE.linux-x86.linux-cris

4.2.4.3. ${CONFIG}/os/CONFIG.linux-x86.linux-cris_v10

• Create ${CONFIG}/os/CONFIG.linux-x86.linux-cris_v10

4.2.4.3.1. Redefiniton of GNU_TARGET

Although GNU_TARGET has already been defined in ${CONFIG}/os/CONFIG.Common.linux-cris it is overwritten here in case of linux-cris_v10 to no purpose but to keep symmetry to linux-cris_v32.
%begin makefile% GNU_TARGET = cris-axis-linux-gnu %end%

4.2.4.3.2. Architecture dependent CFLAGS

The compiler option -march=v10 defines the architecture type. See further options in the CRIS section GCC Manual.
%begin makefile% ARCH_DEP_CFLAGS += -march=v10 %end%

4.2.4.3.3. Optional different AXIS SDK directory

%begin makefile% # if you are using different places for cris_v10 cris_v32 # you have to define for each architecture # AXIS_SDK_DIR= %end%

Finally resulting in
• CONFIG.linux-x86.linux-cris_v10

4.2.4.4. ${CONFIG}/os/CONFIG.linux-x86.linux-cris_v32

• Create ${CONFIG}/os/CONFIG.linux-x86.linux-cris_v32

4.2.4.4.1. Redefiniton of GNU_TARGET

Although GNU_TARGET has already been defined in ${CONFIG}/os/CONFIG.Common.linux-cris it is overwritten here to have the right value.
%begin makefile% GNU_TARGET = crisv32-axis-linux-gnu %end%

4.2.4.4.2. Architecture dependent CFLAGS

The compiler option -march=v32 defines the architecture type. See further options in the CRIS section GCC Manual.
%begin makefile% ARCH_DEP_CFLAGS += -march=v32 %end%

4.2.4.4.3. Optional different AXIS SDK directory

%begin makefile% # if you are using different places for cris_v10 cris_v32 # you have to define for each architecture # AXIS_SDK_DIR= %end%

Finally resulting in
• CONFIG.linux-x86.linux-cris_v32

---

---

4.2.5. Other files

4.2.5.1. optionally: src/libCom/osi/os/default/osdWireFormat.h

• Modify src/libCom/osi/os/default/osdWireFormat.h

4.2.5.1.1. Endianness

While developing the port it was unclear whether CRIS supports little endian or big endian formats. So for being sure src/libCom/osi/os/default/osdWireFormat.h was extended by a switch. Since now it is known that cris is little endian, which is the default, this could be neglected or used as example where to test endianness.
Future releases of EPICS beyond 3.14.9 will define endianness elsewhere.
%begin c++% #elif defined (cris) # define EPICS_LITTLE_ENDIAN %end%

---

---

4.2.6. Compile base

$> cd $EPICS_BASE
$> make
You don't have to clean before-hand.

---

4.2.7. Compile applications

$> cd <Top>
$> make
You don't have to clean before-hand.

---

4.2.8. Copy to target machine

Minimum you only have to copy to the target systems file system:
• the binary to be found in <TOP>/bin/linux-cris_v10, <TOP>/bin/linux-cris_v32 respectively.
• the startup script typically st.cmd to be found in <TOP>/iocBoot/ioc<Application>
if needed
• other parts from the <TOP> directory db/ dbd/ ...

---

5. Download

• Patch file to EPICS base 3.14.9:
  • cris.patch.3.14.9 includes all files
  • apply with patch
• README file:
  • README.cris
• Tar ball of all files
  • cris.tar.bz2

---

6. Tips, Tricks and Follow-Ups

• tech-talk: Cross compiling EPICS for cris v10: https://epics-controls.org/tech-talk/2010/msg01580.php
  -- PeterZumbruch - 01 Oct 2010

---

-- PeterZumbruch - 01 Oct 2010