Add READMEHEADmaster

1 files changed, 81 insertions, 0 deletions

diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..dd64a57
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,81 @@
+STM32 Support Files Git Repository
+==================================
+
+This is an inofficial git repository containing data files describing ST's STM32 series of microcontrollers. It is
+automatically updated every night from ST's STM32 Cube IDE Eclipes P2 update servers. The data files in this repo
+contain machine-readable descriptions of e.g. the microcontrollers memory map (.db files) and peripherals (svd).
+
+The "official" inofficial home of this repo is: https://gitlab.com/neinseg/stm32square
+
+Raison d'être
+-------------
+
+ST's tooling such as the free STM32 Cube IDE as well as their STM32 Cube driver/BSP packages contain a lot of
+machine-readable information about STM32 microcontroller's internals. There's the ARM standard SVD files that describe
+all peripheral registers and their bits, and there's a whole lot of ST-specific XML files that describe things such as
+the chip's memory map.
+
+Both of these are extremely useful when you're building your STM32 firmware outside of ST's STM32 Cube IDE. Since the
+Cube IDE is Eclipse-based, there are about 2.2GB worth of good reasons to use another toolchain.
+
+ST already publishes the driver and template code packages `on github
+<https://github.com/STMicroelectronics/STM32Cube_MCU_Overall_Offer>`_. These repositories contain things like startup
+code and CMSIS headers for all their microcontrollers, but for some reason ST does not include SVD files or
+machine-readable memory maps anywhere.
+
+For this reason, in its "Release" branch, this repository contains a copy of the data files used by the STM32 Cube IDE
+that is updated daily using a Gitlab CI. The CI job pulls ST's official STM32 Cube IDE Eclipse artifacts from the IDE's
+Eclipse p2 update repository and extracts the relevant data files from these Eclipse artifacts.
+
+Licensing
+---------
+
+I was pleasantly surprised to see that ST has included fairy permissive licenses with all of these files.  All artifacts
+contain license information either right next to the data files or as part of the artifact. We simply copy this license
+information along with the data files. Please read these licenses for yourself. The main thing you should be aware of is
+that in some of their licenses, ST prohibits usage of their stuff with non-ST chips. Notably, this would prevent you
+from using it with any of the gazillion chinese clones of their popular F103 µC.
+
+The Makefile, shell and python CI code itself in this repo is licensed under a `Creative Commons Zero (CC-0) public
+domain license <http://creativecommons.org/publicdomain/zero/1.0/>`_.
+
+Repository Structure
+--------------------
+
+Branches
+~~~~~~~~
+
+This repository has two main branches: The master branch contains only the pristine update scripts, and does not contain
+any pulled files anywhere in its history. The release branch merges in any changes to the update scripts on the master
+branch, but additionally is updated by the nightly gitlab CI run to include ST's data files.
+
+To use these files from your code, you could either pull in this repo's ``release`` branch e.g. as a git submodule, or
+you could pull in its ``master`` branch and use the ``Makefile`` to let ``make`` download the files for you. 
+
+Tags
+~~~~
+
+The nightly CI job automatically generates three types of tags:
+
+``v-nightly-20-11-18``
+  Nightly releases. One such release is generated each day, and contains ST's latest update.
+
+``v-ide-1.2.3``
+  STM32 Cube IDE release. Every time the IDE updates to a new version, a tag like this is created.
+
+This repo extracts data from three separate STM32 Cube IDE Eclipse P2 Artifacts that are versioned independently by ST.
+For every new version of each of these artifacts, two tags are created as follows:
+
+``v-[component]-1.2.3``
+  Component version tag. This describes the state when the artifact version ``1.2.3`` was published.
+
+``v-[component]-1.2.3.202011182342``
+  Component build tag. This describes the state when the artifact build ``202011182342`` of version ``1.2.3`` was published.
+
+Building
+--------
+
+One thing to note is that ST's Eclipse P2 repo server seems to kind of suck. Requests time out a lot, which is why we
+have wget retry up to 10 times. In case you're still getting download errors, be aware that chances are it's their
+server and not your internet.
+