Document memory layout in polkavm

[nazar-pc]

There are a few APIs in polkavm related to memory, but as it stands right now, it is hard to understand the full picture.

On one hand this is an embedded target with no global allocator available in Rust target, on the other hand there is instance.heap_size() and I'm not sure what it corresponds to exactly.

polkatool disassemble has "Stack size" in it, so my guess it is fixed at link time and heap is growing on top of it (potentially dynamically)?

There is also instance.set_accessible_aux_size(), but even after looking at MemoryMap and seeing some additional details it is not clear what it is and how it is used.

I have more questions, but probably stop there. What I think would be valuable is to have some visualization and description of different memory sections.

For context I was trying to understand how to correctly write some data structure into VM's memory, then making a function call with a pointer to that data structure, write result into another data structure and then reading it back. I was also thinking about making host calls with some data and getting response back before resuming execution, which is a similar mechanism, but the other way around.

Since all of that is very unsafe, it is really important to understand exactly how things work to do it properly. I understand that I can probably call sbrk (which interestingly only supports unsigned integers, so not clear how to reliably not leak memory without a lot of bookkeeping) and write something there, but it gets more complex with return data, etc.

Documenting here would be helpful, but ideally integrated into the Rust docs.

[athei]

On one hand this is an embedded target with no global allocator available in Rust target, on the other hand there is instance.heap_size() and I'm not sure what it corresponds to exactly.

alloc is available for that target. You just need to provide a memory allocator of your choosing. That allocator could use the sbrk instruction to request some memory from th3 VM which it can operate on. You could also just run it on a buffer inside the rw segment.

polkatool disassemble has "Stack size" in it, so my guess it is fixed at link time and heap is growing on top of it (potentially dynamically)?

Yes the module declares its minimum stack size in a special section: https://docs.rs/polkavm-derive/latest/polkavm_derive/macro.min_stack_size.html

Since all of that is very unsafe, it is really important to understand exactly how things work to do it properly. I understand that I can probably call sbrk (which interestingly only supports unsigned integers, so not clear how to reliably not leak memory without a lot of bookkeeping) and write something there, but it gets more complex with return data, etc.

Yes you can use sbrk for that. The memory allocator should be in the PolkaVM module. It would also be responsible for freeing memory. Thats how you prevent memory leaks.

[nazar-pc]

alloc is available for that target. You just need to provide a memory allocator of your choosing.

I know, I specifically meant that global allocator is not set by default in contrast to some other targets.

Yes the module declares its minimum stack size in a special section: https://docs.rs/polkavm-derive/latest/polkavm_derive/macro.min_stack_size.html

Does "minimum" mean it can be increased somehow? That is the kind of details I'm missing (might be some common knowledge too, I'm just familiarizing myself with this level of abstraction).

That allocator could use the sbrk instruction to request some memory from th3 VM which it can operate on. You could also just run it on a buffer inside the rw segment

What does rw segment contain? I used simplealloc from the repo for some basic experiments, which used static memory, I guess that is one part of rw segment alongside stack and heap?

Visualization like this would be helpful:

[ all memory                                         ]
[ ro memory         ][ rw memory                     ]
[ code ][ static ro ][ static rw ][ stack ][ heap -> ]

Where -> means growable with sbrk (if dynamic paging is enabled from my understanding so far, otherwise amount of memory available is set during instantiation).

Yes you can use sbrk for that. The memory allocator should be in the PolkaVM module. It would also be responsible for freeing memory. Thats how you prevent memory leaks.

I see, makes sense. But I can still allocate something with sbrk before calling into the instance and it will be right between stack and heap in the above visualization, am I correct?