------------------------------------------------------------------------------ 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: ( ...) : 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 : 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. : 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: +- +- +- END 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 Copyright (C) 2013 Werner Almesberger 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 .