kilipili options - Megatokio/kilipili GitHub Wiki

kilipili defines some options in it's cmake files. Your IDE should allow you to change them without modifying the CMakeLists.txt files.

AUDIO_DEFAULT_SAMPLE_FREQUENCY 44100

The default sample frequency for audio output. The frequency can normally not be matched exactly but will approximated as close as possible. The sample frequency can be set at runtime with Audio::setSampleFrequency().

AUDIO_DMA_BUFFER_SIZE 256

Size of the DMA buffer used to supply the audio hardware, measured in number of audio frames (mono samples or stereo sample pairs). The default of 256 is good for roughly 5 msec. It can be reduced if you run out of memory or increased if you experience dropouts. The size must be a power of 2.

AUDIO_INPUT_BUFFER_ON_STACK OFF

The function which collects the audio from the registered audio sources, Audio::fillAudioBuffer(), uses a buffer which is normally allocated statically. This is done because the audio interrupt already allocates a lot of memory on the stack of core0 and you may experience stack overflows due to that.

If you don't use an interrupt but feed audio by calling Audio::fillAudioBuffer() e.g. as a function registered with the Dispatcher, or if you are short of memory and have a good feeling of the stack usage of your program, then you can save the statically allocated memory by setting AUDIO_INPUT_BUFFER_ON_STACK ON. You may possibly want to reduce the AUDIO_INPUT_BUFFER_SIZE in this case too.

AUDIO_INPUT_BUFFER_SIZE 64

Audio::fillAudioBuffer() uses a buffer to receive the audio from the registered audio sources, which is normally allocated statically or possibly on stack. The default size is 64 audio frames (mono samples or stereo sample pairs). You can reduce this size to save ram. The size does not need to be a power of 2. This also reduces the size of buffers used by some AudioSources.

DEVICES_LARGE_FILE_SUPPORT OFF

The file system normally uses 32 bit integers to address positions inside files which is sufficient for up to 4 GB. This flag can be set to ON to use 64 bit integers, if you ever need this.

FLASH_BLOCKDEVICE 300*1024

Set the default size of a BlockDevice in the program flash. This value is used if you format the QspiFlashDevice using Devices::makeFS("flash","FAT"). The size is stored in the Preferences, if not disabled, and the value from the Preferences is subsequently used in Devices::mount("flash"). If Preferences are disabled then FLASH_BLOCKDEVICE is used for mount() too.

The size of the flash blockdevice must be a multiple of the flash erase sector size which is 4 kB.
If Preferences are enabled then one erase sector is silently subtracted from the flash blockdevice size for the preferences.

The flash blockdevice normally survives reprogramming of the program flash unless it is overwritten by the program.

FLASH_PREFERENCES 4*1024

Set the memory allocated for preferences in flash. The default value is 1 flash erase sector which is 4 kB. The preferences are stored at the end of the flash. The preferences survive reprogramming of the program flash and may even be shared between different programs on the same pico.

The size must be a multiple of the flash erase sector size which is 4 kB.
Preferences may be disabled by setting FLASH_PREFERENCES 0. (not recommended)

MALLOC_EXTENDED_LOGGING OFF

The malloc replacement provided by lib kilipili provides some additional help for debugging. If MALLOC_EXTENDED_LOGGING is set to ON then malloc(), free() etc. log each incantation to stdout.

As malloc.cpp is not included directly by lib kilipili but must be included by your project directly (otherwise you may end up using two different malloc implementations in parallel), this flag is also not set by any kilipili cmake file.

You can set this flag by including the following lines in your CMakeLists.txt file:

add_compile_definitions(MALLOC_EXTENDED_LOGGING=1)

MALLOC_EXTENDED_VALIDATION OFF

When this flag is set to ON then malloc(), free() etc. do a more thorough checking of the linking of the chunks in the heap while stepping over them. This is only little cost but may help you find memory bugs earlier.

As malloc.cpp is not included directly by lib kilipili but must be included by your project directly (otherwise you may end up using two different malloc implementations in parallel), this flag is also not set by any kilipili cmake file. The default value if MALLOC_EXTENDED_VALIDATION is not set is ON for debug build and OFF for release.

You can set this flag by including the following lines in your CMakeLists.txt file:

add_compile_definitions(MALLOC_EXTENDED_VALIDATION=1)

FF_FS_TINY OFF

This flag is evaluated by the FatFS module. This sets whether the FatFS shall use the normal or the tiny implementation. tiny reduces the size of FatFiles but increases the number of sector reads and writes by the block device. Use this only if you run out of memory.

This flag is not set by any kilipili cmake file but you can set this flag by including the following lines in your CMakeLists.txt file before add_subdirectory(kilipili):

add_compile_definitions(FF_FS_TINY=1)

OPTION_MEMORY_ID ON

This controls whether some kilipili classes include a human readable name of up to 7 characters. This is a great help when looking at the memory dumps to figure out what went wrong or what is allocated in the middle of the heap preventing a successful malloc() of some size.

Set this to OFF if you don't need it and run really out of memory.

PICO_BOARD vgaboard

This is the normal SDK setting which defines your board. It is searched in pico-sdk/src/boards/include/boards/ and in the directory set with PICO_BOARD_HEADER_DIRS.

PICO_BOARD_HEADER_DIRS kilipili/boards

This is the normal SDK setting which defines an additional directory to search for board description header files. This is set to kilipili/boards and cached when cmake runs successfully. For the first cmake run you must either specify this explicitely or make a dummy run with PICO_BOARD=vgaboard or any other board you like.

PICO_STDIO_UART ON

This is the normal SDK setting for stdio to use the default UART and should be set to ON if you have defined a PICO_DEFAULT_UART in your boards header file.

PICO_STDIO_USB OFF

This is the normal SDK setting for stdio to use the default UART and should be set to OFF if you want to use the USB host mode. Else you can set it to ON to use USB for your stdio serial port.

USB_DEFAULT_KEYTABLE key_table_ger

This sets the default keyboard translation tables for keyboard input in USB host mode. Currently available are key_table_us and key_table_ger.

The keyboard translation table can be set at runtime with USB::setHidKeyTranslationTable().

USB_ENABLE_HOST ON

This enables the USB host mode to attach a keyboard and mouse.

USB_KEY_DELAY1 600
USB_KEY_DELAY 60

The USB::getChar() and USB::getKeyEvent() functions auto-repeat keys. These are the settings in ms for you to adjust.

VIDEO_INTERP0_MODE 5
VIDEO_INTERP1_MODE -1

The video output uses the interpolators of core1 in many display modes. Since the VideoController supports multiple overlapping buffers it is not possible to setup the interpolators once as required, but they must be setup per frame or even per scanline. These settings control optimization of the interpolator setups.

The default setting is to use interp0 for attribute mode with 1 bit per pixel and 8 pixel wide color attributes (A1W8) which is most frequently used in text modes and interp1 for all others. Therefore interp0 is only setup once per frame and interp1 is setup each scanline, if multiple buffers are positioned side-by-side possibly multiple times.

You may set the interpolators to the modes you actually use to save setup time allowing you to display configurations which are otherwise not stable.

It is possible to assign both interpolators to a fixed mode and then display a 3rd one, which just results in more setup time per scanline.

The possible modes are:

  -1:  any
   0:  1 bit per pixel
   1:  2 bit per pixel
   2:  4 bit per pixel
   3:  8 bit per pixel
   5:  2 bit per 2 pixels for A1W8 color attributes mode

VIDEO_MAX_SCANLINE_BUFFERS 16

Sets the maximum size of the array for prepared scanlines. This is normally also the maximum number of scanlines which can be rendered in advance, except for the low resolution double scanline modes 320x240, 400x300 and 512x384 which actually need two slots per scanline in this array. This array is an array of pointers only but it needs to be allocated aligned to it's size so you may waste some memory if setting it too high.

The actually used number of prepared scanlines is set in Video::startVideo().

The value must be a power of 2.

VIDEO_MAX_SYSCLOCK_MHz 290
The Video::startVideo() function sets the system clock to a frequency based on the passed setting and based on calculated requirements. This setting let's you adjust how high the system clock can be set. From my experiments 290 MHz is the general 'just still safe' value.

VIDEO_OPTIMISTIC_A1W8 OFF
The scanline render function for colormode a1w8 (truecolor attributes with 1 bit / pixel in the bitmap and 8 pixel wide attributes) can use a variant which optimizes based on the screen contents. This allows highest video resolution up to 1280*768 to be displayed in this mode. But if the screen contents becomes too colorful, then the video display will fail. (rolling screen contents displayed as the pixel supply can't catch up.) Because the test, whether a pixel octet can be optimized or not takes time, the overall time for the bad cases takes even longer than non-optimized. Specifically 1024*768 is also not guaranteed to display colorful contents properly, while 1024*768 can *just* be displayed without optimization regardless of the screen contents.

VIDEO_SUPPORT_200x150_A1W8 ON
VIDEO_SUPPORT_400x300_A1W8 ON
The scanline renderers are optimized for word-aligned access where possible. Especially the a1w8 mode (8 pixel wide true color attributes) is optimized to the max to make video resolution of 1024x768 in this mode possible. Unlucky enough, 400x300 is only half-word-aligned and 200x150 even has an odd line width measured in bytes. If you want to use these modes for low-res low-memory colorful content you can enable support for these modes. The major drawback is that this adds code to the very limited core1 stack area. Therefore set them to OFF if you don't need them. They are enabled by default just if someone doesn't read this. ;-)

TEMPMEM_SIZE0 1000
lib kilipili contains a cstring library which requires a tempmem pool for storing temporary strings, mostly results of string functions. On a desktop computer the pool grows indefinitely until the program decides to flush it. On a microcontroller this is not an option and a cyclic buffer is used instead and strings are overwritten when the allocation wraps around. If you decide to use the cstring library yourself or make otherwise heavy use of this feature you may want to increase this size. For kilipili itself 2k is already overkill.

This setting is not set by any kilipili CMakeLists.txt file but you may set it in your main cmake file before add_subdirectory(kilipili) like this:

add_compile_definitions(TEMPMEM_SIZE0=2000)

TEMPMEM_SIZE1 320
Same for core 1. Core 1 is dedicated for the video engine which currently uses cstrings just for logging only. If you run additional code on core1 or in the future then this size may need to be set to a higher value.

This setting is not set by any kilipili CMakeLists.txt file but you may set it in your main cmake file before add_subdirectory(kilipili) like this:

add_compile_definitions(TEMPMEM_SIZE1=200)