plang-v2-stm32f051 README¶
Plang-V2 Process Flow¶
[STM32xxxx.svd]
\
> gema ---> cleaned.svd
/ \
svd_clean.pat > xsltproc ---> unfolded.svd
/
unfold-svd.xsl
memmap.xsl
\
> xsltproc --> memmap.pat
/ \
/ \
/ > gema --> project.source.memmap.fs
/ / \____________________________
unfolded.svd [forth-source-in.fs] -> \_ concatenate -> {forth-source-out.fs}
\ \___________________________ /
\ \_ gema -> project-source.bitfield.fs
\ source.pat _ /
\ \__ gema -> bitfield.pat
> xsltproc --> bitfield.data _/
/ \
/ \
bitfield.xsl \
\__ gema --> db.data --> sqlite3 --> {plang2.db}
/
db.pat
File Types¶
*.svd - ARM Cortex-M System View File
*.pat - Gemma ‘pattern’ file, used to supply search words when preprocessing input files
*.fs - Forth source file
plang2.db - For plangview database reader
Programs¶
Gema - text pre-processor
Xsltproc - XML *.xsl transformation program
sqlite3 - SQLite is a C-language library that implements a small, fast, self-contained, high-reliability, full-featured, SQL database engine.
Notes¶
[*] = input file
{*} = output file
forth-source-in.fs¶
Project Forth file created by programmer
\ reset RCC_CFGR_MCO bitfield
: reset ( -- )
%111 RCC_CFGR_MCO<< RCC_CFGR bic! \ Reset all bits of MCO clock selector
;
\ Reset all bits of the COMP_CSR_COMP1INSEL bitfield
%111 COMP_CSR_COMP1INSEL<< COMP_CSR bic!
\ Configure Comp 1
%11 COMP_CSR_COMP1MODE<< \ COMP1 INPUT MODE: %00 High speed / full power 10: Low speed / low-power
%001 COMP_CSR_COMP1INSEL<< \ COMP1 INPUT SELECT: %001 1/2 of VREFINT = 0.6095V
%100 COMP_CSR_COMP1OUTSEL<< \ COMP1 OUTPUT SELECT: %100: Timer 2 input capture 4
%10 COMP_CSR_COMP1HYST<< \ COMP1 HYSTERESIS: %10 Medium hysteresis
+ + + COMP_CSR bis!
forth-source-out.fs¶
Generated file to be uploaded to the MCU hosted Mecrisp-Stellaris Forth OS
: reset
%111 24 lshift $40021004 bic!
;
%111 4 lshift $4001001C bic!
%11 2 lshift
%001 4 lshift
%100 8 lshift
%10 12 lshift
+ + + $4001001C bis!
Plang¶
Is a pre-processor that accepts Forth source (and without altering it):
Strips all comments and blank lines
Swaps CMSIS-SVD Register Labels for absolute hexadecimal addresses
Swaps CMSIS-SVD Bitfield Labels for lshifts with BitPositions
Uploads the new terse source to the on-chip Forth compiler.
This allows the programmer to write readable and maintainable Forth source whist ensuring that what is uploaded to the MCU is only what the on-chip Forth compiler needs.
This process: 1. Maximises the limited flash/ram space available on STM32F0xx devices 2. Reduces serial upload times during project development
Downsides¶
Uploaded source is a different to the programmers source and may make decoding compiler warnings more difficult, tho this is not usually a issue with an experienced Forth user.
Denies the programmer the use of Register labels when performing interactive debugging. This is not usually a problem as higher level Words are being debugged anyway, but if it is a constant word can be made or the hex address can be used directly.
Plang Examples¶
Input¶
OUTPUT GPIOA_MODER_MODER12<< GPIOA_MODER BIS!
Output¶
%01 24 lshift $48000000 BIS!
Plangv¶
Plangv is a CLI Plang Database Reader providing easy to search methods for Registers and Bitfield data along with descriptions.
./plangv -p gpioa -b moder12 -T
name Stack Cmt ar bw bo description
------------------------------ ----------- -- -- -- -------------------------------------
GPIOA_MODER_MODER12<< ( bbb -- x) rw 2 24 Port x configuration bits (y =0..15)
Plang and Plangv allow easy design, maintenance and bugfixes of sourcecode.
Overall Actions¶
Register names are replaced with their absolute hexadecimal addresses
Style File |
Output |
|---|---|
memmap.xsl |
memmap.pat |
Bitfield names are replaced with their BitWidth and Offset values and the Lshift operator is added
Style File |
Output |
|---|---|
bitfield.xsl |
bitfield.pat |
One large source file is uploaded
Operation |
Description |
|---|---|
0x.pat |
remove all leading whitespace, linefeeds (0x0A). add “$” hex prefix |
project: |
cat $(PROJ_FILES) > $(PROJ_FILE) |
mem: |
$(GEMA)/gema -t -nobackup -line -match $(PROJ_FILE) -f $(SVD)memmap-label-gema.pat -out parse.memmap.fs |
bit: |
$(GEMA)/gema -t -nobackup -line -match $(PROJ_FILE) -f $(SVD)bitfields-gema.pat -out parse.bitfields.fs |
membit: |
$(GEMA)/gema -t -nobackup -line -match parse.bitfields.fs -f $(SVD)memmap-label-gema.pat -out parse.membit.fs |
cat: |
cat parse.memmap.fs parse.membit.fs parse.bitfields.fs | sort -u > intermediate.fs |
include: |
echo “includes.fs “ >> includes.fs |
include:1 |
echo “$(PROJECT).fs preprocessor generated dependencies “ >> includes.fs |
include:2 |
echo “compiletoram “ >> includes.fs |
include:3 |
cat intermediate.fs >> includes.fs |
include:4 |
echo “” >> includes.fs |
upload: |
includes.fs $(PROJ_FILE) |
upload:1 |
cat $(SYSTEM_FILE) includes.fs > final.fs |
upload:2 |
Desired Patterns¶
bitfields.pat¶
memmap-hex.pat¶
make all¶
Glossary¶
Stm32 micro¶
Swdcom¶
Cmsis-svd¶
Xslt 1.0¶
Transforms the Micro SVD XML into a form that
Gema¶
Parses source Register names into absolute hex addresses in the uploaded source file. i.e.
Memmaps¶
memmap.pat¶
Produced by memap.xsl for Gema and used to parse user Forth source (stage 1)
GPIOF_MODER=\$48001400
Bitfields¶
bitfield.xsl¶
produces bitfield.pat which is used by source.pat and db.pat
V1¶
GPIOF_MODER_MODER15\<\<=( INSERT INTO GPIOF VALUES ) : GPIOF_MODER_MODER15<< \ ( \%2 -- x ) \ 30 lshift \; \\ rw","2","30","Port x configuration bits (y = 0..15) @\n
V2¶
(planned)
[INSERT INTO GPIOF VALUES]GPIOF_MODER_MODER15\<\<=30 lshift! ( \%2 -- x ) \; \\ rw","2","30","Port x configuration bits (y = 0..15) @\n
source.pat¶
Processes the user Forth source to produce the uploaded source for the mcu hosted Mecrisp-Stellaris
GPIOF_MODER_MODER15\<\<=30 lshift
File Contents¶
bitfield.pat¶
Creates a pattern that contans data for creating the database and the source.pat files.
!CREATE TABLE GPIOF(
!name TEXT PRIMARY KEY NOT NULL,
!stack TEXT,
!word TEXT,
!access TEXT,
!bitwidth NUMERIC,
!bitoffset NUMERIC,
!description TEXT
!)\;
!INSERT INTO GPIOF VALUES(" General-purpose I/Os","-","-","-","-","-","-@\n
!INSERT INTO GPIOF VALUES(" GPIOF_MODER"," Reset Value $00000000","-","-","-","-","-@\n
INSERT INTO GPIOF VALUES("GPIOF_MODER_MODER15<<=30 lshift","( %2 -- x )","rw","2","30","Port x configuration bits (y = 0..15)") @\n
source.pat¶
\N INSERT INTO * VALUES=
("=
","*\n=\n
SQlite¶
db.data¶
V1¶
This SED script produces db.data which builds the Plang database
-rm bitfields.db
sed 's/=(/~/g' < $(BITFIELD_PAT) > $(BITFIELD_PAT).tmp
cut -d '~' -f 2 < $(BITFIELD_PAT).tmp > $(BITFIELD_PAT)1.tmp
sed 's/^ //g' < $(BITFIELD_PAT)1.tmp | sed 's/\\%/%/g' | sed 's/ \\;//g' | sed 's/)\\;/);/g' | sed 's/\\;/;/g' | sed 's/!\;/;/g' | sed 's/\\!/!/g' | sed 's/^!//g' | sed 's/ \\\\/\\ /g' | sed 's/ \\ / "," /g' | sed 's/) :/("/g' | sed 's/\\@/@ /g' | sed 's/@\\n/");/g' > $(DATABASE_DATA)
sqlite3 bitfields.db < $(DATABASE_DATA)
-rm $(BITFIELD_PAT).tmp
CREATE TABLE GPIOF(
name TEXT PRIMARY KEY NOT NULL,
stack TEXT,
word TEXT,
access TEXT,
bitwidth NUMERIC,
bitoffset NUMERIC,
description TEXT
);
INSERT INTO GPIOF VALUES(" General-purpose I/Os","-","-","-","-","-","-");
INSERT INTO GPIOF VALUES(" GPIOF_MODER"," Reset Value $00000000","-","-","-","-","-");
INSERT INTO GPIOF VALUES (" GPIOF_MODER_MODER15<< "," ( %2 -- x ) "," 30 lshift "," rw","2","30","Port x configuration bits (y = 0..15) ");
V2¶
db.pat produces db.data which builds the Plang database
(planned)
CREATE TABLE GPIOF(
name TEXT PRIMARY KEY NOT NULL,
stack TEXT,
word TEXT,
access TEXT,
bitwidth NUMERIC,
bitoffset NUMERIC,
description TEXT
);
INSERT INTO GPIOF VALUES(" General-purpose I/Os","-","-","-","-","-","-");
INSERT INTO GPIOF VALUES(" GPIOF_MODER"," Reset Value $00000000","-","-","-","-","-");
INSERT INTO GPIOF VALUES ("GPIOF_MODER_MODER15<<","( %2 -- x )"," 30 lshift","rw","2","30","Port x configuration bits (y = 0..15)");
Bourne Shell¶
Plangv¶
Operation¶
User Operations |
Description |
|---|---|
make svd2plang |
builds for the $project $mcu |
make dev |
compiles proven abd tested development utilities into flash |
make all |
clean project mem bit membit cat include upload |
make |
compiles new untested source into ram |
Processes¶
SVD --> XSLT --> Memmap.pat, Bitfields.pat
Forth Source --> [Gema <--Memmap.pat, Bitfields.pat] --> upload.fs
Once Memmap.pat, Bitfields.pat are stable then use Plangview to search Register and Bitfield names for source creation.
Memmap.pat, Bitfields.pat --> [SED or (later Gema)] --> plang.db
Plang.db --> Sqlite --> Plangview
Usage¶
make¶
builds builds everything that has changed
