Readme translated to English

LICENSE

@@ -1,3 +1,4 @@
+Library License
 
 Copyright (c) 2010 Michal Tomáš  - part of the example program
 Copyright (c) 2015 Petr Douša    - conversion of CMSIS defintions to assembler

README.cz.md

@@ -0,0 +1,94 @@
+# Bootstrap projekt a asm knihovna pro STM32L100RC
+
+Projekt je vyvíjen na [*Katedře měření ČVUT FEL v Praze*][measure] a bude sloužit pro předmět [NVS][nvs] (příp. [MMP][mmp]).
+
+- Ukázkový program je založený na starším kódu © Michal Tomáš, 2010.
+- Základ knihovny a projektu © Petr Douša, 2015.
+- Další úpravy knihovny, Makefile © Ondřej Hruška, 2015.
+
+Kód je volně šiřitelný za podmínky zachování hlaviček souborů.
+
+
+## Popis projektu
+
+Jedná se o knihovnu definic adres registrů a bitů dle CMSIS a datasheetů spolu s ukázkovým programem,
+který knihovnu využívá (a demonstruje nastavení RCC a pinů).
+
+
+## Cílový hardware
+
+Projekt je určen pro procesor **STM32L100RC** v kitu **STM32L100 Discovery**, který se připojí přes USB.
+
+
+## Knihovna
+
+Assemblerová knihovna sestává ze sady souborů ve složce `lib/` a startup scriptu `startup_stm32l100xc.s` (ten pochází
+z instalace Keilu, dle hlavičky je přímo od ST).
+
+Soubor `INI_REGS.s` obsahuje definice adres registrů, soubory `INI_BITS_*.s` pak bitové masky a hodnoty
+jednotlivých registrů.
+
+Soubor `INI_BB.s` poskutuje adresy pro bit-banding.
+
+Soubory ze složky `lib/` je nutné naincludovat do hlavního programu, např.
+
+```asm
+        ; Register addresses
+        GET        lib/INI_REGS.s
+        GET        lib/INI_BB.s    ; Must be included *after* INI_REGS!
+
+        ; Bit presets
+        GET        lib/INI_BITS_GPIO.s
+        GET        lib/INI_BITS_RCC.s
+        GET        lib/INI_BITS_FLASH.s
+```
+
+## Formátování
+
+Soubory jsou formátovány se šířkou tabulátoru 4 znaky, komentáře jsou anglicky nebo bez diakritiky.
+
+Soubory mají Windowsové konce řádků, aby nebyl problém s Keilem (a většina lidí to bude používat pod Windows).
+
+
+## Jak s projektem pracovat
+
+### Windows - Keil MDK-ARM
+
+Projekt je primárně určen pro **µVision MDK-ARM v.5**, asm soubory fungují i ve verzi 4 (ale projekt bude potřeba upravit).
+
+Keil je primárně pro Windows, pod Wine funguje, ale nedokáže přistupovat na ST-Link.
+
+Ve Vitualboxu funguje včetne ST-Linku, ovšem pouze s verzí 2.
+
+
+### Linux
+
+Kompilace a nahrávání probíhá pomocí Makefile v projektu.
+
+Napřed je potřeba nainstalovat následující software:
+
+1. Pomocí `wine` nainstalovat Keil (do `~/.wine`) - z jeho složky se berou binutils a assembler, nejde je přesunout kvůli
+   licenčním souborům. Teoreticky by mohlo jít použít linuxové verze, pokud zjistíte jak nastavit, aby používaly licenční
+   soubory z Keilu (omezení na 32 kB).
+
+2. Zkontrolovat v Makefile, že proměnná `WINEPREFIX` obsahuje správnou cestu ke složce s exe soubory z Keilu, případně opravit.
+   Pokud používáte nativní linuxové verze těchto programů, upravte náležitě Makefile.
+
+3. Pro plnou funkčnost se hodí doinstalovat `arm-none-eabi-binutils`, ale není nutné - jen pro `make disasm`
+
+4. Dále je potřeba nainstalovat `stlink` pro komunikaci s deskou, linuxová verze je volně dostupná.
+
+
+*Tip:* Uživatelé ArchLinuxu vše najdou v oficiálních repozitářích.
+
+
+#### V čem editovat
+
+Jako editor lze použít Keil pod wine, libovolný textový editor nebo ARM IDE DS-5 *Community Edition* - bohužel nedovoluje
+nic kompilovat, ale má dobru podporu pro assembler a kontextovou nápovědu.
+
+DS-5 podporuje Makefile, ale není to nic extra - lepší `make` spouštět v terminálu.
+
+[measure]: http://measure.feld.cvut.cz/
+[nvs]: http://measure.feld.cvut.cz/vyuka/predmety/A4B38NVS
+[mmp]: http://measure.feld.cvut.cz/vyuka/predmety/A3B38MMP

README.md

@@ -1,93 +1,112 @@
-# Bootstrap projekt a asm knihovna pro STM32L100RC
+# Bootstrap project and an asm library for STM32L100
 
-Projekt je vyvíjen na [*Katedře měření ČVUT FEL v Praze*][measure] a bude sloužit pro předmět [NVS][nvs] (příp. [MMP][mmp]).
+[Česká verze](README.cz.md)
 
-- Ukázkový program je založený na starším kódu © Michal Tomáš, 2010.
+## Project description
-- Základ knihovny a projektu © Petr Douša, 2015.
-- Další úpravy knihovny, Makefile © Ondřej Hruška, 2015.
 
-Kód je volně šiřitelný za podmínky zachování hlaviček souborů.
+The project consists of a definition library for the STM32L100 ARM microcontroller.
 
+The library is in a large part converted from the device-specific CMSIS header files, other
+files are based on the datasheets.
 
-## Popis projektu
+The project also includes a simple "Hello World" program which demonstrates usage of the library
+by blinking the LEDs on your STM32L100 Discovery board.
 
-Jedná se o knihovnu definic adres registrů a bitů dle CMSIS a datasheetů spolu s ukázkovým programem,
+A startup script (startup_stm32l100xc.s) comes from the Keil device packages, and can also be
-který knihovnu využívá (a demonstruje nastavení RCC a pinů).
+found in the CMSIS.
 
 
-## Cílový hardware
+## Target hardware
 
-Projekt je určen pro procesor **STM32L100RC** v kitu **STM32L100 Discovery**, který se připojí přes USB.
+The project targets the STM32L100RC on the STM32L100C-DISCO Discovery development board. The kit
+is attached to the computer using a USB cable.
 
 
-## Knihovna
+## Library structure
 
-Assemblerová knihovna sestává ze sady souborů ve složce `lib/` a startup scriptu `startup_stm32l100xc.s` (ten pochází
+The assembler library is located in a `lib/` folder, and consists of multiple modules.
-z instalace Keilu, dle hlavičky je přímo od ST).
 
-Soubor `INI_REGS.s` obsahuje definice adres registrů, soubory `INI_BITS_*.s` pak bitové masky a hodnoty
+To use any of the modules, first include `INI_BASE.s`, then the required modules (in any order).
-jednotlivých registrů.
 
-Soubor `INI_BB.s` poskutuje adresy pro bit-banding.
+Example of the library usage:
-
-Soubory ze složky `lib/` je nutné naincludovat do hlavního programu, např.
 
 ```asm
-        ; Register addresses
+        ; Base file
-        GET        lib/INI_REGS.s
+        GET        lib/INI_BASE.s
-        GET        lib/INI_BB.s    ; Must be included *after* INI_REGS!
 
-        ; Bit presets
+        ; Registers and bit presets for the peripherals
         GET        lib/INI_BITS_GPIO.s
         GET        lib/INI_BITS_RCC.s
         GET        lib/INI_BITS_FLASH.s
 ```
 
-## Formátování
+## Code style
+
+All comments are in English. Files are formatted with spaces, or tabs 4 spaces wide.
+
+All files should use Windows line endings for compatibility with Keil.
+
+## Development environment
+### Keil MDK-ARM (Windows)
+
+The library will work with any tool that supports the ARM assembler.
+
+Included are project files for **µVision MDK-ARM v.5** (Keil).
+
+### Working on Linux
 
-Soubory jsou formátovány se šířkou tabulátoru 4 znaky, komentáře jsou anglicky nebo bez diakritiky.
+On Linux, you can run Keil in Wine (without hardware support), and also in Virtualbox
+(but with ST-Link v2 only).
 
-Soubory mají Windowsové konce řádků, aby nebyl problém s Keilem (a většina lidí to bude používat pod Windows).
+If you choose to use a more native "IDE" (read: vim, Sublime Text...), you can use the
+provided Makefile for compilation and flashing.
 
+First, though, you have to setup the compiler:
 
-## Jak s projektem pracovat
+1. Install Keil in `wine` (into `~/.wine`) - we'll be using the trial version of
+   the otherwise paid compiler, and for that we need the Keil license files.
 
-### Windows - Keil MDK-ARM
+   If you are adventurous, you can try to use the Keil license files with the native Linux
+   version of the compiler.
 
-Projekt je primárně určen pro **µVision MDK-ARM v.5**, asm soubory fungují i ve verzi 4 (ale projekt bude potřeba upravit).
+2. Check that the Makefile variable `WINEPREFIX` points to the folder with the Keil
+   compiler binaries. If you are using the linux versions of those, adjust your Makefile
+   accordingly.
 
-Keil je primárně pro Windows, pod Wine funguje, ale nedokáže přistupovat na ST-Link.
+3. For a disassembler support, install `arm-none-eabi-binutils`. This is optional.
 
-Ve Vitualboxu funguje včetne ST-Linku, ovšem pouze s verzí 2.
+4. Install the `stlink` package - drivers for communication with the development board.
+   This step is optional, if you don't need flashing.
 
 
-### Linux
+*Tip:* ArchLinuxu users can find both `stlink` and `arm-none-eabi-binutils` in the Community
+repository.
 
-Kompilace a nahrávání probíhá pomocí Makefile v projektu.
 
-Napřed je potřeba nainstalovat následující software:
+### Using the ARM DS-5
 
-1. Pomocí `wine` nainstalovat Keil (do `~/.wine`) - z jeho složky se berou binutils a assembler, nejde je přesunout kvůli
+The "official" ARM IDE, DS-5, is really expensive, but there's a free "Community Edition".
-   licenčním souborům. Teoreticky by mohlo jít použít linuxové verze, pokud zjistíte jak nastavit, aby používaly licenční
-   soubory z Keilu (omezení na 32 kB).
 
-2. Zkontrolovat v Makefile, že proměnná `WINEPREFIX` obsahuje správnou cestu ke složce s exe soubory z Keilu, případně opravit.
+The IDE is a customized Eclipse, so if you have some Eclipse experience, you're right at home.
-   Pokud používáte nativní linuxové verze těchto programů, upravte náležitě Makefile.
 
-3. Pro plnou funkčnost se hodí doinstalovat `arm-none-eabi-binutils`, ale není nutné - jen pro `make disasm`
+**The catch** is that this variant **can't compile anything** - not even assembler.
+The editor and the context-help manual viewer work perfectly, though.
 
-4. Dále je potřeba nainstalovat `stlink` pro komunikaci s deskou, linuxová verze je volně dostupná.
+There is some Makefile support, but I've found it rather pathetic. If you, however, install
+a terminal plugin into the IDE, you can conveniently run the Makefile tasks to compile and
+flash your program.
 
+## Credits
 
-*Tip:* Uživatelé ArchLinuxu vše najdou v oficiálních repozitářích.
+This project is developed for educational purposes at the [Department of Measurement][measure] of the CTU in Prague. The project may be used in the [NVS][nvs] and [MMP][mmp] courses.
 
+- The example program is based on an old code by Michal Tomáš © 2010.
+- Base of the library extracted from CMSIS by Petr Douša © 2015.
+- Further library improvements, organisation and the Makefile © Ondřej Hruška, 2015.
 
-#### V čem editovat
+The library code is free to use in any educational and non-commercial projects, provided you retain the copyright notice and the file header files.
 
-Jako editor lze použít Keil pod wine, libovolný textový editor nebo ARM IDE DS-5 *Community Edition* - bohužel nedovoluje
-nic kompilovat, ale má dobru podporu pro assembler a kontextovou nápovědu.
 
-DS-5 podporuje Makefile, ale není to nic extra - lepší `make` spouštět v terminálu.
 
 [measure]: http://measure.feld.cvut.cz/
 [nvs]: http://measure.feld.cvut.cz/vyuka/predmety/A4B38NVS