File System Component  Version 5.0
MDK-Professional Middleware for Devices with Flash File System
 All Data Structures Files Functions Variables Enumerations Enumerator Macros Groups Pages
I/O Control Interface Routines

I/O control interface routines provide operate on FAT formatted media devices. More...

Functions

int32_t fs_ioc_get_id (const char *drive)
 Check if valid drive is specified and return its ID.
 
fsStatus fs_ioc_lock (int32_t drv_id)
 Lock drive and block media access to the upper layer.
 
fsStatus fs_ioc_unlock (int32_t drv_id)
 Unlock drive and allow media access to the upper layer.
 
fsStatus fs_ioc_get_cache (int32_t drv_id, fsIOC_Cache *cache_info)
 Return IOC cache buffer information.
 
fsStatus fs_ioc_read_sector (int32_t drv_id, uint32_t sect, uint8_t *buf, uint32_t cnt)
 Read sector from media.
 
fsStatus fs_ioc_write_sector (int32_t drv_id, uint32_t sect, const uint8_t *buf, uint32_t cnt)
 Write sector to media.
 
fsStatus fs_ioc_read_info (int32_t drv_id, fsMediaInfo *info)
 Read media configuration info.
 
fsStatus fs_ioc_device_ctrl (int32_t drv_id, fsDevCtrlCode code, void *p)
 IOC device control access; control code is sent directly to device driver.
 

Description

Function Documentation

fsStatus fs_ioc_device_ctrl ( int32_t  drv_id,
fsDevCtrlCode  code,
void *  p 
)
Parameters
[in]drv_idDrive identifier obtained by fs_ioc_get_id.
[in]codeDevice control code.
[in,out]pGeneric pointer.
Returns
execution status fsStatus

The function fs_ioc_device_ctrl is used to send control code directly to the device driver, causing the device to perform a corresponding operation.

The argument drv_id identifies the drive.

The argument code is specifying the control code to be sent.

The argument p is a generic pointer and is used if the control code requires additional parameters to be passed to the driver or causes return values. The object to which pointer p points to, depends on the control code used.

Control code Generic pointerOperation description
fsDevCtrlCode_CheckMediauint32_t Checks presence and write protection status of a removable media.
fsDevCtrlCode_Format void Performs a low level format.
fsDevCtrlCode_GetCID fsCID_Register Reads memory card CID register.
fsDevCtrlCode_Serial uint32_t Reads device serial number.

Code Examples

void tst_device_status (void) {
int32_t id;
uint32_t status;
id = fs_ioc_get_id ("M:");
if (fs_ioc_device_ctrl (id, fsDevCtrlCode_CheckMedia, &status) == fsOK) {
if (status & FS_MEDIA_INSERTED) {
printf ("Removable media is present.\n");
}
if (status & FS_MEDIA_PROTECTED) {
printf ("Removable media is write protected.\n");
}
if (status & FS_MEDIA_INITIALIZED) {
printf ("Removable media is initialized.\n");
}
if (status & FS_MEDIA_NOCHKMEDIA) {
printf ("Removable media is present.\n");
}
}
}
void get_device_serial (void) {
int32_t id;
uint32_t serial;
id = fs_ioc_get_id ("M:");
if (fs_ioc_device_ctrl (id, fsDevCtrlCode_Serial, &serial) == fsOK) {
printf ("Device serial number is %d.\n", serial);
}
}
void read_cid (void) {
int32_t id;
id = fs_ioc_get_id ("M:");
if (fs_ioc_device_ctrl (id, fsDevCtrlCode_GetCID, &cid) == fsOK) {
printf ("Manufacturer ID: %d (0x%.2X)\n", cid.MID, cid.MID);
printf ("OEM/Application ID: %c%c\n", cid.OID >> 8, cid.OID & 0xFF);
printf ("Product name: %c%c%c%c%c\n", cid.PNM[0], cid.PNM[1], cid.PNM[2], cid.PNM[3], cid.PNM[4]);
printf ("Product revision: %d.%d\n", cid.PRV >> 4, cid.PRV & 0x0F);
printf ("Product serial number: 0x%X\n", cid.PSN);
printf ("Manufacturing date: %d/%.2d\n", cid.MDT & 0x0F, cid.MDT >> 4);
}
}
void format_nand (void) {
int32_t id;
id = fs_ioc_get_id ("N:");
if (fs_ioc_device_ctrl (id, fsDevCtrlCode_Format, NULL) == fsOK) {
printf ("Low level NAND formatting succeeded.\n");
}
}
fsStatus fs_ioc_get_cache ( int32_t  drv_id,
fsIOC_Cache cache_info 
)
Parameters
[in]drv_idDrive identifier obtained by fs_ioc_get_id.
[out]cache_infoIOC Cache information.
Returns
execution status fsStatus
  • fsOK = Operation successful.
  • fsInvalidParameter = Input parameters are not valid.
  • fsInvalidDrive = Nonexistent drive id specified.
  • fsAccessDenied = IOC access not allowed for specified drive.

The function fs_ioc_get_cache is used to gain information about the file system cache buffer location and its size. The I/O Control Interface can use this buffer as a temporary storage for sector operations using fs_ioc_read_sector and fs_ioc_write_sector or for any other data storage.

The argument cache_info is a pointer to the fsIOC_Cache structure where the buffer location and its size will be stored.

Note
The buffer size is defined in the configuration file for a particular drive using File System Cache setting.

Code Example

void chk_cache_buffer (void) {
int32_t id;
id = fs_ioc_get_id ("M:");
if (fs_ioc_get_cache (id, &info) == fsOK) {
printf ("Cache buffer location: 0x%X\n", info.buffer);
printf ("Cache buffer size: %d bytes.\n", info.size);
}
}
int32_t fs_ioc_get_id ( const char *  drive)
Parameters
[in]drivea string specifying the memory or storage device.
Returns
drive ID or execution status
  • value >= 0: drive ID as an integer when specified drive exists and allows IOC access
  • value < 0: error occurred, -value is execution status as defined with fsStatus

The function fs_ioc_get_id is used to get the drive identifier associated with the specified drive letter.

The argument drive is specifying a FAT volume drive. The Default System Drive is used, if an empty string "" is provided.

fsStatus fs_ioc_lock ( int32_t  drv_id)
Parameters
[in]drv_idDrive identifier obtained by fs_ioc_get_id.
Returns
execution status fsStatus
  • fsOK = Operation successful.
  • fsInvalidDrive = Nonexistent drive id specified.
  • fsAccessDenied = IOC access not allowed for specified drive.

The function fs_ioc_lock locks a drive in order to block media access to the file system layer while the I/O Control Interface routines are in use. The I/O Control Interface should only be used in the locked state due to possible interference with file system accesses to the media. All file operations will fail while the drive is in the locked state. The function fs_ioc_unlock is used to unlock the drive.

The argument drv_id identifies the drive and must be obtained using the fs_ioc_get_id function.

fsStatus fs_ioc_read_info ( int32_t  drv_id,
fsMediaInfo info 
)
Parameters
[in]drv_idDrive identifier obtained by fs_ioc_get_id.
[out]infoMedia information structure.
Returns
execution status fsStatus
  • fsOK = Operation successful.
  • fsInvalidDrive = Nonexistent drive id specified.
  • fsNoMedia = Media not present.
  • fsAccessDenied = IOC access not allowed for specified drive.
  • fsError = Media information read failed.

The function fs_ioc_read_info reads the media configuration.

The argument drv_id identifies the drive.

The argument info returns the media information structure as specified in fsMediaInfo.

Code Example

void get_device_size (void) {
int32_t id;
id = fs_ioc_get_id ("M:");
if (fs_ioc_read_info (id, &info) == fsOK) {
printf ("Device size is %d bytes.\n", info.block_cnt * info.read_blen);
}
}
fsStatus fs_ioc_read_sector ( int32_t  drv_id,
uint32_t  sect,
uint8_t *  buf,
uint32_t  cnt 
)
Parameters
[in]drv_idDrive identifier obtained by fs_ioc_get_id.
[in]sectSector number.
[out]bufData buffer.
[in]cntCount of sectors.
Returns
execution status fsStatus
  • fsOK = Operation successful.
  • fsInvalidDrive = Nonexistent drive id specified.
  • fsNoMedia = Media not present.
  • fsAccessDenied = IOC access not allowed for specified drive.
  • fsError = Read sector failed.

The function fs_ioc_read_sector reads data from one or more sectors of FAT formatted media.

The argument drv_id identifies the drive.

The argument sect specifies the starting sector from where to read the data.

The argument buf is a pointer to the buffer that stores the data.

The argument cnt specifies the number of sectors to read.

Code Example

bool sector_read (uint32_t sector_addr, uint8_t *buf) {
int32_t id;
id = fs_ioc_get_id ("U:");
if (fs_ioc_lock (id) == fsOK) {
fs_ioc_read_sector (id, sector_addr, buf, 1);
return true;
}
return false;
}
fsStatus fs_ioc_unlock ( int32_t  drv_id)
Parameters
[in]drv_idDrive identifier obtained by fs_ioc_get_id.
Returns
execution status fsStatus
  • fsOK = Operation successful.
  • fsInvalidDrive = Nonexistent drive id specified.
  • fsAccessDenied = IOC access not allowed for specified drive.

The function fs_ioc_unlock unlocks a drive and releases media access to the file system layer. The I/O Control Interface should only be used in the locked state due to possible interference with file system accesses to the media. The function fs_ioc_lock is used to lock the drive.

The argument drv_id identifies the drive and must be obtained using the fs_ioc_get_id function.

fsStatus fs_ioc_write_sector ( int32_t  drv_id,
uint32_t  sect,
const uint8_t *  buf,
uint32_t  cnt 
)
Parameters
[in]drv_idDrive identifier obtained by fs_ioc_get_id.
[in]sectSector number.
[out]bufData buffer.
[in]cntCount of sectors.
Returns
execution status fsStatus
  • fsOK = Operation successful.
  • fsInvalidDrive = Nonexistent drive id specified.
  • fsNoMedia = Media not present.
  • fsAccessDenied = IOC access not allowed for specified drive.
  • fsError = Read sector failed.

The function fs_ioc_write_sector writes data to one or more sectors of FAT formatted media.

The argument drv_id identifies the drive.

The argument sect specifies the starting sector to write the data.

The argument buf is a pointer to the buffer that contains the data to write.

The argument cnt specifies the number of sectors to write to.

Code Example

bool sector_write (uint32_t sector_addr, const uint8_t *buf) {
int32_t id;
id = fs_ioc_get_id ("U:");
if (fs_ioc_lock (id) == fsOK) {
fs_ioc_write_sector (id, sector_addr, buf, 1);
return true;
}
return false;
}