Svd2forth-v2

DOWNLOAD the latest svd2forth-v2 release **HERE**
_images/stm32-disco.jpg

Let’s assume you’re new to STMicro’s STM32xx ARM MCU’s, you have a nice new STM32F0 Discovery board (about $15) and you have installed Mecrisp-Stellaris Forth by Mathias Koch http://mecrisp.sourceforge.net/ on it.

Now you’d like to begin programming, but where do you start, the STM32 documentation is vast, and there are a LOT of registers involved. As a matter of interest, a STM32F051 MCU as used in a STM32F0 Discovery Board lists around 470 unique registers, can you imagine the work involved in manually creating the Forth Words to manipulate them all ?

CMIS-SVD

ARM created CMSIS-SVD to automate the job of telling “C” programs about STM32 MCU registers and register bit fields with SVDConv.exe.

CMIS-SVD files

  • Are XML text files detailing all registers (or most of them at least) for MCU families and not individual parts.
  • May be downloaded from https://github.com/posborne/cmsis-svd/archive/master.zip (39MB)
  • Programming language MCU specific files are created by applying XSLT stylesheets to the CMIS-SVD files.

Svd2forth-v2

Svd2forth-v2 by Terry Porter <terry@tjporter.com.au> 2016 for Mecrisp-Stellaris by Mathias Koch

  • Was created to use CMSIS-SVD files for automated Mecrisp-Stellaris Forth memory-mapped Word production, making target software development far easier and less error prone, especially for Forth beginners.
  • Enforces CMSIS compliant naming across all Mecrisp-Stellaris programs, enabling code reuse.
  • Developed on FreeBSD but also tested on a Ubuntu 16.04.1 x64 VM. This is for Unix and won’t run on Microsoft Windows unless you install all the stuff that turns Windows into Unix.

For the Impatient

  • Deps: xsltproc, make, and sed
  • Untar svd2forth-v2.tar.gz to a directory
  • run make, see what happened ? four additional files have been created ...
  • “m” is a Forth memory mapped Word list for every register in a STM32F0xx
  • “registers.text” is a developers reference for every register and bitfield in a STM32F0xx
  • If you don’t want all the registers as the “m” Word list is too large to upload to your Forth target chip, edit template.xml and comment out ” <!- unwanted register ->” or delete the registers you don’t want, then run make again and “m” will contain Words for only the registers you do want.
  • “make edit” opens template.xml in gvim
  • “make clean” deletes the four additional files created by “make”.

svd2forth-v2.tar.gz contents

  • Makefile
  • README.txt
  • STM32F0xx.svd (sample ARM svd file. You will need to use a SVD for your own MCU, but use this one to test if this all works for you)
  • mk.template.xsl
  • registers.xsl
  • svdcutter.xsl
  • svduf.xsl

Dependencies

  • make
  • xsltproc
  • sed
  • Optional: editor, I use gvim. Change it to your favorite editor in the Makefile

Instructions

  1. Untar svd2forth-v2.tar.gz to a directory

  2. run ‘make’ in this directory which will create the following four additional files. Note the size of “m” and “registers.text”

    1. “STM32F0xx.svd.uf.svd”

      STM32F0xx.svd that has been ‘unfolded’. ARM supply them in a ‘condensed’ form which means that identical registers have missing details.

    2. “m”
      The memory mapped Forth file you upload to your target. Initially contains ALL the registers in your MCU and may be too large to upload to your target, depending on Flash size. After template.xml is edited (see below) and make run again, the size of “m” will be drastically reduced.

      Words created in this file are:-

      • Register pretty print Words with bit field legends
    3. “registers.text”

      A register and bitfield programmer development reference file for registers selected in template.xml. Initially contains a list of ALL the registers in your ARM svd MCU file. After template.xml is edited (see below) and make run again, this file will only list the selected registers.

      Words created in this file are:-

      • lshift Words for writing bits to registers
      • Register Bitfield print Words
    4. template.xml

      Initially contains a list of ALL the registers in your ARM svd MCU file. You edit this file by either commenting out, or deleting lines of registers you DON’T want to use in your project.

  3. edit template.xml with ‘make edit’. Either comment out registers you don’t want by enclosing the line with “<- - register you don’t want - ->” or delete the entire line.

  4. run ‘make’ again, this will rebuild “m” and “registers.text” to reflect the uncommented registers in “template.xml”

  5. upload “m” to a STM32F0 Discovery board or chip depending on what you’re using. Typing ‘words’ in the serial terminal to your chip will show you the Words available.

  6. Use “registers.text” as a programming aid by opening it read only and copy/paste register configs to your forth program.

NOTES

  • MUST DO: edit the Makefile and replace “STM32F0xx.svd” with the ARM SVD file for your MCU (stm32XX.svd).
  • when you use your own stm32XX.svd, edit the xmlns:xs=”http://www.w3.org/2001/XMLSchema-instance” line to xmlns:xs=”stm32XX” or your template.xml file will be very cluttered
  • deleting template.xml and running “make” will recreate the full template.xml file

EXAMPLE

Here all but the “COMP” register (as it’s so simple) have been commented out in template.xml and “make” was run. The file “m” is then uploaded to the Mecrisp-Stellaris system MCU via your serial terminal

The following (non bold text) are terminal screendumps:-

words <enter>

— Flash Dictionary —
Address: 00004000 Link: 00004048 Flags: 00000000 Code: 00004010 Name: b32loop.
Address: 00004048 Link: 000040EC Flags: 00000000 Code: 00004052 Name: 1b.
Address: 000040EC Link: 00004148 Flags: 00000000 Code: 000040FA Name: b8loop.
Address: 00004148 Link: 0000419C Flags: 00000000 Code: 00004152 Name: 4b.
Address: 0000419C Link: 000041EC Flags: 00000000 Code: 000041AC Name: b16loop.
Address: 000041EC Link: 00004248 Flags: 00000000 Code: 000041F6 Name: 2b.
Address: 00004248 Link: 00004264 Flags: 00000040 Code: 00004254 Name: COMP
Address: 00004264 Link: 00004284 Flags: 00000040 Code: 00004274 Name: COMP_CSR
Address: 00004284 Link: FFFFFFFF Flags: 00000000 Code: 00004290 Name: COMP.

The word “comp.” lists the contents of the COMP_CSR register in the default one bit format (1b.)

comp. <enter>

COMP_CSR $00000000
3|3|2|2|2|2|2|2|2|2|2|2|1|1|1|1|1|1|1|1|1|1
1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
ok.

It can be displayed with different print formats:-

comp_csr 2b. <enter>

15|14|13|12|11|10|09|08|07|06|05|04|03|02|01|00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
comp_csr 4b. <enter>

07 06 05 04 03 02 01 00
0000 0000 0000 0000 0000 0000 0000 0000

Finally let’s read the registers.text file which shows how to set any of the bitfields in a copy/paste friendly way

# cat registers.text

######################### COMP ###########################
COMP_CSR (read-write)
$00000000 CONSTANT RESET_COMP_CSR
bit pos arg register name bitfield name bit width
: %1 0 lshift COMP_CSR bis! ; \ COMP_COMP1EN Bit 0 Width 1
: %1 1 lshift COMP_CSR bis! ; \ COMP_COMP1_INP_DAC Bit 1 Width 1
: %xx 2 lshift COMP_CSR bis! ; \ COMP_COMP1MODE Bit 2 Width 2
: %xxx 4 lshift COMP_CSR bis! ; \ COMP_COMP1INSEL Bit 4 Width 3
: %xxx 8 lshift COMP_CSR bis! ; \ COMP_COMP1OUTSEL Bit 8 Width 3
: %1 11 lshift COMP_CSR bis! ; \ COMP_COMP1POL Bit 11 Width 1
: %xx 12 lshift COMP_CSR bis! ; \ COMP_COMP1HYST Bit 12 Width 2
: %1 14 lshift COMP_CSR bis! ; \ COMP_COMP1OUT Bit 14 Width 1
: %1 15 lshift COMP_CSR bis! ; \ COMP_COMP1LOCK Bit 15 Width 1
: %1 16 lshift COMP_CSR bis! ; \ COMP_COMP2EN Bit 16 Width 1
: %xx 18 lshift COMP_CSR bis! ; \ COMP_COMP2MODE Bit 18 Width 2
: %xxx 20 lshift COMP_CSR bis! ; \ COMP_COMP2INSEL Bit 20 Width 3
: %1 23 lshift COMP_CSR bis! ; \ COMP_WNDWEN Bit 23 Width 1
: %xxx 24 lshift COMP_CSR bis! ; \ COMP_COMP2OUTSEL Bit 24 Width 3
: %1 27 lshift COMP_CSR bis! ; \ COMP_COMP2POL Bit 27 Width 1
: %xx 28 lshift COMP_CSR bis! ; \ COMP_COMP2HYST Bit 28 Width 2
: %1 30 lshift COMP_CSR bis! ; \ COMP_COMP2OUT Bit 30 Width 1
: %1 31 lshift COMP_CSR bis! ; \ COMP_COMP2LOCK Bit 31 Width 1

Bonus Words

Svd2Forth’s “m” (memory mapped Word file) also contains Register Print Words to display the register contents, for all registers enabled in ‘template.xml’. To print any register just add a ”.” after the name, i.e. GPIOA. or RCC. etc.

Assuming you have enabled GPIOA, the “GPIOA.” Word should be in your Dictionary and produce similar results to the Cortex M0 listing below. I have attempted to label and space the bitfields as per the actual STM documentation, but where a custom label has not been created, generic labelling applies.

gpioa.

 GPIOA_MODER (read-write) $000000A0
 15|14|13|12|11|10|09|08|07|06|05|04|03|02|01|00
 00 00 00 00 00 00 00 00 00 00 00 00 10 10 00 00

 GPIOA_OTYPER (read-write) $00000000
 1|1|1|1|1|1|
 5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

 GPIOA_OSPEEDR (read-write) $0C000000
 15|14|13|12|11|10|09|08|07|06|05|04|03|02|01|00
 00 00 11 00 00 00 00 00 00 00 00 00 00 00 00 00

 GPIOA_PUPDR (read-write) $242AAAA0
 15|14|13|12|11|10|09|08|07|06|05|04|03|02|01|00
 00 10 01 00 00 10 10 10 10 10 10 10 10 10 00 00

 GPIOA_IDR (read-only) $00002008
 1|1|1|1|1|1|
 5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0
 0 0 1 0 0 0 0 0 0 0 0 0 1 0 0 0

 GPIOA_ODR (read-write) $00000000
 1|1|1|1|1|1|
 5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

 GPIOA_BSRR (write-only) $00000000
 3|3|2|2|2|2|2|2|2|2|2|2|1|1|1|1|1|1|1|1|1|1|
 1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

 GPIOA_LCKR (read-write) $00000000
 3|3|2|2|2|2|2|2|2|2|2|2|1|1|1|1|1|1|1|1|1|1|
 1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

 GPIOA_AFRL (read-write) $00001100
  07   06   05   04   03   02   01   00
 0000 0000 0000 0000 0001 0001 0000 0000

 GPIOA_AFRH (read-write) $00000000
  15   14   13   12   11   10   09   08
 0000 0000 0000 0000 0000 0000 0000 0000

 GPIOA_BRR (write-only) $00000000
 3|3|2|2|2|2|2|2|2|2|2|2|1|1|1|1|1|1|1|1|1|1|
 1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0|9|8|7|6|5|4|3|2|1|0
 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

ok.