m4_init/3rd/libopencm3/ld/README

------------------------------------------------------------------------------
README
------------------------------------------------------------------------------

LIBOPENCM3 LINKER SCRIPT GENERATOR
----------------------------------

This folder contains files needed for the automatic linker script generation
mechanism developed for libopencm3 library.

File contents
-------------

* {ROOT}/ld/tests/* 		- Prepared tests for the testing of the script
* {ROOT}/ld/devices.data	- Device database file
* {ROOT}/ld/linker.ld.S		- Linker script template
* {ROOT}/scripts/genlink.py	- Device database file search script 
* {ROOT}/scripts/genlinktest.sh	- Device database file search test script

Principle of operation
----------------------

The user specifies in the project Makefile the device part name the project is
using, in the variable DEVICE. Note that full device part name must be
specified, because the device specific features is usually dependent on the
last characters of device name string. Note that the device name string search
is case insensitive.

DEVICE=stm32f407vgt6

Device database contains definitions of common sections and its origins for
the linker preprocessor. Every definition is interpreted in the linker script
template as a macro, and it can be used for conditional insertion of the device
dependent stuff.

The search in the device database is pattern-based, and using python script
genlink.py. The python script traverses the file as a tree, joining the options
for the preprocessor together by single space. The python script adds -D to
each parameter for you.

Testing
-------

The testing of feature is done by executing in the root of libopencm3 library.

make genlinktests

The test cases are defined in subdirectory {ROOT}/ld/tests/. Each test contains
two files, the database file *.data and the expected result *.result file. If
the particular test fails, the file *.out containing output of the script is
not deleted to help resolving problem with the script.

The search pattern for the test is the base filename of particular test.

The testing stops after all test cases are valid, or at first error found.

Example of use
--------------

* Check the documentation for the genlink module in /mk/README.

Device database file structure
------------------------------

Line description:
  <pattern> <parent> (<data> ...)

  <pattern>: is the pattern for the chip description to be searched for.
      The case of the pattern string is ignored.
      Pattern match symbols:
          ?  - matches exactly one character
          *  - matches none or more characters
          +  - matches single or more characters

  <parent>: is the parent group name, where the search will continue.
      There are special parents names that controls traversing:
          "END" - Exit traversal.
          "+"   - Don't change the parent. Use for split long line to two.

  <data>: space-separated list of preprocessor symbols supplied to the linker.
      -D option name with single underscore is automatically prepended to each
         symbol definition
      if the symbol starts with dash "-", it is interpreted as parameter to
      linker, and no -D or underscore is generated.

All lines starting with # symbol are treated as Comments

Recommended tree hierarchy:

  <device name> <family group> <device specific params>
      +- <family group> <family> <family group specific params>
          +- <family> <architecture> <device family specific params>
              +- <architecture> END <architecture specific params>

You can split the long line into two or more by using "+" in the parent field,
and defining same regex with appropriate parent on the next line. Example:

   device + PARAM1=aaa PARAM2=bbbb PARAM3=ccc PARAM4=dddd PARAM5=eeee
   device parent PARAM6=ffff PARAM7=gggg PARAM8=hhhh
   parent END

The order of the lines is important. After the regex match, its parent will
be used for match on the next line. If two regexp lines matches input, only
the first will be evaluated, except special group definition "+"

The regex matches entire sym

Example:

--- devices.data file ---
stm32f05[01]?4* stm32f0 ROM=16K RAM=4K
stm32f0 stm32 ROM_OFF=0x08000000 RAM_OFF=0x20000000 -mcpu=cortex-m0 -mthumb
stm32 END

--- queried chip name ---
stm32f051c4t6

--- output of the python script ---
-D_ROM=16K -D_RAM=4K -D_ROM_OFF=0x08000000 -D_RAM_OFF=0x20000000

The generated linker script file will contain sections rom and ram with 
appropriate initialization code, specified in linker file source linker.ld.S


Copyright
---------

This file is part of the libopencm3 project.

Copyright (C) 2013 Frantisek Burian <Bufran@seznam.cz>
Copyright (C) 2013 Werner Almesberger <wpwrak>

This library is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this library. If not, see <http://www.gnu.org/licenses/>.