1 /*

     2 * Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 * Simple non volatile memory device. nvmemmory.h

    17 *

    18 */

    19 

    20 #ifndef _NVMEMORY_H

    21 #define _NVMEMORY_H

    22 

    23 #pragma once

    24 

    25 /*! \brief 

    26 NVMEMORY.DLL 

    27 - A simple non volatile sector addressed memory device

    28 - An example of a portable high abstraction model architecture. 

    29   This DLL is created to serve in multiple different modeling 

    30   environments and tools. Model portability should be taken into 

    31   account when further developing and maintaining this device.

    32 

    33 USAGE       

    34 nvmemory.dll Example usage provided by syborg_nvmemorydevice.py.

    35 1 - Create an instance of SyborgNVMemory class. 

    36     This can be performed either by instantiating the C++ class directly 

    37     by calling the constructor "new SyborgNVMemory( a_sectorsize );".

    38     Or by using the C API to create an instance "nvmem_create( sector_size )".

    39     As you can see you need to set the sector size for your device when you create it.

    40     

    41     In fact each of the API functions are provided in form of both C and C++ API functions.

    42     From this on only the C API is explained.

    43 

    44 2 - Reset the device by calling "nvmem_reset( self.obj )". 

    45     This function clears any information stored by the device instance except the sector size.

    46     Note that for the C API you always need to specify the object which you wish to command.

    47 

    48 3 - Create handle to your image file by calling "nvmem_open( self.obj, imagepath )".

    49     Image is opened in binary mode. Store the handle.

    50     

    51     Note that you need to have an image stored to a path on your PC before you can call this function. 

    52     You must provide the image name and path when calling.

    53     

    54     Note also that there is a service provided by this DLL which can create an image for you.

    55     NVMEMORY_API int32_t nvmem_create_image( SyborgNVMemory* a_syborg_nvmemory, char* a_memoryarrayname, uint32_t a_sectorcount, uint32_t a_sectorsize = NVMEM_DEFAULT_SECTORSIZE_IN_BYTES );

    56     nvmem_create_image function probably needs further development. You may also create image in your wrapper as done in example usage file.

    57     

    58     You may get your memory device size by calling nvmem_get_sector_count( self.obj, nvmemhandle ).

    59     nvmemhandle is the handle you got when calling nvmem_open.

    60     nvmem_get_sector_count is handy in cases where you have provided a readymade image for the device.

    61     In this case you don't need to go and hardcode the image size each time in your wrapper.

    62     

    63 4 - Initialize callback. Provide a callback function for the device by calling "nvmem_set_callback( self.obj, nvmem_callback )".

    64     Where the callback is a function pointer of a type "int (*i_NVMemCallBack)(int);".

    65     Callback is called by DLL when read and write operations are finished. Parameter is the amount of sectors succesfully read or written.

    66     

    67 5 - Start using your device.

    68     nvmem_read(  self.obj, nvmemory_sharedmemory_host_address, nvmemhandle, transaction_offset, transaction_size )

    69     nvmem_write(  self.obj, nvmemory_sharedmemory_host_address, nvmemhandle, transaction_offset, transaction_size )

    70     

    71     See syborg_nvmemorydevice.py to learn more about device usage. 

    72 */

    73 

    74 #include "platformtypes.h"

    75 

    76 #ifdef WIN32

    77 #ifdef NVMEMORY_EXPORTS

    78 #define NVMEMORY_API __declspec(dllexport)

    79 #else

    80 #define NVMEMORY_API __declspec(dllimport)

    81 #endif

    82 #else

    83 #define NVMEMORY_API

    84 #endif

    85 

    86 class NVMEMORY_API SyborgNVMemory;

    87 

    88 extern "C"

    89     {

    90     const int32_t NVMEM_DEFAULT_SECTORSIZE_IN_BYTES = 512;

    91     const int32_t NVMEM_MAX_STREAMHANDLES = 16;

    92 

    93     /*Nvmemory error codes*/

    94     const int32_t NVMEM_OK =                                 0;

    95     const int32_t NVMEM_ERROR_OUT_OF_FREE_STREAMHANDLES =   -1;

    96     const int32_t NVMEM_ERROR_FOPEN =                       -2;

    97     const int32_t NVMEM_ERROR_FCLOSE =                      -3;

    98     const int32_t NVMEM_ERROR_FFLUSH =                      -4;

    99     const int32_t NVMEM_ERROR_FSEEK =                       -5;

   100     const int32_t NVMEM_ERROR_FREAD =                       -6;

   101     const int32_t NVMEM_ERROR_FWRITE =                      -7;

   102     const int32_t NVMEM_ERROR_SETVBUF =                     -8;

   103     const int32_t NVMEM_ERROR_CREATE =                      -9;

   104     const int32_t NVMEM_ERROR_FPRINTF =                     -10;

   105 

   106     /**

   107     * Reset the device

   108     *

   109     * @param a_syborg_nvmemory an object of class SyborgNVMemory.

   110     * @return TODO an error if fails

   111     */

   112     NVMEMORY_API int32_t nvmem_reset( SyborgNVMemory* a_syborg_nvmemory );

   113     

   114     /**

   115     * Create a non volatile memory array object.

   116     *

   117     * @param a_sectorsize Size for the sector.

   118     * @return An object of class SyborgNVMemory.

   119     */

   120     NVMEMORY_API SyborgNVMemory * nvmem_create( uint32_t a_sectorsize = NVMEM_DEFAULT_SECTORSIZE_IN_BYTES);

   121 

   122     /**

   123     * Create a non volatile memory array. A raw image will be created to host filesystem which will 

   124     * act as a non volatile memory device in client point of view.

   125     *

   126     * @param a_syborg_nvmemory an object of class SyborgNVMemory.

   127     * @param a_memoryarrayname Name for the image to be created.

   128     * @param a_sectorcount Image size in sectors.

   129     * @param a_sectorsize size for the sector.

   130     * @return An error code.

   131     */

   132     NVMEMORY_API int32_t nvmem_create_image( SyborgNVMemory* a_syborg_nvmemory, char* a_memoryarrayname, uint32_t a_sectorcount, uint32_t a_sectorsize = NVMEM_DEFAULT_SECTORSIZE_IN_BYTES );

   133     

   134     /**

   135     * Create handle to an image

   136     *

   137     * @param a_syborg_nvmemory an object of class SyborgNVMemory.

   138     * @param a_memoryarrayname Name and path for the image to be opened.

   139     * @return Handle to a non volatile memory array.

   140     */

   141     NVMEMORY_API int32_t nvmem_open( SyborgNVMemory* a_syborg_nvmemory, char* a_memoryarrayname );

   142 

   143     /**

   144     * Close handle to a non volatile memory array

   145     *

   146     * @param a_syborg_nvmemory an object of class SyborgNVMemory.

   147     * @param a_memoryarrayhandle Handle to be closed.

   148     * @return Error code.

   149     */

   150     NVMEMORY_API int32_t nvmem_close( SyborgNVMemory* a_syborg_nvmemory, int32_t a_memoryarrayhandle );

   151     

   152     /**

   153     * Flush possible cached content of a non volatile memory array

   154     *

   155     * @param a_syborg_nvmemory an object of class SyborgNVMemory.

   156     * @param a_memoryarrayhandle Handle pointing to stream which is flushed to a file.

   157     * @return Error code.

   158     */

   159     NVMEMORY_API int32_t nvmem_flush( SyborgNVMemory* a_syborg_nvmemory, int32_t a_memoryarrayhandle );

   160 

   161     /**

   162     * Read from a non volatile memory array to a guest os application memory space

   163     *

   164     * @param a_syborg_nvmemory an object of class SyborgNVMemory.

   165     * @param a_client_targetmemoryaddr Host OS address pointing to a place to where the data read should be returned.

   166     * @param a_memoryarrayhandle Handle to the device image.

   167     * @param a_memoryarrayoffset Sector offset to a position from where the data is to be read.

   168     * @param a_sectorcount Amount of sectors to be read.

   169     * @return Error code.

   170     */

   171     NVMEMORY_API void nvmem_read( SyborgNVMemory* a_syborg_nvmemory, uint32_t *a_client_targetmemoryaddr, int32_t a_memoryarrayhandle, uint32_t a_memoryarrayoffset, uint32_t a_sectorcount );

   172 

   173     /**

   174     * Write to a non volatile memory array from a guest os application memory space

   175     *

   176     * @param a_syborg_nvmemory an object of class SyborgNVMemory.

   177     * @param a_client_sourcememoryaddr Host OS address pointing to a place to where to get the data for write operation.

   178     * @param a_memoryarrayhandle Handle to the device image.

   179     * @param a_memoryarrayoffset Sector offset to a position to where the data is to be written.

   180     * @param a_sectorcount Amount of sectors to be written.

   181     * @return Error code.

   182     */

   183     NVMEMORY_API void nvmem_write( SyborgNVMemory* a_syborg_nvmemory, uint32_t *a_client_sourcememoryaddr, int32_t a_memoryarrayhandle, uint32_t a_memoryarrayoffset, uint32_t a_sectorcount );

   184 

   185     /**

   186     * Get the size of a non volatile memory array

   187     *

   188     * @param a_syborg_nvmemory an object of class SyborgNVMemory.

   189     * @param a_memoryarrayhandle Handle to the device image.

   190     * @return Total amount of sectors of the device.

   191     */

   192     NVMEMORY_API uint32_t nvmem_get_sector_count( SyborgNVMemory* a_syborg_nvmemory, int32_t a_memoryarrayhandle );

   193 

   194     /**

   195     * Store callback

   196     *

   197     * @param a_syborg_nvmemory an object of class SyborgNVMemory.

   198     * @param aGraphicsCallBack pointer to a callback function.

   199     * @return TODO an error if fails.

   200     */

   201     NVMEMORY_API int32_t nvmem_set_callback( SyborgNVMemory* a_syborg_nvmemory, int (*aGraphicsCallBack) (int) );

   202     }

   203 

   204 class NVMEMORY_API SyborgNVMemory

   205     {

   206     public:

   207 

   208         SyborgNVMemory( uint32_t a_sectorsize = NVMEM_DEFAULT_SECTORSIZE_IN_BYTES );

   209         ~SyborgNVMemory( );

   210 

   211         /**

   212         * Reset the device

   213         */

   214         int32_t NVMemReset( );

   215         /**

   216         * Create a non volatile memory array. A raw image will be created to host filesystem which will 

   217         * act as a non volatile memory device in client point of view.

   218         */

   219         int32_t NVMemCreateImage( char* a_memoryarrayname, uint32_t a_sectorcount, uint32_t a_sectorsize = NVMEM_DEFAULT_SECTORSIZE_IN_BYTES );

   220         /**

   221         * Return handle to a non volatile memory array

   222         */

   223         int32_t NVMemOpen( char* a_memoryarrayname );

   224         /**

   225         * Close handle to a non volatile memory array

   226         */

   227         int32_t NVMemClose( int32_t a_memoryarrayhandle );

   228         /**

   229         * Flush possible cached content of a non volatile memory array

   230         */

   231         int32_t NVMemFlush( int32_t a_memoryarrayhandle );

   232         /**

   233         * Read from a non volatile memory array to a guest os application memory space

   234         */

   235         void NVMemRead( uint32_t *a_client_targetmemoryaddr, int32_t a_memoryarrayhandle, uint32_t a_memoryarrayoffset, uint32_t a_sectorcount );

   236         /**

   237         * Write to a non volatile memory array from a guest os application memory space

   238         */

   239         void NVMemWrite( uint32_t *a_client_sourcememoryaddr, int32_t a_memoryarrayhandle, uint32_t a_memoryarrayoffset, uint32_t a_sectorcount );

   240         /**

   241         * Get the size of a non volatile memory array

   242         */

   243         uint32_t NVMemGetSectorCount( int32_t a_memoryarrayhandle );

   244         /**

   245         * Store callback

   246         */

   247         int32_t NVMemSetCallback( int (*aNVMemCallBack) (int) );

   248 

   249     private:

   250         FILE *i_filestream[NVMEM_MAX_STREAMHANDLES];

   251         uint32_t iNVMemSectorSizeInBytes;

   252         int (*i_NVMemCallBack)(int); 

   253     };

   254 

   255 #endif // _NVMEMORY_H