# Flash Simulator Configuration

> The simulator is configured using the `mco_flashsim_params_t` structure, defined in `include/mcoflashsim.h`:

>         typedef struct {
>             size_t                      page_size;       /* page size in bytes */
>             mco_xflash_page_t           pages_per_block; /* number of pages in erase block */
>             mco_xflash_block_t          n_blocks;        /* total number of blocks */
>             timer_unit                  erase_delay;     /* time to perform block erase (microseconds) */
>             timer_unit                  read_delay;      /* time to read a page (microseconds) */
>             timer_unit                  prog_delay;      /* time to program a page (microseconds) */
>             timer_unit                  copy_delay;      /* time to copy back a page (microseconds) */
>             mco_bool                    realtime_delays; /* wait for specified delays */
>             mco_bool                    file_based;      /* store flash content only in image file */
>             mco_bool                    managed;         /* simulate MANAGED flash media (e.g. SD card) */
>             unsigned int                random_seed;     /* seed for random number generator */
>             unsigned int                bad_block_ratio; /* inject bad block error every bad_block_ratio operations */
>             unsigned int                ecc_error_ratio; /* inject ECC error every ecc_error_ratio read operations */
>             char const                 *image_filename;  /* Name of file to save/load the flash content */
>         } mco_flashsim_params_t;

> The pointer to this structure is passed into `mco_flashsim_open()`.

> 1. The first three fields define the geometry of the emulated device.
> 2. `erase_delay`, `read_delay`, `prog_delay`, and `copy_delay` simulate the execution time of basic I/O operations on flash memory.
> 3. `realtime_delays`
>    - If set to `MCO_YES`, the simulator enforces real-time execution delays using a simple busy loop. This ensures that applications take the same time to execute in the simulator as they would on actual hardware.
>    - If set to `MCO_NO`, the simulator only accounts for elapsed I/O time without enforcing delays.
> 4. `random_seed`: The simulator is capable of generating random errors in erase/prog operations (see `bad_block_ratio` below). The generator seed can be defined via `random_seed`.
> 5. `bad_block_ratio`: When set to a value greater than 0, the simulator injects an `MCO_E_DISK_BAD_BLOCK` error during write-type operations - specifically `prog` (page program), `erase` (block erase), and `copy` (page copy). After every `(bad_block_ratio - 1)` successful write operations, the next such operation will fail with this error.
> 6. `ecc_error_ratio`: Controls the frequency of simulated ECC (error-correcting code) errors during read-type operations - specifically `read` and `copy` (since copy involves reading source data). After every `(ecc_error_ratio - 1)` successful read operations, the next read (or read phase of a copy) will return an `MCO_E_DISK_CRC_MISMATCH` error.
> 7. `image_filename` is specifies the file used to persist the flash contents.
> 8. `managed` indicates whether the simulator should emulate managed flash media (e.g., an SD card or eMMC). If set to `MCO_YES`, the simulator relaxes the erase-before-write requirement: pages can be programmed without first erasing their block. This mimics the behavior of managed flash devices that handle wear leveling and bad-block management internally. Note that image save/load functionality (via `image_filename`) remains active regardless of this setting - it is not disabled in managed mode.