4.3 Memory Allocation

FreeWPC does not use dynamic (heap) memory allocation, except in some very rare circumstances. All variables should be declared global, or put on the stack.

Global variables cannot be statically initialized. Variables should be initialized explicitly inside a C function.

Global variables can be divided into a number of categories, depending on their usage. Normal globals are always in scope and behave as you would expect. Additionally, you can tag a global with one of the following attributes:

__fastram__

Used for variables that are used frequently. GCC6809 will generate faster code when accessing these. However, you are limited to about 250 bytes of fastram variables total. These are mostly used by RTTs for performance.

Do not use fastram unless you are working in the core system, or writing a device driver that runs more than once every 4ms or so.

The performance gain is just 1 CPU cycle faster and 1 fewer byte of code per read or write access.

__permanent__

Used for variables that should be persistent across reboots. These variables should be initialized inside of a factory_reset event, because factory reset should restore everything to a sane state. GCC6809 places these variables at an address that is not automatically cleaned by the startup code during the memory test.

The init or init_complete handlers should test these values for sanity, since they may become corrupted due to software bugs. If this is detected, they should be restored to sane values for non-fatal cases if possible, otherwise a factory reset should be forced.

__nvram__

Like __permanent__, but for variables that are also write-protected by default. To modify such a variable, you must first call pinio_nvram_unlock(), change it, and then call pinio_nvram_lock(). This helps to ensure that certain critical variables are not accidentally corrupted.

Do not sleep while inside the critical section. Do not nest calls to these functions either.

This feature makes use of special hardware in the WPC ASIC.

Adjustments and audits kept in NVRAM are managed via special APIs which do the locking/unlocking for you.

This feature works even in native mode; the __nvram__ variables are saved to a file when you exit the program.

__local__

Used for variables that are maintained separately for different players in a multiplayer game. The system software will transparently reload these variables with the correct values whenever the player up changes. These variables should be initialized inside of a start_player event.

There is a limit to how many locals can be declared; if you exceed this, you will get a linker error.