Jump to main content

##

# 1.1.3.4.6 DRV_MEMORY_AsyncErase Function

## C

    void DRV_MEMORY_AsyncErase
    (
        const DRV_HANDLE handle,
        DRV_MEMORY_COMMAND_HANDLE *commandHandle,
        uint32_t blockStart,
        uint32_t nBlock
    );

## Summary

Erase the specified number of memory blocks in Asynchronous mode.

## Description

This function schedules a non-blocking sector erase operation for the specified number of memory blocks from the specified block start start address on attached memory device.

Each block is equal to sector size of the memory device attached.

The function returns with a valid erase handle in the commandHandle argument if the erase request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately.

The function returns DRV_MEMORY_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances:

- if a buffer object could not be allocated to the request
- if the client opened the driver for read only
- if the number of blocks to be erased is either zero or more than the number of blocks actually available
- if the erase queue size is full or queue depth is insufficient
- if the driver handle is invalid

If the requesting client registered a transfer handler callback with the driver, It will issue a DRV_MEMORY_EVENT_COMMAND_COMPLETE event if the erase operation was successful or DRV_MEMORY_EVENT_COMMAND_ERROR event if the erase operation was not successful.

If the requesting client has not registered any transfer handler callback with the driver, It can call DRV_MEMORY_CommandStatusGet() API to know the current status of the request.

## Preconditions

The DRV_MEMORY_Open() must have been called with DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE as a parameter to obtain a valid opened device handle.

## Parameters

Param | Description
--- | ---
handle | A valid open-instance handle, returned from the driver's open function
commandHandle | Pointer to an argument that will contain the return buffer handle
blockStart | Block start from where the blocks should be erased.
nBlock | Total number of blocks to be erased.

## Returns

The command handle is returned in the commandHandle argument. It Will be DRV_MEMORY_COMMAND_HANDLE_INVALID if the request was not queued.

## Example

    // Use DRV_MEMORY_GeometryGet () to find the write region geometry.
    uint32_t blockStart = 0;
    uint32_t nBlocks = 10;
    bool xfer_done = false;

    // memoryHandle is the handle returned by the DRV_MEMORY_Open function.

    // Event is received when the erase request is completed.
    void appTransferHandler
    (
        DRV_MEMORY_EVENT event,
        DRV_MEMORY_COMMAND_HANDLE commandHandle,
        uintptr_t context
    )
    {
        switch(event)
        {
            case DRV_MEMORY_EVENT_COMMAND_COMPLETE:
            {
                xfer_done = true;
                break;
            }

            case DRV_MEMORY_EVENT_COMMAND_ERROR:
            {
                // Handle Error
                break;
            }

            default:
            {
                break;
            }
        }
    }

    DRV_MEMORY_TransferHandlerSet(memoryHandle, appTransferHandler, (uintptr_t)NULL);

    DRV_MEMORY_AsyncErase( memoryHandle, &commandHandle, blockStart, nBlocks );

    if(DRV_MEMORY_COMMAND_HANDLE_INVALID == commandHandle)
    {
        // Error handling here
    }

    // Wait for erase to be completed
    while(!xfer_done);

## Remarks

This API is supported in Both Bare-Metal and RTOS environment.