update docs, add info about cross-compilation and SPL splitting

tenbaht · tenbaht · commit 2dfc4893ab99 · 2019-01-11T11:33:04.000+01:00
diff --git a/docs/developer/coding-style.md b/docs/developer/coding-style.md
@@ -0,0 +1,34 @@
+# Coding style
+
+## Development workflow
+
+I recently read this great article about [a successful branching
+model](https://nvie.com/posts/a-successful-git-branching-model/) for git and
+will implement it. Highly recommended!
+
+
+## Changelog
+
+Every feature branch (or pull request) should include an update for
+Changelog.md
+
+
+## Code format
+
+When porting an existing Arduino library I try to preserve the original
+formatting as much as possible to allow for easy comparison to the original
+state.
+
+There is a development of a C++ capable compiler environment going on. There
+is no public website for that project yet, but I am in contact with the
+developer. He is even targeting Sduino for his project and at one point in
+the (still distant) future we might be able to switch back to the orginal
+library code again. Preserved code structure would be a big plus then. (But
+don't hold your breath yet)
+
+Newly written code is mostly formatted using indent according to the linux
+kernel coding style, using Tabs, Tab width 8, line length 80:
+
+```bash
+indent -linux
+```
diff --git a/docs/developer/cross-compile-for-osx.md b/docs/developer/cross-compile-for-osx.md
@@ -0,0 +1,102 @@
+# Cross-Compile for OSX
+
+Compiling the tools is really easy. Only setting up the cross compilation
+environment requires a little more effort. But luckily, the
+[osxcross](https://github.com/tpoechtrager/osxcross) project already took
+care of this.
+
+
+## Setting up the cross compilation environment on Linux Mint 19
+
+### Install the needed dependencies
+
+I needed only these (the others were already present):
+
+	sudo apt install clang llvm-dev uuid-dev libssl-dev libbz2-dev
+
+Full list of all dependencies:
+
+	sudo apt install clang llvm-dev libxml2-dev uuid-dev libssl-dev bash patch make  tar xz-utils bzip2 gzip sed cpio libbz2-dev
+
+
+### Get the MacOSX SDK
+
+#### The official way
+
+Extract the needed files from the official SDKs Xcode 7.3 from the Apple
+Developer website using the scripts that come with osxcross:
+
+	sudo apt install cmake libxml2-dev fuse libfuse-dev
+	./tools/gen_sdk_package_darling_dmg.sh path/to/SDK-file
+
+On Ubuntu-based distributions with a name not containing the string "ubuntu"
+(like Linux Mint) you will get an error message "Required kernel module
+'fuse' not loaded". To fix this, "echo out" the line `modinfo fuse
+&>/dev/null` in tools/gen_sdk_package_darling_dmg.sh by changing it to `echo
+modinfo fuse &>/dev/null` before running it (don't delete it or comment it
+out).
+
+
+```diff
+diff --git a/tools/gen_sdk_package_darling_dmg.sh b/tools/gen_sdk_package_darling_dmg.sh
+index 8cd23e5..b271450 100755
+--- a/tools/gen_sdk_package_darling_dmg.sh
++++ b/tools/gen_sdk_package_darling_dmg.sh
+@@ -40,7 +40,7 @@ command -v lsb_release 2>&1 > /dev/null
+ if [[ $? -eq 0 ]] && [[ -n $(lsb_release -a 2>&1 | grep -i ubuntu) ]]; then
+   echo "Using ubuntu, skipping fuse module check"
+ else
+-  modinfo fuse &>/dev/null
++  echo modinfo fuse &>/dev/null
+ fi
+ 
+ if [ $? -ne 0 ]; then
+```
+
+Now move the resulting file `MacOSX10.11.sdk.tar.xz` into the tarball directory.
+
+
+
+#### The easy way
+
+Somebody was kind enough to set up a repository with all the [MacOSX
+SDKs](https://github.com/phracker/MacOSX-SDKs). This saves you the trouble
+of downloading multiple gigabytes of data and running the extraction script.
+
+Download the file
+[MacOSX10.11.sdk.tar.xz](https://github.com/phracker/MacOSX-SDKs/releases/download/10.13/MacOSX10.11.sdk.tar.xz)
+into the tarball directory.
+
+
+
+
+
+### Build OSXcross:
+
+	./build.sh
+	sudo mv target /opt/osxcross
+
+Add `/opt/osxcross/bin` to your `$PATH` and prepare macports:
+
+	export MACOSX_DEPLOYMENT_TARGET=10.7
+	export PATH=$PATH:/opt/osxcross/bin
+	osxcross-macports update-cache
+
+
+
+## Build stm8flash
+
+	osxcross-macports install libusb-devel
+	make CC=o64-clang CXX=o64-clang++ PKGCONFIG=x86_64-apple-darwin15-pkg-config RELEASE=yes
+
+Or with full path if you didn't add the osxcross binary directory do your
+PATH:
+
+	make CC=/opt/osxcross/bin/o64-clang CXX=/opt/osxcross/bin/o64-clang++ PKGCONFIG=/opt/osxcross/bin/x86_64-apple-darwin15-pkg-config RELEASE=yes
+
+
+## Build stm8gal
+
+	make CC=o64-clang
+
+That's all!
diff --git a/docs/developer/links.md b/docs/developer/links.md
@@ -2,6 +2,10 @@
 
 ## Further reading and application notes
 
+A very good and compact primer on
+[STM8S-Programming](https://github.com/TG9541/stm8ef/wiki/STM8S-Programming).
+Does not rely on any external libraries.
+
 [A series of
 articles](https://lujji.github.io/blog/bare-metal-programming-stm8/) on bare
 metal programming of the STM8S CPUs. By far the best introduction I
diff --git a/docs/developer/optimizations.md b/docs/developer/optimizations.md
@@ -0,0 +1,92 @@
+# Optimizations
+
+The goal is to reduce the size of the generated binaries. This is done by
+aiding the linker to eleminate dead code by splitting large source files and
+by hand-optimizing individual functions.
+
+## Results
+
+The sum of all these optimizations reduces the total size of Blink.ino by
+more than 30%, saving more than 800 bytes of precious flash space:
+
+   code	 |  data|    RAM|  flash total	|split stage
+   ----  |  ----|   ----|   ----	|------------
+   2507	 |   138|     72|   2645	|before split
+   2450	 |   138|     72|   2588	|after splitting wiring.c
+   2381	 |   138|     72|   2519	|after splitting wiring_digital.c
+   1799	 |   138|     72|   1937	|after splitting HardwareSerial.c
+   1686	 |   138|     72|   1824	|after optimizing pinMode()
+
+Data is mostly the tables to map the Arduino pin numbers to the actual port
+registers. RAM is mostly the transmit and receive buffers for serial
+communication. These can't easily be optimized out.
+
+
+## Splitting files
+
+The SDCC linker does not detect unused functions and constants in an object
+file. It always links the whole file even if only a single symbol contained
+in the file is referenced. This results in pretty bloated binaries if the
+SPL is used.
+
+Splitting larger source files into smaller units and compile them
+individually before building the libraries helps the SDCC linker to
+eleminate dead code and to produce smaller binaries.
+
+Splitting files is worthwhile for all SPL files and at least some of the
+bigger Arduino core files.
+
+
+### The stategy
+
+The SPL consists of many source files with a very regular structure. This
+allows to automate the splitting process with very little preparation work.
+
+All SPL functions are documented with a doxygen comment block. The beginning
+of this comment block is a line with only "/**", that can easily be used as
+a marker for splitting the files.
+
+Only the very first block is special. It contains definitions and prototypes
+that are needed all over the module. This block is saved as a `.h` file and
+`#include`'d by all the following blocks.
+
+In most cases this is already sufficient. Only in very rare cases the
+position of a split needs the be edited. This is automatically done by the
+patches in the `patches/` directory.
+
+**To prevent a split**: Change the `/**` line into something different, `/***`
+is used in the scripts.
+
+**To force a split**: Add an empty Doxygen comment block:
+```c
+/**
+ */
+```
+
+
+### Splitting the SPL files
+
+Splitting and compiling the SPL libraries is moved into the separate project
+[spl-splitter](https://github.com/tenbaht/spl-splitter) now.
+
+
+
+### Split Arduino core files
+
+`wiring.c`, `wiring_digital.c` and `HardwareSerial.c` all compile into quite
+large binaries. All of them are linked with almost 
+every project. This is true even if no serial communication is used since
+main.c references `serialEvent()` and this way pulls in all of
+HardwareSerial.
+
+Splitting these three files reduces the size of simple sketches
+significantly. It does not help so much for complex sketches that use almost
+all functions of these modules.
+
+
+
+## Optimizing individual functions
+
+`pinMode()` sticks out when looking at the size of individual functions. 270
+bytes for just setting the IO-mode of a pin. A re-write in assember reduces
+this to just 147 bytes.
diff --git a/docs/developer/spl.md b/docs/developer/spl.md
@@ -10,38 +10,20 @@ zip file. This and [Lujji's
 blog](https://lujji.github.io/blog/bare-metal-programming-stm8/) is the most
 useful reference on using this library and programming the STM8 in general.
 
-For use with SDCC the library needs to be patched:
+For use with SDCC the library needs to be patched with Georg's [SPL-SDCC
+patches](https://github.com/gicking/STM8-SPL_SDCC_patch):
 
 ```bash
-git clone https://github.com/g-gabber/STM8S_StdPeriph_Driver.git
-git clone https://github.com/gicking/SPL_2.2.0_SDCC_patch.git
-cp ../STM8S_SPL_2.2.0/Libraries/STM8S_StdPeriph_Driver/inc/stm8s.h .
-patch -p1 < ../SPL_2.2.0_SDCC_patch/STM8_SPL_v2.2.0_SDCC.patch
-cp -av  ../STM8S_StdPeriph_Lib/Project/STM8S_StdPeriph_Template/stm8s_conf.h .
-cp -av  ../STM8S_StdPeriph_Lib/Project/STM8S_StdPeriph_Template/stm8s_it.h .
+unzip en.stsw-stm8069.zip
+wget https://raw.githubusercontent.com/gicking/STM8-SPL_SDCC_patch/master/STM8S_StdPeriph_Lib_V2.3.1_sdcc.patch
+patch -p0 < STM8S_StdPeriph_Lib_V2.3.1_sdcc.patch
 ```
 
-SDCC uses .rel as the file extension for its object files.
+Check out the test project and the project template in
+`STM8S_StdPeriph_Lib/Project/STM8S_StdPeriph_test` and
+`STM8S_StdPeriph_Lib/Project/STM8S_StdPeriph_Template`
 
-Additional patch required for stm8s_itc.c:
-
-```diff
---- stm8s_itc.c~	2014-10-21 17:32:20.000000000 +0200
-+++ stm8s_itc.c	2016-12-11 21:56:41.786048494 +0100
-@@ -55,9 +55,12 @@
-   return; /* Ignore compiler warning, the returned value is in A register */
- #elif defined _RAISONANCE_ /* _RAISONANCE_ */
-   return _getCC_();
--#else /* _IAR_ */
-+#elif defined _IAR_ /* _IAR_ */
-   asm("push cc");
-   asm("pop a"); /* Ignore compiler warning, the returned value is in A register */
-+#else /* _SDCC_ */
-+  __asm__("push cc");
-+  __asm__("pop a"); /* Ignore compiler warning, the returned value is in A register */
- #endif /* _COSMIC_*/
- }
-```
+SDCC uses .rel as the file extension for its object files.
 
 
 
@@ -79,14 +61,15 @@ clean:
 This library can now be used for linking with blink_spl or uart_spl. The
 files stm8s_conf.h and stm8s_it.h are still needed for compilation.
 
+
+### Optimizing the code
+
 The linker does not remove individual unused functions from an object file,
 only complete object files can be skipped.  
 **=> for building a library it is better to separate all functions into
 individual source files **
 
-The SPL folder in this archive contains a script `doit` to separate the
-functions before compilation.
-FIXME: description needed
+See [here](../optimizations/#splitting-files) for details.
 
 A suggestion how to move at least the IRQ vectors away from the libray into
 the own source files:
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -41,12 +41,15 @@ nav:
     - Developer Guide:
         - IDE integration: 'developer/ide-integration.md'
         - Compiling the tools: 'developer/compiling-the-tools.md'
+        - Cross-compiling the tools for OSX: 'developer/cross-compile-for-osx.md'
         - Update an automatic installation to a manual installation: 'developer/update-to-manual.md'
         - C preprocessor macro magic: 'developer/macro.md'
         - Ways to define a pin mapping: 'developer/pin_mapping.md'
+        - Coding style: 'developer/coding-style.md'
         - Using the SDCC compiler: 'developer/sdcc.md'
         - Using the SPL with SDCC and sduino: 'developer/spl.md'
         - Bare metal programming on the STM8: 'developer/bare-metal-programming.md'
+        - Optimizations: 'developer/optimizations.md'
         - Performance comparison and benchmarking: 'developer/performance.md'
         - Links and further reading: 'developer/links.md'
     - Contact: contact.md
