Consideration about SYS and the first pages of flash ROM
========================================================

Now, I'm developing something like SYS for Kinetis L MCU, so, I write
this document.


About SYS on STM32F103
======================

In the development of Gnuk, we developed:

	SYS: The system predefined routines for STM32F103

It is now maintained as example-cdc/sys.c.

There is another version in example-led/sys.c, which also support
STM32F030, as well as STM32F103.  But, it wouldn't be useful for
STM32F030.  In fact, the file example-fsm-55/sys.c has name sys.c
but it doesn't include any system routines.

The original issue was:

    (1) When it's protected, STM32F103 can't change the first 4KiB of
        flash ROM at run time.

    (2) We want to support firmware upgrade through its USB.

Later on, we add another point.

    (3) It is good if the executable of Gnuk could be shared among
        different boards.

For (1) and (2), we decided put some useful routines and data which is
not need to be changed.

Now, the first 4KiB of flash ROM consists of:

     1KiB: SYS
     3KiB: 3/4 of AES forward tables

SYS consists of:

  Internal: reset entry, end of RAM
  Data: board identification
  Routines: board specific
            board independent

and here is the list of all.

* Internal routines

  reset entry
  end of RAM

* Board identification

  sys_version
  sys_board_id
  sys_board_name

* Board specific routines

  * led
    set_led

  * mcu/board lower level
    clock_init
    gpio_init

  * usb
    usb_lld_sys_init
    usb_lld_sys_shutdown

* Board independent routines

  * flash ROM access routines

    unlock
    write halfword
    erase page
    brank check
    write page
    protect
    erase_all & exec to ram

  * system reset routine

    nvic_system_reset

The routines of clock_init and gpio_init are here because of some
historical reasons.  (We could design a system with no such exported
routines: by defining: those things done internally after reset and
before calling the application.)

Those are exported as entries of SYS, and it is the responsibility of
the application which do initialize clock and GPIO, calling those
routines.

USB routines are needed because of hardware practice of STM32F103.
With STM32F103, each board has different way for handling the pull up
of USB D+ and how the device asks re-enumeration to host PC.  In my
opinion, if it's defined as full speed device and it's OK for us not
to use high impedance (but asserting to LOW, instead) of D+ to ask
re-enumeration, we can just pull up D+ always.  And we wouldn't need
such routines in SYS.



About SYS on Kinetis L
======================

For Kinetis L, because it's ROM has the original firmware upgrade
support by the vendor (though USB HID), all that we needed for
firmware upgrade would be just erasing to factory settings.

And it has no limitation like STM32F103's first 4KiB flash ROM.
All pages can be updated at run time.

Nevertheless, the first two pages (2KiB) of KL27Z is still difficult
to use.

So, I decide to introduce something like SYS for Kinetis L.


* Layout

Three pages (3KiB) usage:

  ------------ The first page
  End of RAM <-- not used but hardware define this
  Address of reset entry
  sys_version
  sys_board_info (id, name)
  sys_vector
  

  SYS...

  ------------ The second page
  FLASH CONFIG: 16-byte
  Reset entry function
  CRC-32 routine
  CRC-32 table (768-byte of CRC-32 table)

  ------------ The third page
  MAGIC 256-byte (256-byte of the last part of CRC-32 table)
  ...
  vectors (MSP, reset, ...) 
  ...


* data: Board identification

  sys_version
  sys_board_id
  sys_board_name ; null terminated

* Board specific routines

  * mcu/board lower level
    clock_init
    gpio_init

  * led
    set_led

* data: Board independent routines

  * flash ROM access code to be loaded on to RAM

* system reset routine???

    nvic_system_reset


* data: vectors for routines and data
  sys_version
  sys_board_id
  address of set_led
  address of clock_init 
  address of gpio_init 
  address of sys_board_name
  address of ...



--