# mco_flashsim_open
RT

> Initialize and open a flash memory simulator instance using a memory device.

### Prototype

        MCO_RET mco_flashsim_open(
            /*IN*/  mco_device_t *memdev,
            /*IN*/  mco_flashsim_params_t *fsp,
            /*OUT*/ mco_flashsim_h *pfs
        );

### Arguments

`memdev`
Pointer to a memory device descriptor. The device must be of type compatible with the memory allocator (e.g., `MCO_MEMORY_CONV`).
`fsp`
Pointer to a `mco_flashsim_params_t` structure containing configuration parameters for the simulated flash device (page size, block layout, delays, error simulation, etc.).
`pfs`
Pointer to a variable that will receive the handle to the initialized flash simulator instance.

### Description

> This function initializes a flash memory simulator that emulates the behavior of real NAND/NOR flash devices, including erase-before-write semantics, bad block simulation, ECC errors, and programmable timing delays. It is primarily used for testing and development when physical flash hardware is unavailable.

> The simulator uses the provided memory device (`memdev`) to store its internal structures. If the device is not already initialized, the function creates and maps it automatically.

> Key features controlled by `mco_flashsim_params_t`:

> - Geometry: page size, pages per block, total blocks,
> - Timing: configurable delays for read, program, erase, and copy operations,
> - Error injection: probabilistic bad blocks and ECC errors,
> - Persistence: optional file-based image for saving/restoring flash content.

> If multiple calls are made with the same `memdev`, the simulator is opened in shared mode (reference-counted). The first call performs full initialization; subsequent calls return the existing instance.

> Note: The memory device must be large enough to hold all simulator data. Use `mco_flashsim_memory_size()` to calculate the required size.

### Return Codes

`MCO_S_OK`
Flash simulator successfully initialized or opened.
`MCO_E_ILLEGAL_PARAM`
Invalid parameter (e.g., non-power-of-two page size, insufficient memory device size, missing image filename for file-based mode).
`MCO_E_ILLEGAL_TYPE`
Memory device type is not supported.
`MCO_E_DISK_OPEN`
Failed to open or create the image file (in file-based mode).
`MCO_E_NOMEM`
Failed to allocate internal resources.

### Example

        mco_device_t dev;
        mco_flashsim_params_t params = {0};
        mco_flashsim_h fs;

        // Configure simulator parameters
        params.page_size = 4096;
        params.pages_per_block = 64;
        params.n_blocks = 1024;
        params.erase_delay = 2000;     // 2 ms
        params.prog_delay = 500;       // 0.5 ms
        params.bad_block_ratio = 1000; // 1 bad block per 1000 ops

        // Allocate memory device
        dev.assignment = MCO_MEMORY_ASSIGN_PERSISTENT;
        dev.type = MCO_MEMORY_CONV;
        dev.size = mco_flashsim_memory_size(&params);
        dev.dev.conv.ptr = (char*)malloc(dev.size);
        dev.dev.conv.flags = 0;

        // Open simulator
        MCO_RET rc = mco_flashsim_open(&dev, &params, &fs);
        if (rc == MCO_S_OK) {
            printf("Flash simulator ready\n");
        }

### Files

Header file:
mcoflashsim.h
Source file:
mcoflashsim.c
Library:
libmcoflashsim.a