From 905d23b1edce8d99cea6b3f90d2912d681ea20ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Hru=C5=A1ka?= Date: Wed, 21 Oct 2015 16:08:10 +0200 Subject: [PATCH] Readme translated to English --- LICENSE | 1 + README.cz.md | 94 +++++++++++++++++++++++++++++++++++++++++++ README.md | 111 ++++++++++++++++++++++++++++++--------------------- 3 files changed, 160 insertions(+), 46 deletions(-) create mode 100644 README.cz.md diff --git a/LICENSE b/LICENSE index a80d7d8..2ae823c 100644 --- a/LICENSE +++ b/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 diff --git a/README.cz.md b/README.cz.md new file mode 100644 index 0000000..9eb11cd --- /dev/null +++ b/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 diff --git a/README.md b/README.md index 9eb11cd..0c53538 100644 --- a/README.md +++ b/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. -- Základ knihovny a projektu © Petr Douša, 2015. -- Další úpravy knihovny, Makefile © Ondřej Hruška, 2015. +## Project description -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, -který knihovnu využívá (a demonstruje nastavení RCC a pinů). +A startup script (startup_stm32l100xc.s) comes from the Keil device packages, and can also be +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í -z instalace Keilu, dle hlavičky je přímo od ST). +The assembler library is located in a `lib/` folder, and consists of multiple modules. -Soubor `INI_REGS.s` obsahuje definice adres registrů, soubory `INI_BITS_*.s` pak bitové masky a hodnoty -jednotlivých registrů. +To use any of the modules, first include `INI_BASE.s`, then the required modules (in any order). -Soubor `INI_BB.s` poskutuje adresy pro bit-banding. - -Soubory ze složky `lib/` je nutné naincludovat do hlavního programu, např. +Example of the library usage: ```asm - ; Register addresses - GET lib/INI_REGS.s - GET lib/INI_BB.s ; Must be included *after* INI_REGS! + ; Base file + GET lib/INI_BASE.s - ; 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 - 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). +The "official" ARM IDE, DS-5, is really expensive, but there's a free "Community Edition". -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. +The IDE is a customized Eclipse, so if you have some Eclipse experience, you're right at home. -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