Shell memory layout

Since QNICE does not offer a dynamic memory management system, the Shell uses a hard-coded memory layout to perform its duties. This memory layout seeks a balance between three conflicting goals:

1. When using the Shell's "File Browser" to browse for files (such as games, programs, ROMs, cartridges, etc.): Display as many files and subfolders within a given folder as possible. The memory is needed for displaying the directory entries in an alphabetically ordered fashion.
2. When browsing through deeply structured libraries of files, make sure that the file browser remembers all the subfolders so that as soon as you start to "climb up" the directory-tree again (i.e. leave a subdirectory) the file-browser continues where you left off.
3. Have an On Screen Menu with as many menu items and sub-menus as possible.

You can configure the memory layout in m2m-rom.asm. Go to the section that is called Heap and Stack and locate the following constants:

Constant	Meaning
MENU_HEAP_SIZE	Amount of heap reserved for the On Screen Menu, i.e. above-mentioned case (3). This memory amount includes the sum of all characters of all menu and sub-menu items, including buffers for replacing the %s in certain menu items. Since it is hard to guess the correct value for MENU_HEAP_SIZE, the M2M framework outputs valuable debug information on the serial debug console (see below) when you press the Help key for the first time.
HEAP_SIZE	Amount of memory reserved for the above-mentioned case (1): All file- and directory names in the current directory, alphabetically sorted. If your core uses disk images, CRT/ROM images and similar items that need a file browser: Try to maximize this value.
STACK_SIZE	Overall stack size. System stack = Overall stack size minus B_STACK_SIZE. Needs to be at least 768 words.
B_STACK_SIZE	Stack used for case (2), i.e. for remembering the sub-folder "climbing path" that a user went but also for replacing filenames that are too long by a shortened filename that ends with .... For this string replacement an amount of words that equals the maximum screen width is needed plus zero terminator. Additionally B_STACK_SIZE needs 2+<maximum recursive folder climbing depth> words.

Here is an example log out from the "C64 for MEGA65" core version 5:

Maximum available QNICE memory: 31994
  Used as general heap:         28544
  Used as menu heap:            1664
  Used as stack:                1536
    Used as general stack:      768
    Used as browser stack:      768
  Free QNICE memory:            250
Free space in QNICE ROM:        5631
OSM heap utilization:
  MENU_HEAP_SIZE:               1664
  Free menu heap space:         260
  OPTM_HEAP_SIZE:               260
  Free OPTM heap space:         17

The value "Free OPTM heap space" is an indicator for you how you need to size MENU_HEAP_SIZE. If this value starts to shrink towards zero due to you adding more menu items to config.vhd it is time to increase MENU_HEAP_SIZE in m2m-rom.asm. When doing so, make sure that you are decreasing either HEAP_SIZE or STACK_SIZE (or both) by the same absolute value that you are increasing MENU_HEAP_SIZE. Also make sure that you adjust the comments in m2m-rom.asm to match your new values; otherwise you or the reader of your source will be confused later.