/// \param managed  Pointer to a ManagedNandFlash instance.
/// \param block  Number of block to allocate.
//------------------------------------------------------------------------------
unsigned char ManagedNandFlash_AllocateBlock(
    struct ManagedNandFlash *managed,
    unsigned short block)
{
    trace_LOG(INFO, "ManagedNandFlash_AllocateBlock(%d)\n\r", block);

    // Check that block is FREE
    if (managed->blockStatuses[block].status != NandBlockStatus_FREE) {

        trace_LOG(trace_ERROR, "ManagedNandFlash_AllocateBlock: Block must be FREE\n\r");
        return NandCommon_ERROR_WRONGSTATUS;
    }

    // Change block status to LIVE
    managed->blockStatuses[block].status = NandBlockStatus_LIVE;
    return WriteBlockStatus(managed, block);
}

//------------------------------------------------------------------------------
/// Releases a LIVE block of a nandflash and marks it as DIRTY.
/// Returns 0 if successful; otherwise returns NandCommon_ERROR_WRONGSTATUS if
/// the block is not LIVE, or a RawNandFlash_WritePage error.
/// \param managed  Pointer to a ManagedNandFlash instance.
/// \param block  Number of block to release.
//------------------------------------------------------------------------------
unsigned char ManagedNandFlash_ReleaseBlock(
    struct ManagedNandFlash *managed,
    unsigned short block)
{
    trace_LOG(INFO, "ManagedNandFlash_ReleaseBlock(%d)\n\r", block);

    // Check that block is LIVE
    if (managed->blockStatuses[block].status != NandBlockStatus_LIVE) {

        trace_LOG(trace_ERROR, "ManagedNandFlash_ReleaseBlock: Block must be LIVE\n\r");
        return NandCommon_ERROR_WRONGSTATUS;
    }

    // Change block status to DIRTY
    managed->blockStatuses[block].status = NandBlockStatus_DIRTY;
    return WriteBlockStatus(managed, block);
}

//------------------------------------------------------------------------------
/// Erases a DIRTY block of a managed NandFlash.
/// Returns the RawNandFlash_EraseBlock code or NandCommon_ERROR_WRONGSTATUS.
/// \param managed  Pointer to a ManagedNandFlash instance.
/// \param block  Number of block to erase.
//------------------------------------------------------------------------------
unsigned char ManagedNandFlash_EraseBlock(
    struct ManagedNandFlash *managed,
    unsigned short block)
{
    unsigned char error;

    trace_LOG(INFO, "ManagedNandFlash_EraseBlock(%d)\n\r", block);

    // Check block status
    if (managed->blockStatuses[block].status != NandBlockStatus_DIRTY) {

        trace_LOG(trace_ERROR, "ManagedNandFlash_EraseBlock: Block must be DIRTY\n\r");
        return NandCommon_ERROR_WRONGSTATUS;
    }

    // Erase block
    error = RawNandFlash_EraseBlock(RAW(managed), block);
    if (error) {

        return error;
    }

    // Update block status
    managed->blockStatuses[block].status = NandBlockStatus_FREE;
    managed->blockStatuses[block].eraseCount++;
    return WriteBlockStatus(managed, block);
}

//------------------------------------------------------------------------------
/// Reads the data and/or the spare area of a page on a managed nandflash. If
/// the data pointer is not 0, then the block MUST be LIVE.
/// Returns NandCommon_ERROR_WRONGSTATUS if the block is not LIVE and the data
/// pointer is not null; Otherwise, returns EccNandFlash_ReadPage().
/// \param managed  Pointer to a ManagedNandFlash instance.
/// \param block  Number of block to read page from.
/// \param page  Number of page to read inside the given block.
/// \param data  Data area buffer, can be 0.
/// \param spare  Spare area buffer, can be 0.
//------------------------------------------------------------------------------
unsigned char ManagedNandFlash_ReadPage(
    const struct ManagedNandFlash *managed,
    unsigned short block,
    unsigned short page,
    void *data,
    void *spare)
{
    // Check that the block is LIVE if data is requested
    if ((managed->blockStatuses[block].status != NandBlockStatus_LIVE)
        && (managed->blockStatuses[block].status != NandBlockStatus_DIRTY)) {

        trace_LOG(trace_ERROR, "ManagedNandFlash_ReadPage: Block must be LIVE or DIRTY.\n\r");
        return NandCommon_ERROR_WRONGSTATUS;
    }

    // Read data with ECC verification
    return EccNandFlash_ReadPage(ECC(managed), block, page, data, spare);
}

//------------------------------------------------------------------------------
/// Writes the data and/or spare area of a LIVE page on a managed NandFlash.
/// Returns NandCommon_ERROR_WRONGSTATUS if the page is not LIVE; otherwise,
/// returns EccNandFlash_WritePage().
/// \param managed  Pointer to a ManagedNandFlash instance.
/// \param block  Number of the block to write.
/// \param page  Number of the page to write inside the given block.
/// \param data  Data area buffer.
/// \param spare  Spare area buffer.
//------------------------------------------------------------------------------
unsigned char ManagedNandFlash_WritePage(
    const struct ManagedNandFlash *managed,
    unsigned short block,
    unsigned short page,
    void *data,
    void *spare)
{
    // Check that the block is LIVE
    if (managed->blockStatuses[block].status != NandBlockStatus_LIVE) {

        trace_LOG(trace_ERROR, "ManagedNandFlash_WritePage: Block must be LIVE.\n\r");
        return NandCommon_ERROR_WRONGSTATUS;
    }

    // Write data with ECC calculation
    return EccNandFlash_WritePage(ECC(managed), block, page, data, spare);
}

//------------------------------------------------------------------------------
/// Copy the data & spare area of one page to another page. The source block
/// can be either LIVE or DIRTY, and the destination block must be LIVE; they
/// must both have the same parity.
/// Returns 0 if successful; NandCommon_ERROR_WRONGSTATUS if one or more page
/// is not live; otherwise returns an NandCommon_ERROR_xxx code.
/// \param managed  Pointer to a ManagedNandFlash instance.
/// \param sourceBlock  Source block number.
/// \param sourcePage  Number of source page inside the source block.
/// \param destBlock  Destination block number.
/// \param destPage  Number of destination page inside the dest block.
//------------------------------------------------------------------------------
unsigned char ManagedNandFlash_CopyPage(
    const struct ManagedNandFlash *managed,
    unsigned short sourceBlock,
    unsigned short sourcePage,
    unsigned short destBlock,
    unsigned short destPage)
{
    unsigned char error;

    ASSERT((sourcePage & 1) == (destPage & 1),
           "ManagedNandFlash_CopyPage: source & dest pages must have the same parity\n\r");

    trace_LOG(INFO, "ManagedNandFlash_CopyPage(B#%d:P#%d -> B#%d:P#%d)\n\r",
              sourceBlock, sourcePage, destBlock, destPage);

    // Check block statuses
    if ((managed->blockStatuses[sourceBlock].status != NandBlockStatus_LIVE)
         && (managed->blockStatuses[sourceBlock].status != NandBlockStatus_DIRTY)) {

        trace_LOG(trace_ERROR,
                  "ManagedNandFlash_CopyPage: Source block must be LIVE or DIRTY.\n\r");
        return NandCommon_ERROR_WRONGSTATUS;
    }
    if (managed->blockStatuses[destBlock].status != NandBlockStatus_LIVE) {

        trace_LOG(trace_ERROR,
                  "ManagedNandFlash_CopyPage: Destination block must be LIVE.\n\r");
        return NandCommon_ERROR_WRONGSTATUS;
    }

    // If destination page is page #0, block status information must not be
    // overwritten
    if (destPage == 0) {

        unsigned char data[NandCommon_MAXPAGEDATASIZE];
        unsigned char spare[NandCommon_MAXPAGESPARESIZE];

        // Read data & spare to copy
        error = EccNandFlash_ReadPage(ECC(managed), sourceBlock, sourcePage, data, spare);
        if (error) {

            return error;
        }

        // Write destination block status information in spare
        NandSpareScheme_WriteExtra(NandFlashModel_GetScheme(MODEL(managed)),
                                   spare,
                                   &(managed->blockStatuses[destBlock]),
                                   4,
                                   0);

        // Write page
        error = RawNandFlash_WritePage(RAW(managed), destBlock, destPage, data, spare);
        if (error) {

            return error;
        }
    }
    // Otherwise, a normal copy can be done
    else {

        return RawNandFlash_CopyPage(RAW(managed),
                                     sourceBlock,
                                     sourcePage,
                                     destBlock,
                                     destPage);
    }

    return 0;
}

//------------------------------------------------------------------------------
/// Copies the data from a whole block to another block on a nandflash. Both
/// blocks must be LIVE.
/// Returns 0 if successful; otherwise returns NandCommon_ERROR_WRONGSTATUS if
/// at least one of the blocks is not free, or a NandCommon_ERROR_xxx code.
/// \param managed  Pointer to a ManagedNandFlash instance.
/// \param sourceBlock  Source block number.
/// \param destBlock  Destination block number.
//------------------------------------------------------------------------------
unsigned char ManagedNandFlash_CopyBlock(
    const struct ManagedNandFlash *managed,
    unsigned short sourceBlock,
    unsigned short destBlock)
{
    unsigned short numPages = NandFlashModel_GetBlockSizeInPages(MODEL(managed));
    unsigned char error;
    unsigned short page;

    ASSERT(sourceBlock != destBlock,
           "ManagedNandFlash_CopyBlock: Source block must be different from dest. block\n\r");

    trace_LOG(INFO, "ManagedNandFlash_CopyBlock(B#%d->B#%d)\n\r",
              sourceBlock, destBlock);

    // Copy all pages
    for (page=0; page < numPages; page++) {

        error = ManagedNandFlash_CopyPage(managed,
                                          sourceBlock,
                                          page,
                                          destBlock,
                                          page);
        if (error) {

            trace_LOG(trace_ERROR,
                      "ManagedNandFlash_CopyPage: Failed to copy page %d\n\r",
                      page);
            return error;
        }
    }

    return 0;
}

//------------------------------------------------------------------------------
/// Erases all the blocks which are currently marked as DIRTY.
/// Returns 0 if successful; otherwise, returns a NandCommon_ERROR code.
/// \param managed  Pointer to a ManagedNandFlash instance.
//------------------------------------------------------------------------------
unsigned char ManagedNandFlash_EraseDirtyBlocks(
    struct ManagedNandFlash *managed)
{
    unsigned int i;
    unsigned char error;

    // Erase all dirty blocks
    for (i=0; i < NandFlashModel_GetDeviceSizeInBlocks(MODEL(managed)); i++) {

        if (managed->blockStatuses[i].status == NandBlockStatus_DIRTY) {

            error = ManagedNandFlash_EraseBlock(managed, i);
            if (error) {

                return error;
            }
        }
    }

    return 0;
}

//------------------------------------------------------------------------------
/// Looks for the youngest block having the desired status among the blocks
/// of a managed nandflash. If a block is found, its index is stored inside
/// the provided variable (if pointer is not 0).
/// Returns 0 if a block has been found; otherwise returns either
/// NandCommon_ERROR_NOBLOCKFOUND if there are no blocks having the desired
/// status.
/// \param managed  Pointer to a ManagedNandFlash instance.
/// \param block  Pointer to the block number variable.
//------------------------------------------------------------------------------
unsigned char ManagedNandFlash_FindYoungestBlock(
    const struct ManagedNandFlash *managed,
    unsigned char status,
    unsigned short *block)
{
    unsigned char found = 0;
    unsigned short bestBlock = 0;
    unsigned int i;

    // Go through the block array
    for (i=0; i < NandFlashModel_GetDeviceSizeInBlocks(MODEL(managed)); i++) {

        // Check status
        if (managed->blockStatuses[i].status == status) {

            // If no block was found, i becomes the best block
            if (!found) {

                found = 1;
                bestBlock = i;
            }
            // Compare the erase counts otherwise
            else if (managed->blockStatuses[i].eraseCount
                     < managed->blockStatuses[bestBlock].eraseCount) {

                bestBlock = i;
            }
        }
    }

    if (found) {

        if (block) {

            *block = bestBlock;
        }
        return 0;
    }
    else {

        return NandCommon_ERROR_NOBLOCKFOUND;
    }
}

//------------------------------------------------------------------------------
/// Counts and returns the number of blocks having the given status in a
/// managed nandflash.
/// \param managed  Pointer to a ManagedNandFlash instance.
/// \param status  Desired block status.
//------------------------------------------------------------------------------
unsigned short ManagedNandFlash_CountBlocks(
    const struct ManagedNandFlash *managed,
    unsigned char status)
{
    unsigned int i;
    unsigned short count = 0;

    // Examine each block
    for (i=0; i < NandFlashModel_GetDeviceSizeInBlocks(MODEL(managed)); i++) {

        if (managed->blockStatuses[i].status == status) {

            count++;
        }
    }

    return count;
}