Even more STM8L support

New Features

This release will be about STM8L devices (i.e. the likes of STM8L051F3, STM8L151R6 or STM8L162R8).

While STM8S peripherals are simple and the pin and clock configuration is trivial, the STML designers clearly had both many more, and much larger, spec sheets. Many more one can clearly see in the number of configuration dependencies one has to infer when configuring one of the many features of the peripherals. For STM8 eForth this means that some things that were implicit or hard-coded need to be reviewed and restructured, and tested.

This pre-release also (finally) adds support for low-end RM0013 STM8L devices like STM8L101.

Until the release, high-end devices, like the High Density STM8L152R8 should be tested (at least initially, see issue #359).

Changes so far

@frantony
STM8L-DISCOVERY: enable UART output
1f6a8e2

@TG9541
fixes #331 start of 2.2.26 development cycle
5713b7c

@TG9541
fixes #330 Move EEPROMBASE from forth.asm to target.inc
2ceb70d

@TG9541
fixes #334 STM8S207: use UART3
a9e1b61

@TG9541
#295 extended memory access with FC@ and FC!
911d4ae

@TG9541
fixes #336: factored solution for BF! abd LEBF! using B!
5abf97e

@TG9541
fixes #337: FC! and FC@ added
a83bd6b

@TG9541
fixes #339 make EEALIAS compatible with STM8L
40d0156

@TG9541
fixes #340 STM8L interrupt priority of BG task
symbols for interrupt number

@TG9541
fixes #342 improve STM8L efr files

@TG9541
fixes #344 STM8L: fix interrupt number naming error

@TG9541
#346 Add COMPONLY to the library

@TG9541
#349 Add support for STM8L101 and STM8L001

@TG9541
#350 Support ELF target for OpenOCD / stm8-gdb

@TG9541
#353 Add BTJT/ BTJF spin loop enhancement

@TG9541
#354 Add STM8L151K4 board support for RM0031 STM8L Medium Density Devices enhancement

@TG9541
#355 Export constant PAGESIZE to indicate the size of a Flash page enhancement

@TG9541
#356 STM8L101F3: improve target.inc and docs Documentation

Improving STM8L support

Superseded by 2.2.26.pre3

2.2.26.pre1: Merge pull request #343 from TG9541/Pre1.2.2.26

Deprecated - please use 2.2.26.pre2 or later

A bit too fast!

New features

A bug-fix and an extra.

Buffered RX with INTRX

Buffered RX, e.g. using INTRX, speeds up the console quite a bit: STM8 eForth can feel really snappy if it's not slowed down by a 9600 baud console interface.

An important use case for buffered RX is interactive applications with background or idle task execution times that exceed a console char time (about 1ms at 9600 baud). A discussion is in this HaD log.

STM8 UART register addresses and names depend on the device. STM8 eForth works around this by providing a default UART, but selecting the device is still necessary:

\ select the generic STM8S controller first

\ alternatively specify STM8S103, STM8S105 or STM8S207
\res MCU: STM8S103

\ load (or define) device independent constants
\res export INT_UARTRX UART_DR UART_CR2

\ define the UART buffer length
8 CONSTANT RBLEN

\ then load the controller independent code
#require INTRX

\ put it to work
#require WIPE
#require :NVM
#require OSCFREQ
#require UART_DIV
#require UARTBRR

NVM
  'BOOT ( xt )
  :NVM
    INTRX
    ( xt ) LITERAL EXECUTE
  ;NVM 'BOOT !

  \ calculate UART_DIV settings for 3840*10 = 38400 baud @ CPU clock rate
  3840 OSCFREQ UART_DIV UARTBRR !
WIPE RAM

\ make it survive a RESET command
#require PERSIST
PERSIST

This code can be placed in {BOARD}/board.fs} and needs to be executed only once. The baud rate can be set using UART_DIV - of course the terminal program (e.g. e4thcom) needs to be set to the matching baud rate, here 38400 baud.

For example, compiling and executing the 66 lines tree traversal demo with e4thcom shows the following transfer time at different baud rates:

baud	RAM	NVM
9600	2s	4s
115200	1s	2s

The faster console interface can do nothing about the time needed for compilation, especially to Flash memory, but interactive words like WORDS or DUMP feel really fast.

Bug Fix

The reason for this release is #328 - 2.2.24 was long in the making bit the release was a bit too fast.

The bug was introduce when the background timer reload value BGTIMREL was exposed as an "NVM parameter" (see table here). Doing that is now no longer possible.

@Eelkhoorn proposed setting the background task rate in the application init:

  \ change the background task rate to 0.36s:
  7 TIM2_PSCR C! $AFC8 TIM2_ARRH 2C!

This procedure also allows setting the pre-scaler.

Has it really been a year?

New features

Target builds in downstream projects

Adding more boards to STM8 eForth is nice but creating new GitHub repositories for applications, while keeping the core lean, is better.

A new feature supports downstream projects with "target boards": a STM8 eForth release archive contains all source code required for a target build and the Makefile was split in two parts, one with the overal configuration (Makefile), the other for building a board folder (forth.mk).

The release archives are still much smaller since the post-linker list file forth.rst, formerly used by symload.sh, has moved to the release archive stm8ef-rst.tgz. It will only be needed if you'd like to know what exactly went into a binary condiguration.

Support for projects that separate generic from hardware dependent code comes from issue #298: by changing the search order for Forth code in simload.py hardware target folders can used as the "configuration root" that provides initialization and abstractions for multiple targets ({BOARD}/board.fs now comes first, main.fs is second).

Here are some of the GitHub projects that use the new method:

GitHub Project	Notes
STM8 eForth Modular Build	template repository and cookbook in one
stm8ef-modbus	the project targeting the C0135 that first required this feature
W1209 Data-Logging Thermostat	a solution for the still growing number of W1209 variants
XY-LPWM	timers and 7S-LED code
stm8l051led	simulated serial interface and other things for STM8L

Refer to #272 for details.

Move more out of the Core

#282, #285 and #289 make the STM8 eForth Core leaner: the idea is to move more potentially board specific code to include files so that it can be "overwritten" by adding a specific solution to a board folder.

An example is the specialized sser_fdx.inc in stm8l051led which works around a one-sided inverter in a serial link.

Configurable Timer for Background Task

Since introduction of the background task almost 4 years ago it was limited to TIM2. The issues #304 and #305 changed that.

It's now possible to use BG_USE_TIM1 = 1 or BG_USE_TIM3 = 1 in globconf.inc to select TIM1 or TIM3 instead of TIM2. So far the code only works on STM8S.

There is currently no support for STM8L (what's at least missing is configuration of the clock tree for TIM3 and support for TIM1).

Priority feature for EEALIAS using "un-link tags"

With #265 tagging un-linked dictionary entries was introduced. #263 cleaned up old feature selection options. Both contribute to building the aliaslist.fs file in the target folder so that they can be loaded into the EEPROM with the EEALIAS feature.

With this method (#266) up to half a KiB of Flash memory an be saved compared with a STM8 eForth binary that has the same feature set. This is particularly useful for tweaking memory usage in downstream projects.

Improved support for STM8S Low Density Devices with UART remapping

Certain STM8S Low Density Devices (i.e. STM8S001J3, STM8S903 and certain STM8AF devices) have a UART remapping feature: the UART can be mapped to PA3/PF4 instead of the usual PD5/PD6.

#288 and #290 makes sure that by setting HALF_DUPLEX = 2 in globconf.inc the init code in COLD check OPT2 for STM8S "Low Density Device UART remapping" to set either PA_CR1 or PD_CR1.

Improved Support for STM8S High Density Devices

High density devices had a number of feature gaps:

• #292 required a solution for using the 2nd UART - this is now possible by setting USE_UART2 = 1 in globconf.inc.
• #298 also adds Forth stack primitives (rp@, rp!, sp! and sp@).
• #293 fixes a bug that broke simulated console port with TIM4

Future releases will add more support for High Density devices, e.g. access of Far memory for data storage.

Better UART support

Work on STM8EF-MODBUS created some need for non-console use cases of the UART. #302, #303, core exports like OSCFREQ or library words like UART_DIV.

#320 introduces a baud rate parameter for codeload.py.

While the console works fine and feels snappy at 115200 baud, using background tasks can be a challenge (at 9600 baud the background task can take up to 1ms but). A spin-off was code for "buffered RX" (INTRX). This is surprisingly simple and it works very well. The code will be added to the library in the next release.

Better support for the simulated serial interface

The following changes address the simulated serial interface:

• #293 the simulated interface compatible with STM8S High Density devides, and
• #319 did the same for STM8L devices
• #305 adds support for Port E.

There are now configuration parameters for setting the baud rate of the simulated serial interface: TIM4_ARR and TIM4_PSCR.

The following table shows parameter values for a range of baud rates:

Rate	CTIM4ARR	CTIM4PSCR	sser-fdx	sser-hdx
600	7	0xCF	yes*	yes*
1200	6	0xCF	yes*	yes*
2400	5	0xCF	yes*	yes*
4800	4	0xCF	yes	yes
9600	3	0xCF	yes	yes
19200	2	0xCF	yes	yes
38400	1	0xCF	yes	yes
57600	1	0x89	(yes)	yes
115200	0	0x89	no	(yes)

*) untested but very likely to work - due to a 4 bit pre-scaler index STM8L devices can also use 300, 150, 75 downto 2.34375 baud - maybe that's useful for communication using a flashlight ;-)

Full-duplex at 115200 baud was too much for the combined TIM4 Rx/Tx state machine, and it stopped working. 115200 with half-duplex worked fine (using the new "-r" option of codeload.py, see #320) but I didn't test it with e4thcom since the baud rate in version 0.8.0.64 appears to be limited to 57600.

To be on the safe side it's best to limit the simulated serial in full-duplex to 38400 baud and in half-duplex to 57600 baud. It might also be necessary to introduce tuning for the HSI or using a crystal.

More core information export in target

Some use-cases, e.g. writing code that extends the core, requires knowledge of internal constants, variables or CALL targets. Certain improvements togenconst.awk enable export of information from annotated RAM allocation, constant definitions and targets (e.g. #311, $316, #317, #323 and #326).

The following table shows names exported from STM8 eForth 2.2.24 on:

Word in target	type	notes
'?BGKEY	NVM xt-parameter	xt of ?KEY for BG task
'BGEMIT	NVM xt-parameter	xt of EMIT for BG task
PC_?UNIQUE	NVM patch target	patch target for CURRENT
PC_BOARDINIT	NVM patch target	patch target for board initialization
PC_LEDMPX	NVM patch target	patch target for 7S-LED multiplex
PC_NAME?	NVM patch target	patch target for CURRENT
PC_WORDS	NVM patch target	patch target for CURRENT
BGPAD	NVM parameter	address of the empty PAD for BG task
BGSPP	NVM parameter	address of the empty data stack for BG task
BGTIMREL	NVM parameter	timer reload value for BG task
ISPP	NVM parameter	address of the empty data stack for interrupt task
SPP	NVM parameter	address of the main data stack
TIB	NVM parameter	address of Terminal Input Buffer (TIB)
UARTBRR	NVM parameter	UART baud rate generator value (see UART_DIV)
C_BSPP	constant	address of the empty data stack for BG task
C_ISPP	constant	address of the empty data stack for interrupt task
C_RPP	constant	address of the return stack
C_SPP	constant	address of the main data stack
C_TIB	constant	address of Terminal Input Buffer (TIB)
C_UPP	constant	offset of UPP user area
OSCFREQ	constant	clock frequency in kHz as defined in target.inc
KEYREPET	RamByte	key repetition counter for board keys
LED7FIRST	RamBlck	buffer for 7S LED/LCD patterns
OUT	RamWord	register for board output
TIM4RXBUF	RamByte	RX buffer from simulated serial interface
TIM4RXREG	RamByte	RX shift register of sim. serial interface
TIM4TCNT	RamByte	sequence counter of simulated serial interface
TIM4TXREG	RamByte	TX shift register of sim. serial interface
TOKEN_$,n	ALIAS	patch target for CURRENT
aborq	ALIAS	runtime word for ABORT" (renamed from abort")

Note that "parameters" point to locations in NVM (Flash memory) that can be changed as needed. That's especially useful for changing I/O words for background tasks by writing to '?BGKEY and 'BGEMIT.

Abstraction of peripheral addresses in the core

Across the STM8S family, the reference manual RM0016 describes peripherals such as GPIOs, timers, UARTS, I2C, SSC, ADC, watchdog timers and control of interrupt or control. Variants of these peripherals are often described in great detail, and the variants are given names such as USART, UART1, UART2, UART3, UART4 or even USART and LINUART. Sometimes the same peripheral has a different name in the datasheet of commercial/industrial and automotive grades of the same chip.

It turns out that subsets of peripheral register addresses are almost always the same. Almost. Timers TIM2 and TIM4 have the same register names in LD (Low Density) as in MD (Medium Density) and HD (High Density) devices but the addresses differ a bit.

UART irregularities are of a different kind: there are two sets of address and interrupt vectors, let's call them 1st UART and 2nd UART. An "LD" device has a 1st UART, "MD" a 2nd UART and "HD" has both of them.

For writing device independent low-level code some workarounds can be used:

• provide a symbol file that contains a shared functiona...

2.2.24.pre4: Merge pull request #303 from TG9541/bits

Still experimental

Refer to #302 and #304.

Towards improved modularity

New features

Target builds in downstream projects

An experimental feature allows downstream projects building new "target boards" using only STM8 eForth "release archives". To enable this all source code that's necessary for a target build is now contained in the release archive, and the Makefile is now more modular (see forth.mk).

Additionally, the forth.rst post-linker list file, previously used by symload.sh, has been moved into an independent release archive (stm8ef-rst.tgz).

#298 changed the simload precedence for Forth code: {BOARD}/board.fs now comes first, main.fs is second. Maybe that's not the best solution for all use cases but it solves the problem of loading "board code" first.

Refer to #272 for details.

Move more out of the Core

#282, #285 and #289 make the STM8 eForth Core leaner: the idea is to move more potentially board specific code to include files so that it can be "overwritten" by adding a specific solution to a board folder.

Priority feature for EEALIAS using "un-link tags"

With #265 tagging un-linked dictionary entries was introduced. #263 cleaned up old feature selection options. Both contribute to building the aliaslist.fs file in the target folder so that they can be loaded into the EEPROM with the EEALIAS feature.

With this method up to half a KiB of Flash memory an be saved compared with a STM8 eForth binary that has the same feature set.

Improved Support for STM8S High Density Devices

• #298 also adds Forth stack primitives (rp@, rp!, sp! and sp@) - maybe this will be the default also for Medium Density devices.
• #293 fixes a bug that broke simulated console port with TIM4

Note: the final release will also provide a solution for #292.

Yet another W1209 Variant

#277 adds support for the W1209 CA V2. Please refer to the docs in the board folder.

Other changes

• #281 makes the behavior of 'IDLE similar to BG: setting it to 0 stops Idle Task execution
• #299 adds ]BCPL for direct bit complement (like ]B! etc.)

Bug Fixes

• #270 fixes the Rx GPIO CR1 settings if the simulated UART doesn't use PD1 (SWIM)
• #279 fixed GPIO settings for the STM8L-Discovery board
• #300 fixes a bug in genconst.awk which broke features like 'IDLE and which was on master for about 5 weeks - fortunately release 2.2.24.pre1 was unaffected and 2.2.24.pre2 only lasted for hours.

superseded by 2.2.24.pre3

Please don't use this one - refer to issue #300.

superseded by 2.2.24.pre2

2.2.24.pre1

fixes #272 Deliver forth.asm and other source files in release archive

Improvements and Maintenance

New features

ADC support for STM8L devices

In #227 and #229 @Eelkhoorn provided ADC! and ADC@ for STM8L devices (e.g. STM8L051)

New bit addressing words

The following new words make efficiernt bit manipulation/testing easier, assembly programming often unnecessary:

• [ address bit# ]B? read bit from memory to flag on stack (contributed by Manfred Mahlow)
• [ address bit# ]BC copy C flag to memory bit
• [ address bit# ]CB copy bit from memory address to C flag

The bit-banging DS1302 RTC code in stm8ef/XH-M194/board.fs is an example for mixing machine code with Forth for fast and compact code.

New assembly interface words

Since STM8 eForth compiles to machine code, injecting assembly instructions into Forth code is very easy. Since many Forth words keep the value of the last Top of the Stack (TOS) in either the STM8 register Y (16 bit) or A (8 bit) accessing these registers in assembly is often a shortcut to interfacing Forth from assembly.

The following interface words can be added with #require:

word	action
>A	pull 8bit value from stack to register A
A@	read word from zero-page RAM address in A and push to stack
A>	push 8bit value in register A to stack
>Y	pull 16bit value from stack to register Y
Y@	read word from address in Y and push to stack
Y>	push 16bit value in register Y to stack

More kernel constants exposed

Issue #243 improved the export of target dependent kernel constants, and introduced some new ones that are all available in the target folder:

$0064 CONSTANT BASE    \  "BASE" radix base for numeric I/O
$0040 CONSTANT BGADDR  \  address of background routine (0: off)
$0350 CONSTANT BSPP    \  "BSPP" Background data stack, growing down
$007E CONSTANT BUFFER  \  "BUFFER" address, defaults to TIBB
$0076 CONSTANT CONTEXT \  "CONTEXT" start vocabulary search
$006A CONSTANT CP      \  "CP" point to top of dictionary
$0070 CONSTANT CTOP    \  "CTOP" point to the start of RAM dictionary
$0060 CONSTANT 'EMIT   \  "'EMIT" execution vector of EMIT
$0078 CONSTANT 'EVAL   \  "'EVAL" execution vector of EVAL
$0044 CONSTANT HLD     \  "HLD" hold a pointer of output string
$0066 CONSTANT 'IDLE   \  "'IDLE" idle routine in KEY (default: RET)
$007C CONSTANT >IN     \  ">IN" hold parsing pointer
$0330 CONSTANT ISPP    \  "ISPP" Interrupt data stack, growing down
$0062 CONSTANT '?KEY   \  "'?KEY" execution vector of QKEY
$006C CONSTANT LAST    \  "LAST" currently last name in dictionary
$3E80 CONSTANT OSCFREQ \  "OSCFREQ" oscillator frequency in kHz
$0068 CONSTANT 'PROMPT \  "'PROMPT" point to prompt word (default .OK)
$03FF CONSTANT RPP     \  "RPP"  return stack, growing down
$0320 CONSTANT SPP     \  "SPP"  data stack, growing down (with SPP-1 first)
$0350 CONSTANT TIB     \  "TIB"  Term. Input Buf. TIBLENGTH between SPPLOC and RPP
$007A CONSTANT #TIB    \  "#TIB" count in terminal input buffer
$0042 CONSTANT TICKCNT \  16 bit ticker (counts up)
$0060 CONSTANT UPP     \  "UPP"  offset user area
$0072 CONSTANT VAR     \  "VAR" point to next free USR RAM location
$0046 CONSTANT YTEMP   \  extra working register for core words

Hints:

• these internal variables and constants can be accessed with #require when using e4thcom or codeload.py
• variable addresses in the range 0x0040 .. 0x005F, stack location etc. depend on the target
• variable addresses in the range 0x0060 .. 0x007F are target independent and change rarely

Tool improvements and bug-fixes

Continuous integration environment updated

The Docker driven CI environment now uses SDCC 3.8.6 including an improved version of uCsim (see #235 ).

Alias export improvements

• #237 improved genalias.awk: there won't be aliases for headers that contain a NOALIAS tag (exposing code like dodoes only clutters the target/ folder).

More make targets

make can now fetch the STM8 target device name from <BOARD>/target.inc. New device dependent targets are defaults, readflash, readeeprom, and readopt.

Please note that the for some devices (e.g. STM8S207, STM8L) the opt defaults file in the /tools folder is still missing.

AWK issues fixed

• @zcsahok provided a fix (43dcd7f) for binary and() in recent versions of gawk
• #197 fixes use POSIX awk, don't rely on linux script processor path

Changes to simload.sh

• Merge pull request #252 from bademux/tool_dump2ihx_script (this replaces the AWK script with a much nicer python script)

• fixes #235 sstm8 dump format update: simload.sh fix for DOCKER-SDCC:V3.8.4 (2nd take)

Documentation improvements

VOC Examples added

With #130 Manfred Mahlow's VOC example for I2C was added. VOC and word list extensions were added in #241, and they have finally found their way into the Wiki.

More example code

Besides lots of Wiki edits and new pages, #233 brings some docs improvements in the source repository (e.g.
info for the STM8S001J3, example code in lib/ words improved).