plang-v2-stm32f051 README¶
Project: plang-v2-stm32f051
Created: Wed 21 Sep 2022 20:31:14 AEST
Author Copyright 2022 by t.j.porter <terry@tjporter.com.au>
Purpose:
Intended Audience
MCU:
Board:
Core:
Required:
Recommended:
Critical:
Based on:
References:
plang-v2-stm32f051 URL:
license: MIT, please see COPYING
Description¶
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
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 [project-source.fs] -> \_ concatenate -> parsed.source.fs
\ \___________________________ /
\ \_ gema -> project-source.bitfield.fs
\ source.pat _ /
\ \__ gema -> bitfield.pat
> xsltproc --> bitfield.data _/
/ \
/ \
bitfield.xsl \
\__ gema --> db.data --> sqlite3 --> plang2.db --> plangview (database reader)
/
db.pat
parsed.source.fs -> [Upload to Forth Mcu]
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
