mbr/application-ReadMe.text

   1 Multiple applications in flash
   2 ==============================
   3
   4 Some brief notes about mbr, menu, hello, *-test and *-loader
   5
   6
   7 1. Each application must: #include "application.h"
   8 2. Link with:             application.lds
   9 3. Do not add eeprom.o to list of objects as this is supplied by mbr
  10    (the vector is defined in application.lds)
  11    (still have to include "eeprom.h" though)
  12 4. Makefile has a MAKE_APP macro to simplify the rules
  13 5. application.c must start and end with special macros
  14    and also define a title.  (see below)
  15
  16
  17 example: hello application:
  18 ===========================
  19
  20 ************** start of hello.c **************
  21
  22 #define APPLICATION_TITLE "hello world"
  23
  24 #include "application.h"
  25
  26
  27 // main() must be first as the loader executes from the first program address
  28 int main(void)
  29 {
  30         APPLICATION_INITIALISE();
  31
  32         print("hello world\n");
  33
  34         print(" 1 + 2 = ");
  35         print_u32(1 + 2);
  36         print_char('\n');
  37
  38         print("goodbye world\n");
  39
  40         APPLICATION_FINALISE(0);
  41 }
  42
  43 ************** end of hello.c **************
  44
  45
  46 The makefile must contain this line:
  47     $(call MAKE_APP, hello, misc.o)
  48
  49 i.e part of the makefile contains:
  50 ==================================
  51
  52 ************** section of Makefile **************
  53
  54 # Applications
  55
  56 $(call MAKE_APP, menu, misc.o)
  57 $(call MAKE_APP, hello, misc.o)
  58 $(call MAKE_APP, memory-test, misc.o)
  59
  60 ************** end of section of Makefile **************
  61
  62
  63
  64 Boot sequence for 8kByte applications
  65 =====================================
  66
  67 1. internal ROM load mbr from FLASH @ 0 to RAM @ 0
  68 2. ROM jumps to RAM @ 0
  69 3. mbr reads flash from ((block << 13) + 0x300) to ram @ 0x200
  70    where block is initially zero
  71 4. mbr call code at RAM 0x200
  72 5. if this code returns the the block = return code
  73 6. back to step 3
  74
  75 Missing is argument value that is initially zero and gets the high 16
  76 bits of the return value which then gets passed as a parameter to the
  77 next program.
  78
  79
  80 The boot menu program
  81 =====================
  82
  83 This is just like any other application program and does the following.
  84
  85 It scans the first 4 bytes of each 8kByte flash block looking for
  86 "SAMO" if there is a match then a letter from A..G is output followed
  87 by upto 32 bytes of text from block offset 4 (this is derived from
  88 APPLICATION_TITLE in the .c file.
  89
  90 Finally it waits fo a key press then return 1..7 to the mbr to load
  91 another program.
  92
  93 The purpose is to select between various programs such as the elf file
  94 loader, memory-test, etc. which are part of the initial load sequence
  95 or testing.  Some of these (e.g. memory test) cannot run from SDRAM
  96 since the SDRAM is completely overwritten by the process and may not
  97 even work.
  98
  99 The second reason is that it is not possible to fit all of the
 100 required code into a single 8kByte program, hence the need to "chain"
 101 between different programs.  (an ancient technique from pre-history
 102 when computers came with basic in ROM)
 103
 104 (Missing: There ought to ba a way for the menu program to determine
 105 the flash size)
 106
 107
 108 Ordering the programs (example mapfile)
 109 =======================================
 110
 111 mbr is located at 0x1
 112 menu at 0x300
 113 application headers are located at 0xN000
 114 and their code at 0xN300.
 115 (where n is an even digit)
 116
 117 ************** start of mapfile **************
 118 # samo_a1.map
 119 # FLASH = PM25LV512
 120 # SIZE  = 64kB
 121
 122 0x1     mbr
 123 0x0300  menu
 124
 125 0x2000  kernel-loader.header
 126 0x2300  kernel-loader
 127
 128 0x4000  forth-loader.header
 129 0x4300  forth-loader
 130
 131 0x6000  hello.header
 132 0x6300  hello
 133
 134 0x8000  key-test.header
 135 0x8300  key-test
 136
 137 0xa000  memory-test.header
 138 0xa300  memory-test
 139
 140 #0xc000  <other>.header
 141 #0xc300  <other>
 142
 143 #0xe000 gfxtool/failed_boot.p
 144
 145 ************** end of mapfile **************