[GENLINK] Edit the documentation to match current version

ld/README

@@ -1,20 +1,153 @@
-libopencm3 Linker script generator
+------------------------------------------------------------------------------
-5 July 2013 (C) Franisek Burian
+README
--------------------------------
+------------------------------------------------------------------------------
 
-This folder contains files needed for the automatic linker script generation 
+LIBOPENCM3 LINKER SCRIPT GENERATOR
+----------------------------------
+
+This folder contains files needed for the automatic linker script generation
 mechanism developed for libopencm3 library.
 
-FILE CONTENTS
+File contents
 -------------
 
-* devices.data - device database file, containing 
+* {ROOT}/ld/tests/* 		- Prepared tests for the testing of the script
-* Makefile.linker - Common makefile part, ready to be included in user files
+* {ROOT}/ld/devices.data	- Device database file
+* {ROOT}/ld/Makefile.linker	- Common makefile part
+* {ROOT}/src/linker.ld.S	- Linker script template
+* {ROOT}/scripts/genlink.awk	- Device database file search script 
+* {ROOT}/scripts/genlinktest.sh	- Device database file search test script
 
-HACKING
+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
+
+Then, the user includes the file /ld/Makefile.linker exactly after the first
+target (usually all) has been defined.
+
+The script automatically modifies the $(LDSCRIPT) variable to meet the new
+generated script with <device part name>.ld in the project directory, and adds
+a rule to make it from the scratch.
+
+Making the script is done by looking to device database file for the needed
+definitions, and applying those definitions to the C preprocessor source
+linker.ld.S outputting the preprocessed ld file.
+
+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 awk script
+genlink.awk. The awk script traverses the file as a tree, joining the options
+for the preprocessor together by single space. The awk script adds -D to each
+parameter for you.
+
+Testing
 -------
 
-EXAMPLE OF USE
+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
 --------------
 
-* See Makefile.example file
+* See Makefile.example file
+
+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 is automatically prepended to each symbol definition
+
+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
+stm32 END
+
+--- queried chip name ---
+stm32f051c4t6
+
+--- output of the awk script ---
+-DROM=16K -DRAM=4K -DROM_OFF=0x08000000 -DRAM_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/>.

scripts/genlink.awk

@@ -1,9 +1,25 @@
-# This program converts chip name to the series of definitions for make of
+# This awk program generates parameters for the linker script generator feature.
-# automatic linker script.
 #
+# See ld/README file for more info.
+#
+
+# 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/>.
 
 BEGIN {
 	PAT = tolower(PAT);

scripts/genlinktest.sh

@@ -1,5 +1,29 @@
 #!/bin/sh
 
+# This script is intended to test the awk program genlink.awk for the linker 
+# script generator feature.
+#
+# See ld/README file for more info.
+#
+
+# 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/>.
+
 # run test
 PAAT=`basename $1`;
 awk -v PAT="$PAAT" -f scripts/genlink.awk $1.data > $1.out;