README.patmos

                             LLVM FOR PATMOS


This is LLVM for Patmos, the time predictable processor of the T-CREST project.

--------------------------------------------------------------------------------
1. Requirements

 - Clang for Patmos
   https://github.com/t-crest/patmos-clang
    
    Required to compile .c files to bitcode files (with the proper data layout 
    for Patmos).

    You need to checkout patmos-clang as tools/clang subdirectory of this 
    repository (symlinks will not work!) to build clang as part of the Patmos 
    toolchain.

    You can (currently) omit this step, if you only need to compile .ll or .bc 
    files.

 - cmake 2.8 or higher (optional for llvm and clang, required for compiler-rt)

 - graphviz (optional, for debugging)


For Debian or Ubuntu, you may need to install the following packages:

    cmake make
    g++ 
    texinfo
    flex bison
    libelf-dev
    graphviz
    python
    zlib1g-dev

To build the simulator, you also need the following packages (version >= 1.46):

    libboost-dev libboost-program-options-dev

For the WCET analysis integration (optional), you also need

    ruby1.9.1
    ruby1.9.1-dev

--------------------------------------------------------------------------------
2. Configure and build

The recommended way to build the compiler, the Patmos libraries and the rest
of the toolchain is to use the build script provided in the patmos-misc
repository.
    
    git clone http://github.com/t-crest/patmos-misc
    cd patmos-misc
    cp build.cfg.dist build.cfg
    # edit build.cfg, set ROOT_DIR and INSTALL_DIR
    ./build.sh


For manual builds, LLVM can be compiled either with configure or with CMake. 
For an automake based build, use the follwing commands to build for Patmos and 
enable building of the gold plugin:

    mkdir build
    cd build
    ../configure --disable-optimized --enable-assertions \
    --enable-targets=host,patmos \
    --with-binutils-include=`readlink -f ../../patmos-gold/include/` \
    --prefix=$INSTALL_DIR

	Emad: Can't make above work.
	
With cmake:
    
    mkdir build
    cd build
    cmake .. -DCMAKE_CXX_STANDARD=14 -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=$INSTALL_DIR -DLLVM_BINUTILS_INCDIR=`readlink -f $GOLD_INCLUDE_DIR` -DLLVM_TARGETS_TO_BUILD=Patmos -DLLVM_ENABLE_ASSERTIONS=true -DLLVM_DEFAULT_TARGET_TRIPLE=patmos-unknown-unknown-elf -DCLANG_ENABLE_ARCMT=false -DCLANG_ENABLE_STATIC_ANALYZER=false -DCLANG_ENABLE_TESTS=false -DCLANG_ENABLE_DOCS=false -DCLANG_BUILD_EXAMPLES=false
		 

$INSTALL_DIR: the local installation folder. typicalling '../local'
$GOLD_INCLUDE_DIR: the include directory of the patmos-gold repo. typically '../gold/include'

In both cases, LLVM is built using make

    make -j

To install libraries for LTO support:
    - Go to the directory where your patmos gold, ar and nm binaries with 
      plugin support are located
    - mkdir -p ../bin && mkdir -p ../lib/bfd-plugins
    - Copy or link patmos-llvm-obj/Debug+Asserts/lib/{LLVMgold.so,libLTO.so} to 
      the lib/bfd-plugins directory
    - Specify -plugin /path/to/LLVMgold.so when you use gold

--------------------------------------------------------------------------------
3. Run Tests

To run test that are specific to Patmos, navigate to the folder `llvm/build` and run:
```make -j UnitTests llc && ./bin/llvm-lit ../test --filter=Patmos -v```

This command will first build `llc` and unit tests, and if successfull then run all Patmos tests.

To only run unit tests use:
```make -j UnitTests && ./bin/llvm-lit ../test --filter="Unit.*Patmos" -v```

This will run quicker, as it doesn't build the whole LLVM. But it also does
not run all tests.

--------------------------------------------------------------------------------
4. Use it

To build an application, the following command can be used to compile and link
the application:

    patmos-clang -o hello main.c hello.c

The application can be simulated using

    pasim hello


The default target triple is 'patmos-unknown-unknown-elf', if the clang compiler
is called 'patmos-clang'. You can set the target triple explicitly using -target:

    patmos-clang -target patmos-unknown-unknown-elf -o hello main.c hello.c

The following target triples are supported by the patmos tool-chain:

    patmos-unknown-unknown-elf	    No operating system, run ELF on bare metal.
    patmos-unknown-rtems	    Use RTEMS, defines __rtems__.


Options for compiling and linking using the clang driver:

    patmos-clang -c <inputs>
	Input:  .c C source file
	Output: .o or .bc bitcode files
	Actions: compile each input file to a bitcode file
    
    patmos-clang -S <inputs>
	Input:  .c C source file
	Output: .s or .ll human readable bitcode files
	Actions: compile each input file to a human readable bitcode file
    
    patmos-clang -fpatmos-emit-obj -c <inputs>
	Input:  .c C source file
	Output: .o Patmos relocatable ELF
	Actions: compile each input file to a Patmos relocatable ELF file

    patmos-clang -fpatmos-emit-obj -S <inputs>
	Input:  .c C source file
	Output: .s Patmos assembly file
	Actions: compile each input file to a Patmos assembly file

    patmos-clang -emit-llvm <inputs>
	Input:  .c C source file, .bc bitcode object file, .a bitcode files archive
	Output: bitcode file
	Actions: compile to bitcode, link all input files, link with standard 
	         libraries and start code

    patmos-clang -fpatmos-emit-obj <inputs>
	Input:  .c C source file, .bc bitcode object file, .a bitcode files archive
	Output: .o Patmos relocatable ELF
	Actions: compile to bitcode, link all input files, link with standard 
		 libraries and start code, compile to relocatable ELF

    patmos-clang -fpatmos-emit-asm <inputs>
	Input:  .c C source file, .bc bitcode object file, .a bitcode files archive
	Output: .o Patmos assembly file
	Actions: compile to bitcode, link all input files, link with standard 
 	 	 libraries and start code, compile to Patmos assembly

    patmos-clang -o <output> <inputs>
	Input:  .c C source file, .bc bitcode object file, .a bitcode files archive
	Output: Patmos executable ELF
	Actions: compile to bitcode, link with standard libraries and start code,
		 compile to relocatable ELF, create Patmos executable ELF

    patmos-clang -flto -o <output> <inputs>
	Input:  .c C source file, .bc bitcode object file, .a bitcode files archive,
	        Patmos ELF files
	Output: Patmos executable ELF
	Actions: compile to bitcode, link all input files, compile to relocatable ELF, 
	         link libraries with patmos-gold, create Patmos executable ELF
        Note:    Linking applications with LTO is currently not fully supported.

The following options control the linker default behaviour:

    -mfloat-abi=hard	         Do not use software floating point libraries when linking
    -nostdlib		         Do not use standard libraries such as libc when linking
    -nolibc		         Do not use libc when linking
    -noruntimelibs	         Do not use platform system libraries when linking
    -nodefaultlibs	         Do not use standard libs or system libraries when linking
    -nostartfiles	         Do not use the crt0 startup file when linking
    -nolibsyms		         Do not use symbol definition files for runtime libraries when
			         linking. Those files prevent the linker from removing any
			         functions for which calls might be generated by the compiler
			         backend, such as software division or memcpy
    -fpatmos-link-object         Link as object, i.e., do not link in any libraries or start code.
                                 Shortcut for -nostartfiles -nodefaultlibs. Emits bitcode if possible.
    -flto                        Link all libraries with gold instead of with llvm-link
    -fpatmos-disable-internalize Disable internalize pass after bitcode linking
    -fpatmos-no-std-link-opts    Disable default link time optimization passes (internalize, ..) after 
                                 bitcode linking. Custom opt passes/arguments can be added with -Xopt.
    -fpatmos-skip-opt            Skip executing opt after bitcode linking.

Bitcode file libraries can be created using ar. However, in order to be able to
link libraries with -flto using gold, the libraries must be created with 
patmos-ar and the LLVMgold.so plugin must be properly installed. Either 
patmos-nm or patmos-llvm-nm can be used to inspect the archives in any case.


The following options pass arguments through the driver to the invoked commands:

    -Xclang <arg>	Pass <arg> to clang -cc1 (can be used multiple times)
    -Xlinker <arg>	Pass <arg> to llvm-ld (can be used multiple times)
    -Xopt <arg>	        Pass <arg> to opt after bitcode linking
    -Wl,<arg>[,<arg>..] Comma-separated list of arguments to pass to llvm-ld
    -Xllc <arg>		Pass <arg> to llc (can be used multiple times)
    -Xassembler <arg>   Pass <arg> to llvm-mc (can be used multiple times)
    -Wa,<arg>[,<arg>..] Comma-separated list of arguments to pass to llvm-mc
    -Xgold <arg>        Pass <arg> to patmos-ld (can be used multiple times)

    -m<arg>		Passed to llc
    -T<arg>		Passed to patmos-ld
    -e <entry>		Passed to patmos-ld


Have fun!


--------------------------------------------------------------------------------
Appendix - Additional Information
--------------------------------------------------------------------------------

--------------------------------------------------------------------------------
A) Patmos Backend Documentation

For more information about the Patmos backend (ELF file format, assembler 
syntax, ...) please refer to the documentation provided in the patmos-misc 
repository.

  https://github.com/t-crest/patmos-misc


--------------------------------------------------------------------------------
B) Toolchain

 - pasim - Patmos Simulator

 - compiler-rt, and NewLib for Patmos
   https://github.com/t-crest/patmos-compiler-rt
   https://github.com/t-crest/patmos-newlib

  patmos-newlib and patmos-compiler-rt into separate directories, for libc and 
  runtime libraries

 - patmos-gold for the linker
   https://github.com/t-crest/patmos-gold
   
   clang looks for patmos-gold in the PATH and the clang 
  install directory. To specify the linker executable to use for clang, set the
  PATMOS_GOLD environment variable to the linker filename.


See the README files in the various repositories for information on how to build 
them.


--------------------------------------------------------------------------------
C) Eclipse Setup

To setup Eclipse with C++ and GDB support for developing LLVM, follow those steps:

- Install Eclipse version 3.7 (3.8 has crappy UI), CDT version 
  (CDT plugin >= 8.x)
    - Edit your eclipse.ini to get more heap, ~600-700Mb (-Xmx=700m)
- Install gdb >= 7.0
- Create an Eclipse project using cmake:
    - Use cmake-gui to setup cmake in a separate directory, run Configure
	mkdir ../patmos-llvm-eclipse
	cd ../patmos-llvm-eclipse
	cmake-gui ../patmos-llvm
    - Select Eclipse as generator type
    - Do not use clang and clang++ as compilers, use defaults (g++)
      Otherwise gdb python scripts do not work properly for libstdc++ !
    - Make sure to:
		* Set CMAKE_BUILD_TYPE to Debug
		* Enable assertions
		* Change LLVM_DEFAULT_TARGET_TRIPLE to 'patmos-unknown-unknown-elf'
		* Change LLVM_TARGETS_TO_BUILD to 'Patmos'
- Setup Eclipse project
    - Use File->Import->General->Import Existing Project. Do not check Copy Sources.
    - Setup Resource->Resource Filters in Project settings on project root, 
	- Exclude */clang/test and */clang/INPUTS project relative paths (recursive)
	- Do not use 'Location', causes nullpointer exception on file save
      This avoids bombing the indexer with stresstest files.
      Make sure Indexer does not run before you create the filters!
    - Delete the [Targets] and [Subprojects] directories (or whatever they are called)
      Otherwise Eclipse will open your files multiple times and you will loose some of 
      your changes if you are not careful!
    - Setup project settings:
        - Setup coding style to new derivative from GNU, edit line-breaks settings
        - Setup Project Include-path settings: add following paths and defines:
            - /usr/include
            - /usr/include/c++/4.6
            - /usr/include/c++/4.6/x86_64-linux-gnu
            - /usr/include/x86_64-linux-gnu
            - GET_REGINFO_MC_DESC, GET_REGINFO_HEADER, GET_REGINFO_TARGET_DESC, 
	      GET_ASSEMBLER_HEADER, GET_MATCHER_IMPLEMENTATION
        - Setup indexer to consume up to 100-200Mb
        - Setup Tabwidth to 8 in Text Editor, C++ Code Style, General Editor!
        - Setup Texteditor Font to Deja Sans Mono or any other font that has 
	  same character width for normal and bold text!
        - Setup dictionary for 'C++ Spell Checker' 
	  General spell checker dictionary does not remember words.
    - Setup GDB (Preferences -> C++ -> Debug)
	- in GDB, set GDB command file to ~/.gdbinit (not loaded automatically 
	  with GDB DSF launcher!), uncheck stop at startup, enable pretty printers
	- in Source Lookup Path, remove defaults, add:
	    - Absolute Paths as first entry (otherwise Eclipse does not find files)
	    - File System Directory entries for both patmos-llvm and build dir 
	      (patmos-llvm-eclipse) as absolute paths, check Lookup Subdirectories
	      (relative paths do not work for GDB DSF, only for the Standard Launcher)
	    Make sure you removed all Project Path entries (breaks GDB DSF breakpoints)
- Setup Debug Configurations (Run -> Debug configurations -> New C++ Application)
    - Select 'GDB (DSF)' as debugging interface (either per project or change workspace 
      defaults; Standard Launcher does not support pretty printing)
    - In 'Arguments', set working dir to your test directory (for relative paths in arguments)
    - In 'Debugger', disable stop on main, set gdbinit file to ~/.gdbinit if necessary
    - In 'Source', make sure you have the same settings as described above 
      (Absolute File Path, then absolute paths to llvm checkout and build dir, include subdirs)
      Remove any Project Relative Path entries
    
    - Note: GDB DSF launcher is a bit whimpy when GDB throws errors e.g. in python printers. 
      You may need to restart Eclipse if your Variable view stays empty during debugging.

    - Note: GDB DSF launcher does not load ~/.gdbinit by default, does not work with relative
      source paths. Standard Launcher always loads ~/.gdbinit *in addition* to the given
      GDB command file (do *not* specify ~/.gdbinit), works with project relative paths, may 
      work better for debugging shared libraries (?), maybe more stable (?), but does not 
      support pretty printing.
- Setup GDB pretty printing (change ~/gdb_printers path to your liking)
    - Follow http://sourceware.org/gdb/wiki/STLSupport to setup pretty printer for STL
      mkdir ~/gdb_printers
      cd ~/gdb_printers
      svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python
    - Create a ~/.gdbinit file with the following content (or use any other name and 
      specify as command file when launching GDB)

    ---- ~/.gdbinit ----
    python
    import sys
    sys.path.insert(0, '/path/to/patmos-llvm/utils/gdb/python')
    sys.path.insert(1, '/home/user/gdb_printers/python')
    from libstdcxx.v6.printers import register_libstdcxx_printers
    register_libstdcxx_printers (None)
    from llvm.printers import register_llvm_printers
    register_llvm_printers (None)
    end

    set print pretty on
    set print array on
    set print object on
    set print static-members on
    set print vtbl on
    set print demangle on
    set demangle-style gnu-v3
    set print sevenbit-strings off
    ---- END ----

--------------------------------------------------------------------------------

(D) Known customization of LLVM code

* lib/MC/MCParser/AsmParser.cpp

In 'parseStatement()', added '{' and '(' as an allowed identifiers.
The first is already allowed in LLVM version, and is therefore forward compatible.
The second is not.