Provide documentation and options for memory allocation

[lloydjatkinson]

Context

I was not able to find any documentation about what allocation modes DeviceScript supports, eg static or dynamic, or if it allows usage of a custom allocator. This is a very nuanced topic in embedded systems, where use of malloc() can be restricted, not available, or even dangerous. This includes the use of garbage collectors.

Further reading:

• How to Allocate Dynamic Memory Safely
• Why are you not supposed to use malloc/calloc in embedded systems programming?

For collections (such as array) one strategy is to have a bounded (fixed size) array. In the embedded Rust space, there are crates available such as heapless which contains fixed size implementations of the collections found in the runtime library. Another alternative is to provide a custom allocator. Both options are discussed below.

Further reading:

The Embedded Rust Book - Collections.

Finally, another example would be FreeRTOS's approach to memory management. It provides several heaps the developer can choose from at build time.

heap_1 - the very simplest, does not permit memory to be freed.
heap_2 - permits memory to be freed, but does not coalescence adjacent free blocks.
heap_3 - simply wraps the standard malloc() and free() for thread safety.
heap_4 - coalescences adjacent free blocks to avoid fragmentation. Includes absolute address placement option.
heap_5 - as per heap_4, with the ability to span the heap across multiple non-adjacent memory areas.
https://www.freertos.org/a00111.html

DeviceScript

Although I see that there is some mention of conserving memory in the docs on buffers:

Buffers can be dynamically allocated, read and written. This can be used to conserve memory (regular variables always take 8 bytes) and create arrays (with fixed upper limit).

There are still no guarantees about the runtime, with comments such as this:

devicescript/runtime/devicescript/objects.c

Line 521 in 9f83802

// it may allocate an object for the tuple, but typically it doesn't

This leaves a few questions about safety and guarantees for embedded scenarios.

• The description says "brings a professional TypeScript developer experience to low-resource microcontroller-based devices." but unless these considerations are factored in then it doesn't really help with the professional goal. I tried to rephrase that a few times, I'm not trying to sound rude! 😄
• What happens in OOM situations?
• What guarantees, if any, are in place to prevent an OOM in the first place?
• Will a custom allocator feature be included (like embedded Rust and FreeRTOS), or are fixed size collections to be emphasised more through use of buffer? Buffers are not likely to be a newcomers first choice unless they have prior embedded experience.
• Currently with all of these questions and unknowns, DeviceScript is not a sufficiently safe language/ecosystem for many embedded systems.

[pelikhan]

@mmoskal

[mmoskal]

Excellent question!

I assume you're asking about using a DeviceScript runtime, not porting the runtime to a different MCU.

First, a qualifier - the "professional" refers to the TypeScript developers and experience, and we will definitely not cover all professional uses of embedded systems, now done in C, C++ or Rust (let alone assembly). However, we think that there are many scenarios where using an ESP32 or RP2040 in place even of an 8-bit chip is cost-effective, due to the costs of developing software. Simple (though not necessarily 8-bit-simple!) embedded scenarios are DeviceScript sweet spot.

In other words, our focus is to enable TypeScript developers to do embedded stuff that no-one did before, because it was not cost-effective, and not so much to enable embedded developers to do their current projects more efficiently.

The DeviceScript code generally allocates freely, as expected by (non-embedded) TypeScript developers. The DeviceScript runtime uses a precise garbage collector (GC). The GC is currently non-compacting, though that may be fixed in future, see issue #255. When the program runs out of memory, it is terminated and restarted (after a few seconds). Similarly, the program is restarted upon an unhandled exception (though we plan to allow overriding that). Note, that in either case the device is not restarted, only the user program, and the exception may be reported via the cloud connection.

We do not plan to allow any more precise control over memory allocation, though we may provide better ways of monitoring usage.

I hope this helps!