FatFs - disk

disk_ioctl

The disk_ioctl function is called to control device specific features and miscellaneous functions other than generic read/write.

DRESULT disk_ioctl (
  BYTE pdrv,     /* [IN] Drive number */
  BYTE cmd,      /* [IN] Control command code */
  void* buff     /* [I/O] Parameter and data buffer */
);

Parameters

pdrv: Physical drive number to identify the target device.
cmd: Command code.
buff: Pointer to the parameter depends on the command code. Do not care if no parameter to be passed.

Return Value

RES_OK (0): The function succeeded.
RES_ERROR: An error occured.
RES_PARERR: The command code or parameter is invalid.
RES_NOTRDY: The device has not been initialized.

Description

The FatFs module requires only five device independent commands described below.

Standard ioctl command used by FatFs
Command	Description
CTRL_SYNC	Make sure that the device has finished pending write process. If the disk I/O module has a write back cache, the dirty buffers must be written back to the media immediately. Nothing to do for this command if each write operation to the media is completed within the `disk_write` function.
GET_SECTOR_COUNT	Returns number of available sectors on the drive into the `DWORD` variable pointed by `buff`. This command is used by only `f_mkfs` and `f_fdisk` function to determine the volume/partition size to be created. Required at `_USE_MKFS == 1` or `_MULTI_PARTITION == 1`.
GET_SECTOR_SIZE	Returns sector size of the device into the `WORD` variable pointed by `buff`. Valid return values of this command are 512, 1024, 2048 and 4096. This command is required only at variable sector size configuration, `_MAX_SS > _MIN_SS`. At the fixed sector size configuration, `_MAX_SS == _MIN_SS`, this command is not used and the device must work at that sector size.
GET_BLOCK_SIZE	Returns erase block size of the flash memory media in unit of sector into the `DWORD` variable pointed by `buff`. The allowable value is from 1 to 32768 in power of 2. Return 1 if the erase block size is unknown or non flash memory media. This command is used by only `f_mkfs` function and it attempts to align data area on the erase block boundary. Required at `_USE_MKFS == 1`.
CTRL_TRIM	Informs the device the data on the block of sectors is no longer needed and it can be erased. The sector block is specified by `DWORD` array {<start sector>, <end sector>} pointed by `buff`. This is an identical command to Trim of ATA device. Nothing to do for this command if this funcion is not supported or not a flash memory device. The FatFs does not check the result code and the file function is not affected even if the sector block was not erased well. This command is called on remove a cluster chain and in the `f_mkfs` function. Required at `_USE_TRIM == 1`.

FatFs never uses any device dependent command nor user defined command. Following table shows an example of non-standard commands usable for some applications.

Example of optional ioctl command
Command	Description
CTRL_FORMAT	Create a physical format on the media. If `buff` is not null, it is pointer to the call-back function for progress notification.
CTRL_POWER_IDLE	Put the device idle state. `STA_NOINIT` in the current status flags may not be set if the device goes active state by generic read/write function.
CTRL_POWER_OFF	Put the device off state. Shut-down the power to the device and deinitialize the device interface if needed. `STA_NOINIT` in the current status flags must be set. The device goes active state by `disk_initialize` function.
CTRL_LOCK	Lock media eject mechanism.
CTRL_UNLOCK	Unlock media eject mechanism.
CTRL_EJECT	Eject media cartridge. `STA_NOINIT` and `STA_NODISK` in status flag are set after the function succeeded.
MMC_GET_TYPE	Get card type. The type flags, bit0:MMCv3, bit1:SDv1, bit2:SDv2+ and bit3:LBA, is stored to a BYTE variable pointed by `buff`. (MMC/SDC specific command)
MMC_GET_CSD	Get CSD register into a 16-byte buffer pointed by `buff`. (MMC/SDC specific command)
MMC_GET_CID	Get CID register into a 16-byte buffer pointed by `buff`. (MMC/SDC specific command)
MMC_GET_OCR	Get OCR register into a 4-byte buffer pointed by `buff`. (MMC/SDC specific command)
MMC_GET_SDSTAT	Get SDSTATUS register into a 64-byte buffer pointed by `buff`. (SDC specific command)
ATA_GET_REV	Get the revision string into a 16-byte buffer pointed by `buff`. (ATA/CFC specific command)
ATA_GET_MODEL	Get the model string into a 40-byte buffer pointed by `buff`. (ATA/CFC specific command)
ATA_GET_SN	Get the serial number string into a 20-byte buffer pointed by `buff`. (ATA/CFC specific command)
ISDIO_READ	Read a block of iSDIO registers specified by command structure pointed by `buff`. (FlashAir specific command)
ISDIO_WRITE	Write a block of data to iSDIO registers specified by command structure pointed by `buff`. (FlashAir specific command)
ISDIO_MRITE	Change bits in an iSDIO register specified by command structure pointed by `buff`. (FlashAir specific command)

QuickInfo

The disk_ioctl function is not needed when _FS_READONLY == 1 and _MAX_SS == _MIN_SS.