Implement std::mem::memcopy procedure

CHANGELOG.md

@@ -4,6 +4,9 @@
 
 #### Enhancements
 
+- Added new `memcopy_felts` procedure for the `std::mem` module. ([#2352](https://github.com/0xMiden/miden-vm/pull/2352)).
+- Added new `memcopy` procedure for the `std::mem` module. ([#2361](https://github.com/0xMiden/miden-vm/pull/2361)).
+
 #### Changes
 
 - Added missing implementations of `proptest::Arbitrary` for non-`BasicBlockNode` variants of `MastNode` ([#2335](https://github.com/0xMiden/miden-vm/pull/2335)).

docs/src/user_docs/stdlib/mem.md

@@ -6,10 +6,12 @@ sidebar_position: 6
 # Memory procedures
 Module `std::mem` contains a set of utility procedures for working with random access memory.
 
-| Procedure   | Description   |
-| ----------- | ------------- |
-| memcopy_words | Copies `n` words from `read_ptr` to `write_ptr`.<br /><br />`read_ptr` and `write_ptr` *must be* word-aligned.<br /><br />Stack transition looks as follows:<br />[n, read_ptr, write_ptr, ...] -> [...]<br />cycles: 15 + 16n<br /> |
-| pipe_double_words_to_memory | Copies an even number of words from the advice_stack to memory.<br /><br />Input: [C, B, A, write_ptr, end_ptr, ...]<br />Output: [C, B, A, write_ptr, ...]<br /><br />Where:<br />- The words C, B, and A are the RPO hasher state<br />- A is the capacity<br />- C,B are the rate portion of the state<br />- The value `words = end_ptr - write_ptr` must be positive and a multiple of 8<br /><br />Cycles: 9 + 6 * word_pairs<br /> |
-| pipe_words_to_memory | Copies an arbitrary number of words from the advice stack to memory<br /><br />Input: [num_words, write_ptr, ...]<br />Output: [C, B, A, write_ptr', ...]<br />Cycles:<br />even num_words: 43 + 9 * num_words / 2<br />odd num_words: 60 + 9 * round_down(num_words / 2)<br /> |
-| pipe_preimage_to_memory | Moves an arbitrary number of words from the advice stack to memory and asserts it matches the commitment.<br /><br />Input: [num_words, write_ptr, COM, ...]<br />Output: [write_ptr', ...]<br />Cycles:<br />even num_words: 62 + 9 * num_words / 2<br />odd num_words: 79 + 9 * round_down(num_words / 2)<br /> |
-| pipe_double_words_preimage_to_memory | Moves an even number of words from the advice stack to memory and asserts it matches the commitment.<br /><br />Input: [num_words, write_ptr, COM, ...]<br />Output: [write_ptr', ...]<br /><br />Cycles: 56 + 3 * num_words / 2<br /> |
+| Procedure                              | Description   |
+| -------------------------------------- | ------------- |
+| `memcopy`                              | Copies `n` felts from `read_ptr` to `write_ptr`.<br/><br/>If possible, this procedure will copy word-aligned words internally using `memcopy_words` procedure, decreasing the total number of cycles required to make a copy.<br/><br/>It is advised to copy small chunks of memory using `memcopy_felts` procedure instead, since it won't have a computation logic overhead.<br/><br/>**Inputs:** `[n, read_ptr, write_ptr]`<br/>**Outputs:** `[]`<br/><br/>Total cycles:<ul><li>Read and write pointers are mutually unaligned: $23 + 14 * num\_felts$</li><li>Read and write pointers are mutually aligned: $66 + 14 * num\_prefix\_felts + 16 * num\_words + 14 * num\_suffix\_felts$</li></ul> |
+| `memcopy_words`                        | Copies `n` words from `read_ptr` to `write_ptr`.<br/><br/>`read_ptr` and `write_ptr` pointers *must be* word-aligned.<br/><br/>**Inputs:** `[n, read_ptr, write_ptr]`<br/>**Outputs:** `[]`<br/><br/>Total cycles: $15 + 16 * num\_words$ |
+| `memcopy_felts`                        | Copies `n` felts from `read_ptr` to `write_ptr`.<br/><br/>It is advised to copy big chunks of memory using `memcopy` procedure instead, since it will handle the memory more efficiently.<br/><br/>**Inputs:** `[n, read_ptr, write_ptr]`<br/>**Outputs:** `[]`<br/><br/>Total cycles: $7 + 14 * num\_felts$ |
+| `pipe_double_words_to_memory`          | Copies an even number of words from the advice_stack to memory.<br/><br/>**Inputs:** `[C, B, A, write_ptr, end_ptr]`<br/>**Outputs:** `[C, B, A, write_ptr]`<br/><br/>Notice that the `end_ptr - write_ptr` value must be positive and a multiple of 8.<br/><br/>Total cycles: $9 + 6 * num\_word\_pairs$ |
+| `pipe_words_to_memory`                 | Copies an arbitrary number of words from the advice stack to memory.<br/><br/>**Inputs:** `[num_words, write_ptr]`<br/>**Outputs:** `[C, B, A, write_ptr']`<br/><br/>Total cycles:<ul><li>Even `num_words`: $43 + 9 * num\_words / 2$</li><li>Odd `num_words`: $60 + 9 * round\_down(num\_words / 2)$</li></ul> |
+| `pipe_preimage_to_memory`              | Moves an arbitrary number of words from the advice stack to memory and asserts it matches the commitment.<br/><br/>**Inputs:** `[num_words, write_ptr, COMMITMENT]`<br/>**Outputs:** `[write_ptr']`<br/><br/>Total cycles:<ul><li>Even `num_words`: $62 + 9 * num\_words / 2$</li><li>Odd `num_words`: $79 + 9 * round\_down(num\_words / 2)$</li></ul> |
+| `pipe_double_words_preimage_to_memory` | Moves an even number of words from the advice stack to memory and asserts it matches the commitment.<br/><br/>**Inputs:** `[num_words, write_ptr, COMMITMENT]`<br/>**Outputs:** `[write_ptr']`<br/><br/>Total cycles: $56 + 3 * num\_words / 2$ |