Browse Source

Readme translated to English

Ondřej Hruška 6 years ago
parent
commit
905d23b1ed
3 changed files with 160 additions and 46 deletions
  1. 1 0
      LICENSE
  2. 94 0
      README.cz.md
  3. 65 46
      README.md

+ 1 - 0
LICENSE View File

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

+ 94 - 0
README.cz.md View File

@@ -0,0 +1,94 @@
1
+# Bootstrap projekt a asm knihovna pro STM32L100RC
2
+
3
+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]).
4
+
5
+- Ukázkový program je založený na starším kódu © Michal Tomáš, 2010.
6
+- Základ knihovny a projektu © Petr Douša, 2015.
7
+- Další úpravy knihovny, Makefile © Ondřej Hruška, 2015.
8
+
9
+Kód je volně šiřitelný za podmínky zachování hlaviček souborů.
10
+
11
+
12
+## Popis projektu
13
+
14
+Jedná se o knihovnu definic adres registrů a bitů dle CMSIS a datasheetů spolu s ukázkovým programem,
15
+který knihovnu využívá (a demonstruje nastavení RCC a pinů).
16
+
17
+
18
+## Cílový hardware
19
+
20
+Projekt je určen pro procesor **STM32L100RC** v kitu **STM32L100 Discovery**, který se připojí přes USB.
21
+
22
+
23
+## Knihovna
24
+
25
+Assemblerová knihovna sestává ze sady souborů ve složce `lib/` a startup scriptu `startup_stm32l100xc.s` (ten pochází
26
+z instalace Keilu, dle hlavičky je přímo od ST).
27
+
28
+Soubor `INI_REGS.s` obsahuje definice adres registrů, soubory `INI_BITS_*.s` pak bitové masky a hodnoty
29
+jednotlivých registrů.
30
+
31
+Soubor `INI_BB.s` poskutuje adresy pro bit-banding.
32
+
33
+Soubory ze složky `lib/` je nutné naincludovat do hlavního programu, např.
34
+
35
+```asm
36
+        ; Register addresses
37
+        GET        lib/INI_REGS.s
38
+        GET        lib/INI_BB.s    ; Must be included *after* INI_REGS!
39
+
40
+        ; Bit presets
41
+        GET        lib/INI_BITS_GPIO.s
42
+        GET        lib/INI_BITS_RCC.s
43
+        GET        lib/INI_BITS_FLASH.s
44
+```
45
+
46
+## Formátování
47
+
48
+Soubory jsou formátovány se šířkou tabulátoru 4 znaky, komentáře jsou anglicky nebo bez diakritiky.
49
+
50
+Soubory mají Windowsové konce řádků, aby nebyl problém s Keilem (a většina lidí to bude používat pod Windows).
51
+
52
+
53
+## Jak s projektem pracovat
54
+
55
+### Windows - Keil MDK-ARM
56
+
57
+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).
58
+
59
+Keil je primárně pro Windows, pod Wine funguje, ale nedokáže přistupovat na ST-Link.
60
+
61
+Ve Vitualboxu funguje včetne ST-Linku, ovšem pouze s verzí 2.
62
+
63
+
64
+### Linux
65
+
66
+Kompilace a nahrávání probíhá pomocí Makefile v projektu.
67
+
68
+Napřed je potřeba nainstalovat následující software:
69
+
70
+1. Pomocí `wine` nainstalovat Keil (do `~/.wine`) - z jeho složky se berou binutils a assembler, nejde je přesunout kvůli
71
+   licenčním souborům. Teoreticky by mohlo jít použít linuxové verze, pokud zjistíte jak nastavit, aby používaly licenční
72
+   soubory z Keilu (omezení na 32 kB).
73
+
74
+2. Zkontrolovat v Makefile, že proměnná `WINEPREFIX` obsahuje správnou cestu ke složce s exe soubory z Keilu, případně opravit.
75
+   Pokud používáte nativní linuxové verze těchto programů, upravte náležitě Makefile.
76
+
77
+3. Pro plnou funkčnost se hodí doinstalovat `arm-none-eabi-binutils`, ale není nutné - jen pro `make disasm`
78
+
79
+4. Dále je potřeba nainstalovat `stlink` pro komunikaci s deskou, linuxová verze je volně dostupná.
80
+
81
+
82
+*Tip:* Uživatelé ArchLinuxu vše najdou v oficiálních repozitářích.
83
+
84
+
85
+#### V čem editovat
86
+
87
+Jako editor lze použít Keil pod wine, libovolný textový editor nebo ARM IDE DS-5 *Community Edition* - bohužel nedovoluje
88
+nic kompilovat, ale má dobru podporu pro assembler a kontextovou nápovědu.
89
+
90
+DS-5 podporuje Makefile, ale není to nic extra - lepší `make` spouštět v terminálu.
91
+
92
+[measure]: http://measure.feld.cvut.cz/
93
+[nvs]: http://measure.feld.cvut.cz/vyuka/predmety/A4B38NVS
94
+[mmp]: http://measure.feld.cvut.cz/vyuka/predmety/A3B38MMP

+ 65 - 46
README.md View File

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