.. index:: vim,Bram Moolenaar,bitfields,include files,cmsis-svd,svd2forth,embedded configuration,peripherals .. _vim: VIM === By Bram Moolenaar: https://moolenaar.net/vim.html .. _vim-codecompletion-bitfields: **Using Vim completion to easily insert bitfield configuration template Words into your Forth programs.** .. seealso:: :ref:`BITFIELDS, DECLARE EARLY ?` Svd2forth --------- :ref:`svd2forth` derives output from ARM *CMSIS-SVD* files and transforms them using *XSLT*. In one fast operation :ref:`svd2forth` produces a number of files for the chosen STM32Xxxxx MCU. The file we are interested in here is named *bitfields.fs* and contains complete configuration *templates* for the hardware in your MCU. Why would you want them ? .. note:: Bitfields.fs can be likened to the *Include files* used by The C Programming Language, but bitfields.fs also contains the description field plus the Stack Picture. Bitfields.fs ------------ This is a small sample of the bitfields.fs file produced for the STM32F051 MCU. This segment contains the MODE configuration *template* Words for GPIOC, BITs 0 - 15. See the :download:`Technical Manual`, page 148/1004 for General-purpose I/Os (GPIO) information. :: \ GPIOC_MODER (read-write) Reset:0x00000000 : GPIOC_MODER_MODER15 ( %bb -- x addr ) 30 lshift GPIOC_MODER ; \ GPIOC_MODER_MODER15, Port x configuration bits y = 0..15 : GPIOC_MODER_MODER14 ( %bb -- x addr ) 28 lshift GPIOC_MODER ; \ GPIOC_MODER_MODER14, Port x configuration bits y = 0..15 : GPIOC_MODER_MODER13 ( %bb -- x addr ) 26 lshift GPIOC_MODER ; \ GPIOC_MODER_MODER13, Port x configuration bits y = 0..15 : GPIOC_MODER_MODER12 ( %bb -- x addr ) 24 lshift GPIOC_MODER ; \ GPIOC_MODER_MODER12, Port x configuration bits y = 0..15 : GPIOC_MODER_MODER11 ( %bb -- x addr ) 22 lshift GPIOC_MODER ; \ GPIOC_MODER_MODER11, Port x configuration bits y = 0..15 : GPIOC_MODER_MODER10 ( %bb -- x addr ) 20 lshift GPIOC_MODER ; \ GPIOC_MODER_MODER10, Port x configuration bits y = 0..15 : GPIOC_MODER_MODER9 ( %bb -- x addr ) 18 lshift GPIOC_MODER ; \ GPIOC_MODER_MODER9, Port x configuration bits y = 0..15 : GPIOC_MODER_MODER8 ( %bb -- x addr ) 16 lshift GPIOC_MODER ; \ GPIOC_MODER_MODER8, Port x configuration bits y = 0..15 : GPIOC_MODER_MODER7 ( %bb -- x addr ) 14 lshift GPIOC_MODER ; \ GPIOC_MODER_MODER7, Port x configuration bits y = 0..15 : GPIOC_MODER_MODER6 ( %bb -- x addr ) 12 lshift GPIOC_MODER ; \ GPIOC_MODER_MODER6, Port x configuration bits y = 0..15 : GPIOC_MODER_MODER5 ( %bb -- x addr ) 10 lshift GPIOC_MODER ; \ GPIOC_MODER_MODER5, Port x configuration bits y = 0..15 : GPIOC_MODER_MODER4 ( %bb -- x addr ) 8 lshift GPIOC_MODER ; \ GPIOC_MODER_MODER4, Port x configuration bits y = 0..15 : GPIOC_MODER_MODER3 ( %bb -- x addr ) 6 lshift GPIOC_MODER ; \ GPIOC_MODER_MODER3, Port x configuration bits y = 0..15 : GPIOC_MODER_MODER2 ( %bb -- x addr ) 4 lshift GPIOC_MODER ; \ GPIOC_MODER_MODER2, Port x configuration bits y = 0..15 : GPIOC_MODER_MODER1 ( %bb -- x addr ) 2 lshift GPIOC_MODER ; \ GPIOC_MODER_MODER1, Port x configuration bits y = 0..15 : GPIOC_MODER_MODER0 ( %bb -- x addr ) GPIOC_MODER ; \ GPIOC_MODER_MODER0, Port x configuration bits y = 0..15 GPIOC_MODER_MODER8 Breakdown ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ====================================== ============================================================================================================= Syntax Description ====================================== ============================================================================================================= : Definition start GPIOC_MODER_MODER8 Definition Name: Peripheral_Register_Bitfield transformed from :ref:`CMSIS-SVD` ( %bb -- x addr ) Stack Picture; %bb means it expects two bits as input parameters. X = some number, addr = a 32 bit address 16 decimal number = 16 lshift shift left, 16 bits in this case GPIOC_MODER 32 bit address constant defined in memmap.fs. GPIOC_MODER = $48000800 ; Definition completion \ GPIOC_MODER_MODER8 Definition name repeated in comments Port x configuration bits y = 0..15 Description Field, transformed from :ref:`CMSIS-SVD` ====================================== ============================================================================================================= A brief code example ^^^^^^^^^^^^^^^^^^^^ This is code from "f0-disco-leds.fs. It is uploaded to a :ref:`STM32F0 Discovery Board` running Mecrisp-Stellaris and "leds-init" is then executed. After that the on-board blue and green leds may be controlled by Words such as "green-on" etc. :: %00 constant INPUT %01 constant OUTPUT %10 constant AF %11 constant ANALOG : bit ( u -- u ) 1 swap lshift1-foldable ; \ turn a bit position into a binary number. : GPIOC_MODER_MODER8 ( %bb -- x addr ) 16 lshift GPIOC_MODER ; \ GPIOC_MODER_MODER8 : GPIOC_MODER_MODER9 ( %bb -- x addr ) 18 lshift GPIOC_MODER ; \ GPIOC_MODER_MODER9 : GPIOC_BSRR_BS9 ( -- ) 9 bit GPIOC_BSRR ! ; \ GPIOC_BSRR_BS9 : GPIOC_BSRR_BR9 ( -- ) 25 bit GPIOC_BSRR ! ; \ GPIOC_BSRR_BR9 : GPIOC_BSRR_BS8 ( -- ) 8 bit GPIOC_BSRR ! ; \ GPIOC_BSRR_BS8 : GPIOC_BSRR_BR8 ( -- ) 24 bit GPIOC_BSRR ! ; \ GPIOC_BSRR_BR8 : leds-init ( -- ) output GPIOC_MODER_MODER8 bis! output GPIOC_MODER_MODER9 bis! ; : green-on ( -- ) GPIOC_BSRR_BS9 ; \ green led on : green-off ( -- ) GPIOC_BSRR_BR9 ; \ green led off : blue-on ( -- ) GPIOC_BSRR_BS8 ; \ blue led on : blue-off ( -- ) GPIOC_BSRR_BR8 ; \ blue led off Summary ------- * bitfields.fs contains all the Forth bitfield configuration templates for your STM32Xxxx MCU * each bitfield can be pasted into your code and used in your program as above. * this method shows the hardware AND software operation in a way that can be read and understood decades later. I wrote about why I prefer this method :ref:`here`. Inserting a bitfield template into your code -------------------------------------------- There are two ways that I know of, the easy way and the hard way. The Hard Way ^^^^^^^^^^^^ Have multiple files open, (easy with a tabbed editor) then copy and paste from bitfields.fs into your program. The Easy Way ^^^^^^^^^^^^ Use a capable editor that can search all opened files from your program and insert the template you want. Vim Completion -------------- Vim offers many *completion* options and one is described here. Whole Line Completion ^^^^^^^^^^^^^^^^^^^^^ While writing f0-disco-leds.fs I enter (in insert mode): :: GPIOC_MODER ^ cursor is here x, l select GPIOC_MODER_MODER8 from the pink coloured pop up window. When I hit the enter key the line is then pasted into my program. I have found this to be a fast and easy method to locate and insert the bitfield templates needed. .. image:: pics/vim/vim-whole-line-completion.jpg Vimrc ----- Some notes on what your ~/.vimrc requires for this to work. These are taken from my ~/.vimrc. Note there are probably a hundred ways to do this. :: " Omni completion CTRL-X CTRL-O set omnifunc=syntaxcomplete#Complete " The default value is .,w,b,u,t,i " .: The current buffer " w: Buffers in other windows " b: Other loaded buffers " u: Unloaded buffers " t: Tags " i: Included files set complete=b