Difference between revisions of "83Plus:Software:usb8x/Asm Interface/MSD"

From WikiTI
Jump to: navigation, search
m
m (fixing links broken during trasnfer/upgrade, may need more work IDK, they work now)
 
(12 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
The mass storage driver works through a series of U_CALL entry points, much like the HID driver.
 
The mass storage driver works through a series of U_CALL entry points, much like the HID driver.
  
It requires two RAM buffers, one for internal use and one for a sector buffer. File handles used for opened files (explained later) also require around 27 bytes. The size of all three of these buffers can be obtained through the [[/MSDVersion|MSDVersion]] U_CALL. The size of the internal buffer is typically 254 bytes and the sector buffer is 512 bytes.
+
It requires two RAM buffers, one for internal use and one for a sector buffer. File handles used for opened files (explained later) also require around 27 bytes. The size of all three of these buffers can be obtained through the [[83Plus:Software:usb8x/Asm_Interface/MSD/MSDVersion|MSDVersion]] U_CALL. The size of the internal buffer is typically 254 bytes and the sector buffer is 512 bytes.
  
The entry point which requires these buffers is the [[/MSD_Initialize|MSD_Initialize]] U_CALL. Its memory can be dynamically allocated to appBackUpScreen (taking up practically all of it) with the code below:
+
The entry point which requires these buffers is the [[83Plus:Software:usb8x/Asm_Interface/MSD/MSD_Initialize|MSD_Initialize]] U_CALL. Its memory can be dynamically allocated to appBackUpScreen (taking up practically all of it) with the code below:
  
 
<code>
 
<code>
Line 15: Line 15:
 
</code>
 
</code>
  
For file system operations, you will then make calls to [[/UFI_Initialize|UFI_Initialize]] and [[/FAT_Initialize|FAT_Initialize]]. All entry points will return with the carry flag set if there are problems, with more detailed information in offErrorCode.
+
For file system operations, you will then make calls to [[83Plus:Software:usb8x/Asm_Interface/MSD/UFI_Initialize|UFI_Initialize]] and [[83Plus:Software:usb8x/Asm_Interface/MSD/FAT_Initialize|FAT_Initialize]]. All entry points will return with the carry flag set if there are problems, with more detailed information available via [[83Plus:Software:usb8x/Asm_Interface/MSD/GetErrorCode|GetErrorCode]].
  
 
No knowledge of the intimate details of FAT16 are required. However, the "starting cluster" of a directory is used in several routines. This is a 16-bit number uniquely indentifying a directory. It is beneficial to use this number rather than an extremely long ASCIIZ directory path which wastes memory. It is easily obtained with [[/FAT_getStartingCluster|FAT_getStartingCluster]] by passing an ASCIIZ directory path to it.
 
No knowledge of the intimate details of FAT16 are required. However, the "starting cluster" of a directory is used in several routines. This is a 16-bit number uniquely indentifying a directory. It is beneficial to use this number rather than an extremely long ASCIIZ directory path which wastes memory. It is easily obtained with [[/FAT_getStartingCluster|FAT_getStartingCluster]] by passing an ASCIIZ directory path to it.
 
If all three of the initializing U_CALLs succeed, the following entry points can then be called.
 
  
 
== Entry Points ==
 
== Entry Points ==
 +
 +
If all three of the initializing U_CALLs succeed, the other following entry points can then be called.
  
 
{| border="1" cellpadding="2"  cellspacing="0"  
 
{| border="1" cellpadding="2"  cellspacing="0"  
 
|-
 
|-
| [[/MSDVersion|MSDVersion]] || Gets mass storage driver version and memory requirements
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/MSDVersion|MSDVersion]] || Gets mass storage driver version and memory requirements
 
|-
 
|-
| [[/MSD_Initialize|MSD_Initialize]] || Initializes mass storage driver
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/MSD_Initialize|MSD_Initialize]] || Initializes mass storage driver
 
|-
 
|-
| [[/UFI_Initialize|UFI_Initialize]] || Initializes connected mass storage device for sector read/write operations
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/UFI_Initialize|UFI_Initialize]] || Initializes connected mass storage device for sector read/write operations
 
|-
 
|-
| [[/UFI_Read|UFI_Read]] || Reads sector at (MSDLBA) address into sector buffer
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/UFI_getCapacity|UFI_getCapacity]] || Gets capacity of entire drive and sets up bytes-per-sector
 
|-
 
|-
| [[/UFI_Write|UFI_Write]] || Writes memory in sector buffer to (MSDLBA) address
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/UFI_Read|UFI_Read]] || Reads sector at (MSDLBA) address into sector buffer
 
|-
 
|-
| [[/FAT_Initialize|FAT_Initialize]] || Initializes connected mass storage device for FAT16 file system operations
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/UFI_Write|UFI_Write]] || Writes memory in sector buffer to (MSDLBA) address
 
|-
 
|-
| [[/DOS_openFile|DOS_openFile]] || Opens a file and populates file handle with important information
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/msdDetect|msdDetect]] || Detects and loads 83P/8XP levels based on detection string and specified directory
 
|-
 
|-
| [[/DOS_fileSeek|DOS_fileSeek]] || Sets seek pointer for file handle to specified offset
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/FAT_Initialize|FAT_Initialize]] || Initializes connected mass storage device for FAT16 file system operations
 
|-
 
|-
| [[/DOS_fileRead|DOS_fileRead]] || Read bytes from a file
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/DOS_openFile|DOS_openFile]] || Opens a file and populates file handle with important information
 
|-
 
|-
| [[/DOS_fileWrite|DOS_fileWrite]] || Write bytes to a file and grow if necessary
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/DOS_fileSeek|DOS_fileSeek]] || Sets seek pointer for file handle to specified offset
 
|-
 
|-
| [[/DOS_createFile|DOS_createFile]] || Create new file in specified directory with size 0
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/DOS_fileRead|DOS_fileRead]] || Read bytes from a file
 
|-
 
|-
| [[/DOS_createDirectory|DOS_createDirectory]] || Create new subdirectory in specified directory
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/DOS_fileWrite|DOS_fileWrite]] || Write bytes to a file and grows it if necessary
 
|-
 
|-
| [[/DOS_renameFileEntry|DOS_renameFileEntry]] || Rename specified file or folder
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/DOS_updateAttributes|DOS_updateAttributes]] || Update "last modified" date/time and other attributes
 
|-
 
|-
| [[/DOS_deleteFileEntry|DOS_deleteFileEntry]] || Delete file or folder (including contents)
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/DOS_createFile|DOS_createFile]] || Create new file in specified directory with size 0
 
|-
 
|-
| [[/DOS_countFilesInDir|DOS_countFilesInDir]] || Get number of files/folders in specified directory
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/DOS_createDirectory|DOS_createDirectory]] || Create new subdirectory in specified directory
 
|-
 
|-
| [[/DOS_getNextFile|DOS_getNextFile]] || Get first/next file in specified directory
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/DOS_renameFileEntry|DOS_renameFileEntry]] || Rename specified file or folder
 
|-
 
|-
| [[/DOS_getFileSize|DOS_getFileSize]] || Get size of file
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/DOS_deleteFileEntry|DOS_deleteFileEntry]] || Delete file or folder (including contents)
 
|-
 
|-
| [[/DOS_getDirEntry|DOS_getDirEntry]] || Get directory entry for specified file/folder
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/DOS_countFilesInDir|DOS_countFilesInDir]] || Get number of files/folders in specified directory
 
|-
 
|-
| [[/FAT_nameConvertTo11|FAT_nameConvertTo11]] || Convert name to 11-character format (ex. "<code>README  TXT</code>")
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/DOS_getNextFile|DOS_getNextFile]] || Get first/next file in specified directory
 
|-
 
|-
| [[/FAT_nameConvertFrom11|FAT_nameConvertFrom11]] || Convert name to ASCIIZ format (ex. "readme.txt")
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/DOS_getFileSize|DOS_getFileSize]] || Get size of file
 
|-
 
|-
| [[/FAT_lookupPath|FAT_lookupPath]] || Find whether specified file/directory exists
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/DOS_getDirEntry|DOS_getDirEntry]] || Get directory entry for specified file/folder
 
|-
 
|-
| [[/FAT_findFileInCluster|FAT_findFileInCluster]] || Get directory entry for a file in specified folder
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/FAT_nameConvertTo11|FAT_nameConvertTo11]] || Convert name to 11-character format (ex. "<code>README  TXT</code>")
 
|-
 
|-
| [[/FAT_getStartingCluster|FAT_getStartingCluster]] || Get starting cluster of specified directory
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/FAT_nameConvertFrom11|FAT_nameConvertFrom11]] || Convert name to ASCIIZ format (ex. "readme.txt")
 
|-
 
|-
| [[/MSD_ImportVariable|MSD_ImportVariable]] || Imports 8x* file as calculator variable in RAM/Flash
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/FAT_lookupPath|FAT_lookupPath]] || Find whether specified file/directory exists
 
|-
 
|-
| [[/MSD_ExportVariable|MSD_ExportVariable]] || Exports calculator variable in RAM/Flash as 8x* file in specified directory
+
| [[83Plus:Software:usb8x/Asm_Interface/MSD/FAT_findFileInCluster|FAT_findFileInCluster]] || Get directory entry for a file in specified folder
 +
|-
 +
| [[83Plus:Software:usb8x/Asm_Interface/MSD/FAT_getStartingCluster|FAT_getStartingCluster]] || Get starting cluster of specified directory
 +
|-
 +
| [[83Plus:Software:usb8x/Asm_Interface/MSD/MSD_ImportVariable|MSD_ImportVariable]] || Imports 8x* file in specified directory as calculator variable in RAM/Flash
 +
|-
 +
| [[83Plus:Software:usb8x/Asm_Interface/MSD/MSD_ExportVariable|MSD_ExportVariable]] || Exports calculator variable in RAM/Flash as 8x* file in specified directory
 
|}
 
|}
 +
 +
== Other File Systems ==
 +
 +
You can use the [[83Plus:Software:usb8x/Asm_Interface/MSD/MSD_Initialize|MSD_Initialize]], [[83Plus:Software:usb8x/Asm_Interface/MSD/UFI_getCapacity|UFI_getCapacity]], [[83Plus:Software:usb8x/Asm_Interface/MSD/UFI_Read|UFI_Read]], and [[83Plus:Software:usb8x/Asm_Interface/MSD/UFI_Write|UFI_Write]] entry points to create your own file system driver. For example, you could create a driver for ext2/3, FAT32, or any other file system imaginable.
 +
 +
The low-level parts of the mass storage driver work by reading and writing sectors to the drive based on the current LBA address. This is located in (MSDLBA) in the mass storage driver's memory. To create your own file system driver, you will need to implement all of the details specific to that file system.
 +
 +
The [[83Plus:Software:usb8x/Asm_Interface/MSD/MSD_Initialize|MSD_Initialize]] entry point is required for any communication with the drive. When this entry point succeeds, you would then call [[83Plus:Software:usb8x/Asm_Interface/MSD/UFI_getCapacity|UFI_getCapacity]] to set up (MSDBPS) in the driver memory. This is necessary for the [[83Plus:Software:usb8x/Asm_Interface/MSD/UFI_Read|UFI_Read]] and [[83Plus:Software:usb8x/Asm_Interface/MSD/UFI_Write|UFI_Write]] entry points to succeed.
 +
 +
Once both entry points succeed, you are free to read and write as much as you like. The boot sector is located at LBA address 0x00000000. Most file systems require that you read this first to find out what to do next. Check out the mass storage driver in the usb8x source for more information.

Latest revision as of 20:02, 17 February 2009

The mass storage driver works through a series of U_CALL entry points, much like the HID driver.

It requires two RAM buffers, one for internal use and one for a sector buffer. File handles used for opened files (explained later) also require around 27 bytes. The size of all three of these buffers can be obtained through the MSDVersion U_CALL. The size of the internal buffer is typically 254 bytes and the sector buffer is 512 bytes.

The entry point which requires these buffers is the MSD_Initialize U_CALL. Its memory can be dynamically allocated to appBackUpScreen (taking up practically all of it) with the code below:

U_CALL MSDVersion
ld de,appBackUpScreen
push de
add hl,de
ex de,hl
pop hl
U_CALL MSD_Initialize

For file system operations, you will then make calls to UFI_Initialize and FAT_Initialize. All entry points will return with the carry flag set if there are problems, with more detailed information available via GetErrorCode.

No knowledge of the intimate details of FAT16 are required. However, the "starting cluster" of a directory is used in several routines. This is a 16-bit number uniquely indentifying a directory. It is beneficial to use this number rather than an extremely long ASCIIZ directory path which wastes memory. It is easily obtained with FAT_getStartingCluster by passing an ASCIIZ directory path to it.

Entry Points

If all three of the initializing U_CALLs succeed, the other following entry points can then be called.

MSDVersion Gets mass storage driver version and memory requirements
MSD_Initialize Initializes mass storage driver
UFI_Initialize Initializes connected mass storage device for sector read/write operations
UFI_getCapacity Gets capacity of entire drive and sets up bytes-per-sector
UFI_Read Reads sector at (MSDLBA) address into sector buffer
UFI_Write Writes memory in sector buffer to (MSDLBA) address
msdDetect Detects and loads 83P/8XP levels based on detection string and specified directory
FAT_Initialize Initializes connected mass storage device for FAT16 file system operations
DOS_openFile Opens a file and populates file handle with important information
DOS_fileSeek Sets seek pointer for file handle to specified offset
DOS_fileRead Read bytes from a file
DOS_fileWrite Write bytes to a file and grows it if necessary
DOS_updateAttributes Update "last modified" date/time and other attributes
DOS_createFile Create new file in specified directory with size 0
DOS_createDirectory Create new subdirectory in specified directory
DOS_renameFileEntry Rename specified file or folder
DOS_deleteFileEntry Delete file or folder (including contents)
DOS_countFilesInDir Get number of files/folders in specified directory
DOS_getNextFile Get first/next file in specified directory
DOS_getFileSize Get size of file
DOS_getDirEntry Get directory entry for specified file/folder
FAT_nameConvertTo11 Convert name to 11-character format (ex. "README TXT")
FAT_nameConvertFrom11 Convert name to ASCIIZ format (ex. "readme.txt")
FAT_lookupPath Find whether specified file/directory exists
FAT_findFileInCluster Get directory entry for a file in specified folder
FAT_getStartingCluster Get starting cluster of specified directory
MSD_ImportVariable Imports 8x* file in specified directory as calculator variable in RAM/Flash
MSD_ExportVariable Exports calculator variable in RAM/Flash as 8x* file in specified directory

Other File Systems

You can use the MSD_Initialize, UFI_getCapacity, UFI_Read, and UFI_Write entry points to create your own file system driver. For example, you could create a driver for ext2/3, FAT32, or any other file system imaginable.

The low-level parts of the mass storage driver work by reading and writing sectors to the drive based on the current LBA address. This is located in (MSDLBA) in the mass storage driver's memory. To create your own file system driver, you will need to implement all of the details specific to that file system.

The MSD_Initialize entry point is required for any communication with the drive. When this entry point succeeds, you would then call UFI_getCapacity to set up (MSDBPS) in the driver memory. This is necessary for the UFI_Read and UFI_Write entry points to succeed.

Once both entry points succeed, you are free to read and write as much as you like. The boot sector is located at LBA address 0x00000000. Most file systems require that you read this first to find out what to do next. Check out the mass storage driver in the usb8x source for more information.