mco_flashsim_open

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:

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