Mass Storage Devices (BLACKSheep OS)

Mass Storage Device Manager

Registering a MSD

Files associated: MSDmanager.c , MSDmanager.h

Directories: BLACKSheep/common/msd

The device manager manages the low level driver of all devices where file systems can be located like SD Card, CF Card and RAM drive called block devices. The device manager also controls calls to character or streaming devices.

The device manager allows to register or un-register block or streaming devices and to perform hardware independent read or write operations. The function msd_info provides information about the device.

Example:

The example registers an SD-card to the device manager.

<source lang="c"> // initializing sd-card T_SD_HANDLE hSDcard = sd_open (pa_cSDcardSlot); // registering sd-card at the device manager msd_register((void*)hSDcard, "sd0", 0, dev_sd_blockRead, dev_sd_blockWrite, dev_sd_info); </source>

Prior to using any functionality of the device manager he has to be initialized by calling the msd_initManager function.

Required functionality for new devices

If you want to add a new MSD to the MSD manager so you need to provide 3 functions for access to the new device:

Read block(s)

<source lang="c">signed long fnBlockRead(void *pa_pDevHandle, unsigned long pa_nBlockAddr, unsigned long pa_nBlockCount, unsigned char *pa_pcData);</source>

The device is specified by the device handle pa_pDevHandle. The function reads an amount of pa_nBlockCount starting from address pa_nBlockAddr and fills the buffer pa_pcData. The needed memory for pa_pcData is allocated from MSD manager before the function is calling.

Write block(s)

<source lang="c">signed long fnblockWrite(void *pa_pDevHandle, unsigned long pa_nBlockAddr, unsigned long pa_nBlockCount, unsigned char *pa_pcData);</source>

The device is specified by the device handle pa_pDevHandle. The function writes the specified data buffer pa_pcData containing an amount of pa_nBlockCount blocks at the address pa_nBlockAddr.

Device info

<source lang="c">T_ERROR_CODE fnInfo(void *pa_pDevHandle, T_DEVICE_INFO *pa_pstDeviceInfo);</source>

The device is specified by the device handle pa_pDevHandle. The function fills the struct pa_pstDeviceInfo. This struct contains informations about the MSD such as the block count, block size, head count, cylinder count, blocks per track and the device type. Please refer to the doxygen documentation for more informations about the struct T_DEVICE_INFO.

Initialize the supported MSDs

Files associated: MSDinit.c , MSDinit.h

Directories: BLACKSheep/common/msd

The file MSDinit.c contains the initializations of the supported MSDs listen here. The init functions are only avaiable if the corresponding macro is uncommented in Environment.h . Following functions are avaiable: <source lang="c"> T_ERROR_CODE MSDramdriveInit (unsigned long pa_nBlockcount,

                             char *pa_pcPartitionName, 
                             char *pa_pcFileSystem);

T_ERROR_CODE MSDsdcardInit (unsigned char pa_cSPI,

                           unsigned long pa_nSPIsdCardSlot, 
                           char *pa_pcPartitionName, 
                           char *pa_pcFileSystem);

T_ERROR_CODE MSDcfcardTrueIdeModeInit ( unsigned long pa_nBaseAddress,

                                       unsigned short pa_nAddressShift, 
                                       T_GPIO_MASK pa_tResetFlag, 
                                       T_GPIO_MASK pa_tIRQFlag, 
                                       char *pa_pcPartitionName,
                                       char *pa_pcFileSystem);

T_ERROR_CODE MSDSdhSdCardInit (unsigned long pa_nSDHsdCardSlot,

                              unsigned char *pa_pcPartitionName, 
                              char *pa_pcFileSystem);

</source>

Please refer to the doxygen documentation for further information.

Supported Mass Storage Devices

RAM Drive

Files associated: RDconfig.c , RDconfig.h devRD.c , devRD.h

Directories: BLACKSheep/common/msd

The RAM-drive driver emulates a RAM drive. The memory needed for the device is allocated from heap. So be sure to have enough space in heap. The driver implements the following functions:

Prototypes: <source lang="c"> T_RD_HANDLE rd_open(unsigned long pa_nNofSectors); T_ERROR_CODE rd_readSingleBlock(T_RD_HANDLE pa_hRD, unsigned long pa_nBlockAddr, unsigned char *pa_cData); T_ERROR_CODE rd_writeSingleBlock(T_RD_HANDLE pa_hRD, unsigned long pa_nBlockAddr, unsigned char *pa_cData); void rd_close( T_RD_HANDLE pa_hRD ); </source>

Interface to the device manager:

To provide a common interface to the device manager the file devRD.c contains the 3 common interface functions for the device manager:

<source lang="c"> signed long dev_rd_blockRead(void *pa_pDevHandle, unsigned long pa_nBlockAddr, unsigned long pa_nBlockCount, unsigned char *pa_pcData); signed long dev_rd_blockWrite(void *pa_pDevHandle, unsigned long pa_nBlockAddr, unsigned long pa_nBlockCount, unsigned char *pa_pcData); T_ERROR_CODE dev_rd_info(void *pa_pDevHandle, T_DEVICE_INFO *pa_pstDeviceInfo); </source>

The RAM drive can be configured in the Environment.h .

SD Card over SPI

Files associated: SDcard.c , SDcard.h , devSD.c , devSD.h

Directories: BLACKSheep/common/msd

This SD Card driver uses the SPI interface to communicate with the SD Card. The driver does all low level communication with the SD Card providing an interface to the user, so that the user can communicate with the SD Card. As the SD Card driver uses the SPI interface be sure to have initialized the SPI driver prior to call any function of the SD Card driver. The following example shows how to initialize the SD Card over SPI:

<source lang="c"> T_SD_HANDLE hSDCard = sd_open(pa_cSPIBus, pa_nSPISlot); </source>

The parameters needed by the sd_open function is the number of the SPI bus where the SD card is connected and the SPI slot (CS signal) used to activate the SD Card. The function returns a handle which identifies the SD Card and is used by other further calls to the SD Card driver. The driver implements the following functions:

Prototypes: <source lang="c"> void sd_cleanup(void); T_SD_HANDLE sd_open( unsigned char pa_cSPI, unsigned long pa_nSlot ); void sd_close(T_SD_HANDLE pa_hSDcard); char sd_writeSingleBlock(T_SD_HANDLE pa_hSDcard, unsigned long pa_nBlockAddress, unsigned char *pa_cData); char sd_readSingleBlock (T_SD_HANDLE pa_hSDcard, unsigned long pa_nBlockAddress, unsigned char *pa_cData); char sd_readCardInfo ( T_SD_HANDLE pa_hSDcard, unsigned char *cProductName, unsigned char *cManufactID, unsigned char *cApplicationID, unsigned char *cProductRev, unsigned long *nSerialNr, unsigned char *cManuMonth, unsigned short *nManuYear); </source>

Interface to the device manager:

To provide a common interface to the device manager the file devSD.c contains the 3 common interface functions for the device manager:

<source lang="c"> signed long dev_sd_blockRead(void *pa_pDevHandle, unsigned long pa_nBlockAddr, unsigned long pa_nBlockCount, unsigned char *pa_pcData); signed long dev_sd_blockWrite(void *pa_pDevHandle, unsigned long pa_nBlockAddr, unsigned long pa_nBlockCount, unsigned char *pa_pcData); T_ERROR_CODE dev_sd_info(void *pa_pDevHandle, T_DEVICE_INFO *pa_pstDeviceInfo); </source>

The SD Card over SPI can be configured in the Environment.h .

SD Card over SDH

Files associated: devSDHSDCard.c , devSDHSDCard.h

Directories: BLACKSheep/common/msd

This SD Card driver uses the SDH interface to communicate with the SD Card. The driver does all low level communication with the SD Card providing an interface to the user, so that the user can communicate with the SD Card. As the SD Card driver uses the SDH interface be sure to have initialized the SDH driver prior to call any function of the SD Card driver. The following example shows how to initialize the SD Card over SDH:

<source lang="c"> T_SDH_SD_CARD_HANDLE hSDHSDCard = SDHsdCardOpen (pa_nSDHsdCardSlot); </source>

The only parameter needed by the SDHsdCardOpen function is the number of the SDH bus where the SD card is connected. The function returns a handle which identifies the SD Card and is used by other further calls to the SD Card driver.

Interface to the device manager:

To provide a common interface to the device manager the file devSDHSDCard.c contains the 3 common interface functions for the device manager:

<source lang="c"> signed long dev_sdh_sd_card_blockRead(void *pa_pDevHandle, unsigned long pa_nBlockAddr, unsigned long pa_nBlockCount, unsigned char *pa_pcData); signed long dev_sdh_sd_card_blockWrite(void *pa_pDevHandle, unsigned long pa_nBlockAddr, unsigned long pa_nBlockCount, unsigned char *pa_pcData); T_ERROR_CODE dev_sdh_sd_card_info(void *pa_pDevHandle, T_DEVICE_INFO *pa_pstDeviceInfo); </source>

The SD Card over SDH can be configured in the Environment.h .

CF Card

Files associated: devIDE.c , devIDE.h , IDEconfig.c , IDEconfig.h

Directories: BLACKSheep/common/msd

The CF Card driver supports CF Cards in true IDE mode. Hence the files and functions associated with the CF Card have ide as prefix. For this reason the CF Card driver should also working with mass storage devices supporting the IDE-ATA mode as harddisks or similar devices. The example shows how to initialize the CF-card driver and how to open a device:

<source lang="c"> T_IDE_HANDLE hIDE = ide_open(pa_nSlotBaseAddress, pa_nAddressShift, pa_bAsMaster, pa_gpioResetFlag, pa_gpioIntReq); </source> The parameters needed for the ide_open are:

• pa_nSlotBaseAddress: base address of the CF Card (i.e. 0x2020C000)
• pa_nAddressShift: address A2, A1, A0 shift in True IDE mode
• pa_bAsMaster: true if device is master
• pa_gpioResetFlag: GPIO used as RESET signal
• pa_gpioIntReq: GPIO used as IRQ

The driver implements the following functions:

Prototypes: <source lang="c"> T_IDE_HANDLE ide_open(T_ADDRESS pa_nSlotBaseAddress, unsigned short pa_nAddressShift, bool pa_bAsMaster, T_GPIO_MASK pa_gpioResetFlag, T_GPIO_MASK pa_gpioIntReq); void ide_close(T_IDE_HANDLE pa_hIDE); T_ERROR_CODE ide_readSingleBlock(T_IDE_HANDLE pa_hIDE, T_ADDRESS pa_nBlockAddr, unsigned char *pa_cData); T_ERROR_CODE ide_readMultipleBlocks(T_IDE_HANDLE pa_hIDE, T_ADDRESS pa_nStartBlockAddr, unsigned long pa_nBlockCount, unsigned char *pa_cData); T_ERROR_CODE ide_writeSingleBlock(T_IDE_HANDLE pa_hIDE, T_ADDRESS pa_nBlockAddr, unsigned char *pa_cData); T_ERROR_CODE ide_writeMultipleBlocks(T_IDE_HANDLE pa_hIDE, T_ADDRESS pa_nStartBlockAddr, unsigned long pa_nBlockCount, unsigned char *pa_cData); </source> Interface to the device manager:

To provide a common interface to the device manager the file devIDE.c contains the 3 common interface functions for the device manager:

<source lang="c"> signed long dev_ide_blockRead(void *pa_pDevHandle, unsigned long pa_nBlockAddr, unsigned long pa_nBlockCount, unsigned char *pa_pcData); signed long dev_ide_blockWrite(void *pa_pDevHandle, unsigned long pa_nBlockAddr, unsigned long pa_nBlockCount, unsigned char *pa_pcData); T_ERROR_CODE dev_ide_info(void *pa_pDevHandle, T_DEVICE_INFO *pa_pstDeviceInfo); </source>

The CF Card can be configured in the Environment.h .