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 the command has 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	Makes sure that the device has finished pending write process. If the disk I/O layer or storage device has a write-back cache, the dirty cache data must be committed to the medium immediately. Nothing to do for this command if each write operation to the medium is completed in the `disk_write` function.
GET_SECTOR_COUNT	Retrieves number of available sectors, the largest allowable LBA + 1, on the drive into the `LBA_t` variable that pointed by `buff`. This command is used by `f_mkfs` and `f_fdisk` function to determine the size of volume/partition to be created.
GET_SECTOR_SIZE	Retrieves sector size, minimum data unit for generic read/write, into the `WORD` variable that pointed by `buff`. Valid sector sizes are 512, 1024, 2048 and 4096. This command is required only if `FF_MAX_SS > FF_MIN_SS`. When `FF_MAX_SS == FF_MIN_SS`, this command will never be used and the `disk_read` and `disk_write` function must work in `FF_MAX_SS` bytes/sector.
GET_BLOCK_SIZE	Retrieves erase block size in unit of sector of the flash memory media into the `DWORD` variable that pointed by `buff`. The allowable value is 1 to 32768 in power of 2. Return 1 if it is unknown or in non flash memory media. This command is used by `f_mkfs` function with block size not specified and it attempts to align the data area on the suggested block boundary. Note that FatFs does not have FTL (flash translation layer), so that either disk I/O layter or storage device must have an FTL in it.
CTRL_TRIM	Informs the disk I/O layter or the storage device that the data on the block of sectors is no longer needed and it can be erased. The sector block is specified in an `LBA_t` array `{<Start LBA>, <End LBA>}` that 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. 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. It is required when `FF_USE_TRIM == 1`.

FatFs will never use any device dependent command nor user defined command. Following table shows an example of non-standard commands which may be useful for some applications.

Example of optional ioctl command
Command	Description
CTRL_FORMAT	Creates 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	Puts 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	Puts 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	Locks media eject mechanism.
CTRL_UNLOCK	Unlocks media eject mechanism.
CTRL_EJECT	Ejects media cartridge. `STA_NOINIT` and `STA_NODISK` in status flag are set after the function succeeds.
CTRL_GET_SMART	Reads SMART information.
MMC_GET_TYPE	Gets 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	Reads CSD register and sets it into a 16-byte buffer pointed by `buff`. (MMC/SDC specific command)
MMC_GET_CID	Reads CID register and sets it into a 16-byte buffer pointed by `buff`. (MMC/SDC specific command)
MMC_GET_OCR	Reads OCR register and sets it into a 4-byte buffer pointed by `buff`. (MMC/SDC specific command)
MMC_GET_SDSTAT	Reads SDSTATUS register and sets it into a 64-byte buffer pointed by `buff`. (SDC specific command)
ATA_GET_REV	Reads the revision string and sets it into a 16-byte buffer pointed by `buff`. (ATA/CFC specific command)
ATA_GET_MODEL	Reads the model string and sets it into a 40-byte buffer pointed by `buff`. (ATA/CFC specific command)
ATA_GET_SN	Reads the serial number string and sets it into a 20-byte buffer pointed by `buff`. (ATA/CFC specific command)
ISDIO_READ	Reads a block of iSDIO registers specified by command structure pointed by `buff`. (FlashAir specific command)
ISDIO_WRITE	Writes a block of data to iSDIO registers specified by command structure pointed by `buff`. (FlashAir specific command)
ISDIO_MRITE	Changes bits in an iSDIO register specified by command structure pointed by `buff`. (FlashAir specific command)

QuickInfo

The disk_ioctl function is not needed when FF_FS_READONLY == 1 and FF_MAX_SS == FF_MIN_SS.