Jump to main content

##

# 1.1.3.4.8 DRV_MEMORY_AsyncEraseWrite Function

## C

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

## Summary

Erase and Write data for the specified number of memory blocks in Asynchronous mode.

## Description

This function combines the step of erasing a sector and then writing the page. The application can use this function if it wants to avoid having to explicitly delete a sector in order to update the pages contained in the sector.

This function schedules a non-blocking operation to erase and write blocks of data into attached device memory.

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

While the request is in the queue, the application buffer is owned by the driver and should not be modified.

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

- if a buffer could not be allocated to the request
- if the sourceBuffer pointer is NULL
- if the client opened the driver for read only
- if the number of blocks to be written is either zero or more than the number of blocks actually available
- if the driver handle is invalid

If the requesting client registered an event callback with the driver, the driver will issue a DRV_MEMORY_EVENT_COMMAND_COMPLETE event if the buffer was processed successfully or DRV_MEMORY_EVENT_COMMAND_ERROR event if the buffer was not processed successfully.

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

## Precondition

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 command handle. If NULL, then command handle is not returned.
sourceBuffer | The source buffer containing data to be programmed into media device memory
blockStart | Write block start where the write should begin.
nBlock | Total number of blocks to be written.

## 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

    #define BUFFER_SIZE 4096
    uint8_t buffer[BUFFER_SIZE];

    // Use DRV_MEMORY_GeometryGet () to find the write region geometry.
    uint32_t blockStart = 0x0;
    uint32_t nBlock = BUFFER_SIZE / block_size; // block_size for write geometry
    DRV_MEMORY_COMMAND_HANDLE commandHandle;

    // memoryHandle is the handle returned by the DRV_MEMORY_Open function.
    // Client registers an event handler with driver

    // Event is received when the erase-write 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_AsyncEraseWrite(memoryHandle, &commandHandle, &myBuffer, blockStart, nBlock);

    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.