# cpct_memset_f8

Fills up a complete array in memory setting bytes 2-by-2, in chuncks of 8 bytes. Size of the array must be multiple of 8.

#### C Definition

void cpct_memset_f8 (void* array, u16 value, u16 size);

#### Warning

- This function disables interrupts while operating and uses the stack pointer. Take it into account when you require interrupts or the stack pointer. When in doubt, use cpct_memset instead.
- At the end of the function, it reenables interrupts, no matter how they were before. Please, take into account.

#### Input Parameters (5 Bytes)

(2B HL) array | Pointer to the first byte of the array to be filled up (starting point in memory)
(2B DE) value | 16-bit value to be set (Pair of bytes)
(2B BC) size | Number of bytes to be set (>= 8, multiple of 8)

#### Assembly call (Input parameters on registers)

>     call cpct_memset_f8_asm

#### Parameter Restrictions

- array could theoretically be any 16-bit memory location. However, take into account that this function does no check at all, and you could mistakenly overwrite important parts of your program, the screen, the firmware... Use it with care.
- size must be greater than 7 and multiple of 8. It represents the size of the array, or the number of total bytes that will be set to the value. This function sets bytes 2-by-2, in chuncks of 8 bytes, so the minimum amount of bytes to be set is 8. Beware! sizes below 8 can cause this function to overwrite the entire memory.
- value could be any 16-bit value, without restrictions. It is considered as a pair of bytes that will be copied to every 2-bytes in the array.

#### Known limitations

- This function will not work from ROM, as it uses self-modifying code.

#### Details

Sets all pairs of bytes of an array in memory to the same given value. This is the same operation as std memset from standard C library, but with the added advantage of being faster and letting the user define the contents 16-bits-by-16-bits instead of 8. The technique used by this function is as follows:

1 | It saves the value of SP to recover it at the end of the function
2 | It places SP at the last 2-bytes of the array
3 | It uses PUSH instructions to set bytes 2-by-2, in chuncks of 8 bytes, until the entire array is set

This function works for array sizes from 8 to 65528. However, it is recommended that you use it for values much greater than 8. Depending on your code, using <cpct_memset_f> for values in the range [8-16] could underperform simple variable assignments.

#### Destroyed Register values

AF, BC, DE, HL

#### Required memory

C-binding | 46 bytes
ASM-binding | 41 bytes

#### Time Measures

>       Case      |   microSecs (us)  |     CPU Cycles         |
>     ----------------------------------------------------------
>        Any      | 53 + 20CH + 3CHHH | 212 + 80*CH + 12(CHHH) |
>     ----------------------------------------------------------
>     Asm saving  |      -16          |         -64            |
>     ----------------------------------------------------------

BC = array size (Number of total bytes to set) CH = BC \ 8 (number of chuncks, 1 chunck = 8 bytes) CHHH = CH \ 256 - 1 \ = integer division

Fills up a complete array in memory setting bytes 2-by-2, in chuncks of 8 bytes.
unsigned int (u16 = unsigned 16-bits, 2 bytes)
Fills up a complete byte-array in memory with a given 8-bit value (as std memset)
Close