Building Multicom UM1112
1.1 Overview
Multicom 4 is supplied as a set of source files and a set of test suites tailored to support certain ST SoCs. In addition sample board support packages (BSPs) are provided.
This chapter explains how to build the sources and test suites and then to compile and link the Multicom 4 libraries before running the test suites under the required OS. It also explains how to use the sample BSP as a template for creating new BSPs.
Multicom 4 has been developed and tested for target CPUs running both OS21 and Linux
(STLinux R2.3 and R2.4).
The release contains two source packages:
os21
- Multicom 4 release for OS21 based targets
linux
- Multicom 4 release for Linux based targets
Unpack the Multicom distribution on a suitable host machine which has the appropriate target toolsets installed. See
Section 1.1.2 on page 9
for a list of applicable toolsets. These
toolsets must be included in your PATH.
The main code is split between two top level directories;
source
test
The source directory contains all the code for the ICS and MME system libraries. The test directory contains many self tests which test each subsystem of ICS and MME.
The Multicom distribution contains a deep directory structure. An overview of these
directories is listed in
Table 1
.
Directory
Table 1. The distribution directories
Contains
docs source/include source/src/bsp source/src/ics
Product documentation.
C header files used by every processor.
BSP configuration files for each SoC
Complete source code for the ICS implementation
Complete source code for the MME implementation source/src/mme test/src/include
C header files used by test suite test/src/tests/ics
Test suite for the ICS subsystem test/src/tests/mme
Test suite for the MME subsystem lib/<
os>/<arch>
(1)
Compiled libraries for each OS and SoC bin/<
os>/<arch>
(1)
Compiled test codes for each OS and SoC
1. Created when Multicom 4 is built.
8/224 8182595 Rev 5
UM1112 Building Multicom
All makefiles supplied with Multicom use GNU make syntax. Therefore in order to rebuild the distribution, run the test suites or build any example, then a version of make compatible with GNU make must be available.
All target resident code supplied with Multicom is provided in source form to facilitate debugging and porting.
Note:
1.2
Note:
The Release Notes provide the list of products for which Multicom 4 has been tested.
Several issues have been found when using Multicom with the ST200 Micro Toolset R6.3.0.
In addition issues have been found using the GNU make tool under Windows, so GNU
make 3.81 or later is recommended.
Building the library code
The source directory must be built first, before any of the tests are built. For OS21 builds, makefiles are provided for each CPU architecture.
For example, to build Multicom 4 for ST40 and ST200, issue the following commands: cd source make -f Makefile.st40
make -f Makefile.st200
To build the kernel module for Linux, requires a command sequence of the form: export KERNELDIR=<path_to_original_linux_kernel_sources> export O=<path_to_built_linux_kernel_sources>
For example, to build the kernel module for Linux (for the MB671/STi7200) issue the following commands (adjusting the kernel paths as necessary for the desired target kernel): export KERNELDIR=/usr/src/linux-sh4-2.6.23.17_stm23_0122
export O=/lib/modules/linux-sh4-2.6.23.17_stm23_0122_mb671
cd source make ARCH=sh CROSS_COMPILE=sh4-linux-
For example, to build the kernel module for Linux (for the B2000/STiH415) issue the following commands (adjusting the kernel paths as necessary for the desired target kernel): export KERNELDIR=/usr/src/linux-arm-b2000-2.6.32.y
export O=/lib/modules/linux-arm-b2000-2.6.32.y
cd source make ARCH=arm CROSS_COMPILE=armv7-linux-
(where ARCH and CROSS_COMPILE are Linux environment variables)
On ARM based Linux builds, if the kernel does not export the symbol
set_iounmap_nonlazy
, its reference from Multicom can be disabled using the following
Make command line or environment option:
export MULTICOM_EXTRA_CFLAGS=-DDISABLE_IOUNMAP_NONLAZY
8182595 Rev 5 9/224
14
Building Multicom
To build the Linux userspace MME interface library, issue the following commands: cd source make ARCH=sh CROSS_COMPILE=sh4-linux- -f Makefile.linux
make ARCH=arm CROSS_COMPILE=armv7-linux- -f Makefile.linux
UM1112
1.3
Note:
10/224
Building the test code
Having built the source tree, the tests can now be built.
For example, to build for the MB671/STi7200 under OS21, issue the following commands: cd test make -f Makefile.st40 PLATFORM=mb671 make -f Makefile.st200 PLATFORM=mb671_audio0 make -f Makefile.st200 PLATFORM=mb671_video0 make -f Makefile.st200 PLATFORM=mb671_audio1 make -f Makefile.st200 PLATFORM=mb671_video1
The OS21 test build support is only provided for some platforms, see the Release Notes for details.
When building the companion tests, be careful to ensure that the static code load addresses and memory sizes are arranged so that the memory areas of any two CPU cores do not overlap. This is particularly important when running Linux on the ST40 host, as its default load address often clashes with that of the ST200 companions.
To this end, the test suite build allows the user to specify an alternative ST200 compiler target directory (-mtargetdir) using the ST200_TARGETDIR make environment variable.
Set this environment variable to a directory containing ST200 compiler configuration files that correctly define the static code addresses for each CPU.
To build the kernel test modules for Linux (for the MB671/STi7200) issue the following commands (adjusting the kernel paths as necessary for the desired target kernel): export KERNELDIR=/usr/src/linux-sh4-2.6.23.17_stm23_0122
export O=/lib/modules/linux-sh4-2.6.23.17_stm23_0122_mb671
cd test make ARCH=sh CROSS_COMPILE=sh4-linux-
To build the kernel test modules for Linux (for the B2000/STiH415) issue the following commands (adjusting the kernel paths as necessary for the desired target kernel): export KERNELDIR=/usr/src/linux-arm-b2000-2.6.32.y
export O=/lib/modules/linux-arm-b2000-2.6.32.y
cd test make ARCH=arm CROSS_COMPILE=armv7-linux-
(where ARCH and CROSS_COMPILE are Linux environment variables)
To build the userspace test MME executables for Linux, issue the following commands: cd test make ARCH=sh CROSS_COMPILE=sh4-linux- -f Makefile.linux
make ARCH=arm CROSS_COMPILE=armv7-linux- -f Makefile.linux
8182595 Rev 5
UM1112
1.4
Note:
Building Multicom
Compiling and linking against the Multicom 4 libraries
In order to compile a test application using the Multicom 4 libraries you need to link the application against the binary library.
For example, to compile an OS21 ST40 test program for the MB671/STi7200, issue a command similar to the following; sh4gcc -mboard=mb671 -mruntime=os21 -o test40.out test.c
-Isource/include
-Lsource/lib/os21/st40 -lmme -lics
-Lsource/lib/os21/st40/stx7200/st40 -lics_bsp
-rmain -Wl,--wrap=_write_r
For the Audio0 ST231 CPU, the command is: st200cc -mboard=mb671_audio0 -msoc=sti7200 -mcore=st231
-mruntime=os21 -o test200.out test.c
-fno-dismissible-load
-Isource/include
-Lsource/lib/os21/st231 -lmme -lics
-Lsource/lib/os21/st231/stx7200/audio0 -lics_bsp
--rmain -Wl,--wrap=_write_r
To compile a Linux userspace ST40 MME test program, issue a command similar to the following: sh4-linux-gcc -o test.out test.c
-Isource/include -Lsource/lib/linux/st40 -lmme
The ST231 -fno-dismissible-load option is only necessary if the companion code has
not correctly enabled SCU speculation for all possible memory locations that will be accessed by the ST200.
The linker --wrap=_write_r argument allows the ICS system to intercept all text output
from the target executable and log it into the CPU cyclic log buffers, for each CPU.
1.5
Note:
Building relocatable libraries for use with Multicom 4
ICS includes infrastructure that allows relocatable libraries to be dynamically loaded into the running CPUs (OS21 only). See the
Chapter 5: Overview of the inter-core system (ICS) on page 110
for more details.
In order to compile and link a compatible ELF module, use the -fpic and the -rlib options, as in the following examples. For ST40: sh4gcc -o dyn.rl -fpic -mruntime=os21
-Isource/include -rlib dyn.c
For ST200: st200cc -mcore=st231 -mruntime=os21 dyn.c -o dyn.out
-Isource/include
-fpic --rlib -fvisibility=protected
For the ST200 Micro Toolset R6.3.0, in order to overcome a bug detected only in that toolset, add the following option to the command line:
8182595 Rev 5 11/224
14
Building Multicom UM1112
-Wz,-z,max-page-size=1
Detailed information on relocatable libraries can be found in the ST40 Micro toolset user
manual (7379953) and in the ST200 Micro toolset user manual (8063762).
The ST40 and ST200 toolsets contain a tool for managing relocatable libraries. The tool is called sh4rltool in the ST40 toolset and st200rltool in the ST200 toolset. When the name of one (or more) relocatable libraries is given on the command line, the tool lists the undefined global symbols in the libraries. These symbols may need to be imported into the main program that uses the libraries. The tool also generates a linker script fragment for importing or exporting the symbols.
This feature is useful when the executable requires more than one relocatable library, each with its own (non-overlapping) API requirements.
For more information concerning the relocatable library tool, issue one of the following commands: sh4rltool --help st200rltool --help
12/224
Comprehensive debug tracing is included in the Multicom 4 code, but by default these messages are not compiled into the libraries. In order to be able to use the debug logging, the library code will need to be rebuilt using the following make command line or environment option:
# For ICS debugging
export DEBUG_CFLAGS="-DICS_DEBUG"
# For MME debugging
export DEBUG_CFLAGS="-DMME_DEBUG"
Debug libraries can be built alongside the default non-debug libraries by adding the following option to the make command line:
MULTILIB="/dbg"
This causes the debug enabled libraries to be placed in a separate dbg subdirectory in the build tree. In order to link the test executables against these libraries, add the same
MULTILIB
make command line option when compiling the tests.
As soon as the debug enabled libraries have been built, debug logging can be configured dynamically by using the ics_debug_flags() and MME_DebugFlags() API calls. The debug logging level can also be configured statically by specifying the following make command line or environment option:
# For ICS debugging
export DEBUG_CFLAGS="-DICS_DEBUG -DICS_DEBUG_FLAGS=1"
# For MME debugging
export DEBUG_CFLAGS="-DMME_DEBUG -DMME_DEBUG_FLAGS=1"
Where ICS_DEBUG_FLAGS and MME_DEBUG_FLAGS can be set to a bitmask for each subsystem for which logging is required. See
Section 5.9: Debug logging support on page 124
for further details.
8182595 Rev 5
UM1112 Building Multicom
For the Linux kernel modules the ICS and MME debugging level can be set by using the ics_debug_flags()
and MME_DebugFlags() function calls or by setting the module
parameters, see
Section C.1: Debugging assertions and logging on page 216
.
Note:
1.7
Note:
1.8
By default all ICS and MME debug log messages are logged to a cyclic buffer. Under Linux these logs can be easily accessed using the procfs filing system. For example, to dump out the current log for CPU #1, issue the command: cat /proc/ics/cpu01/log
This command dumps out all the messages logged since the last time the log was dumped.
If the logging output has exceeded the size of the cyclic buffer then only the newer messages are seen.
By linking against debug built libraries the size of the cyclic log buffer is greatly increased.
Running the tests under OS21
Running the OS21 based tests is just a matter of loading and running the primary test executable. For tests that make use of multiple CPUs the corresponding executables are loaded directly by the test harness. All test executables are compiled into the test/bin directory and should be executed from the top level test directory.
For example running a test on an MB671 may use a command such as; cd test sh4xrun -t stmc:mb671:st40,tapmux_mux=1
-e bin/os21/st40/mb671/st40/ics/channel/channel00_main.elf
The .elf files are simply stripped versions of the .out files to reduce load times.
Running the tests under Linux
To run the test modules under Linux, first the appropriate Linux kernel needs to be booted.
After booting, log into the target CPU as a root user and load the Multicom and test modules.
Load the Multicom modules using: cd source insmod src/ics/ics.ko init=0 debug_flags=0 insmod src/ics/ics_user.ko
insmod src/mme/mme.ko init=0 debug_flags=0 insmod src/mme/mme_user.ko
8182595 Rev 5 13/224
14
Building Multicom
Note:
UM1112
Individual test modules can be loaded using: cd test insmod src/tests/ics/channel/channel11_main.ko
insmod src/tests/mme/api/api10_main.ko
However, the tests which require further executables to be loaded require that all binaries are copied into /lib/firmware on the target file system. Because /lib/firmware does not support directory hierarchies, each file needs to be renamed to include the CPU name.
For example, on an MB671 we might do: cp bin/os21/st231/mb671/audio0/ics/channel/channel11_main.elf
/lib/firmware/channel11_main.audio0.elf
In this example the name of the test module channel11_main is appended with the CPU name audio0 and the extension .elf used instead of .ko.
The Linux test suite fails if these binaries are not present or have a different filename.
The Linux /lib/firmware file loading system has a maximum filename length of 32 characters including the terminating ‘\0’.
Because of the filename length limit of the Linux firmware loader, some symbolic links are required in order for the MME test suite to run correctly. For example, on an MB671, create the following links:
ln -s buffercontent10_main.audio0.elf /lib/firmware/bc10_main.audio0.elf
ln -s buffercontent10_main.audio1.elf /lib/firmware/bc10_main.audio1.elf
ln -s buffercontent10_main.video0.elf /lib/firmware/bc10_main.video0.elf
ln -s buffercontent10_main.video1.elf /lib/firmware/bc10_main.video1.elf
Currently the ICS is supplied with BSPs for a limited number of SoCs.
Appendix A: ICS board support package on page 201
describes how to create a BSP for
other SoCs.
14/224 8182595 Rev 5
