Copyright (c) Hyperion Entertainment and contributors.
Difference between revisions of "DiskIO Library"
Steven Solie (talk | contribs) (Created page with "Disk I/O Library is a higher level API for disk/partition I/I that automatically takes care of most technical details like getting the correct device name, unit and flags to...") |
Steven Solie (talk | contribs) |
||
| (One intermediate revision by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | Disk I/O Library is a higher level API for disk/partition I/ |
+ | Disk I/O Library is a higher level API for disk/partition I/O that automatically takes care of most technical details. Details like: |
| − | unit and flags to call OpenDevice() |
+ | * getting the correct device name, unit and flags to call OpenDevice() |
| + | * checking that it's of the correct type and what commands to use |
||
| − | type and what commands to use and calculating the disk/partition |
||
| − | dimensions based on the |
+ | * calculating the disk/partition dimensions based on the DosEnvec structure and TD_GETGEOMETRY (if de_LowCyl is zero). |
| − | de_LowCyl is zero). As an additional safety measures it also checks that |
||
| − | all read and write accesses are within partition bounds and immediately |
||
| − | fails them if they are not. |
||
| + | As an additional safety measures it also checks that all read and write accesses are within partition bounds and immediately fails them if they are not. |
||
| − | Other than that it has functions that allow reading and writing data |
||
| − | that is not block aligned or a multiple of the block size and it has a |
||
| − | built-in block cache. |
||
| + | Disk I/O Library has functions that allow reading and writing data that is not block aligned or a multiple of the block size and it has a built-in block cache. |
||
| − | The functions themselves should be simple use and are described in the |
||
| − | autodoc. |
||
| + | The functions themselves should be simple use and are described in the autodoc. |
||
| − | The Setup() function is called to get the disk i/o handle. This just |
||
| − | takes a device/volume name, which is used to find the device node and |
||
| − | from there all the other necessary data, and an optional taglist |
||
| − | specifying additional parameters. |
||
| + | The Setup() function is called to get the disk i/o handle. This takes a device/volume name, which is used to find the device node and from there all the other necessary data, and an optional taglist specifying additional parameters. |
||
| − | After Setup(), Query() should be used to get information on the |
||
| − | disk/partition and whether there is a storage medium available at all. |
||
| + | After Setup(), Query() should be used to get information on the disk/partition and whether there is a storage medium available at all. |
||
| − | Reading and writing is done through ReadBytes/-Blocks() |
||
| − | WriteBytes/-Blocks() and the write cache is flushed to disk by using |
||
| − | FlushIOCache() (this also calls CMD_UPDATE to flush the device driver's |
||
| − | write cache if there is one). |
||
| + | Reading and writing is done through ReadBytes/ReadBlocks(). WriteBytes/WriteBlocks() and the write cache is flushed to disk by using FlushIOCache() (this also calls CMD_UPDATE to flush the device driver's write cache if there is one). |
||
| − | And when all is done Cleanup() is called to get rid of the disk i/o |
||
| − | handle (this also automatically flushes the write cache if any). |
||
| + | When all is done Cleanup() is called to get rid of the disk I/O handle (this also automatically flushes the write cache if any). |
||
| − | Some other functions I skipped are |
||
| − | AddDiskChangeHandler()/RemDiskChangeHandler() which make it very simple |
||
| − | to add a disk change handler. As with Setup() all that is needed is a |
||
| − | device/volume name and all the messy low level details are hidden. |
||
| + | AddDiskChangeHandler()/RemDiskChangeHandler() make it simple to add a disk change handler. As with Setup() all that is needed is a device/volume name and all the low level details are hidden. |
||
| − | The last noteworthy function is Update() which is used to make |
||
| − | diskio.library start accessing a new storage medium. It's called |
||
| − | implicitly the first time during Setup() and among other things takes |
||
| − | care of things like getting rid of the old block cache if any and |
||
| − | setting up a new one. None of the currently available filesystems use |
||
| − | this function because they create a new disk i/o handle every time a new |
||
| − | disk/medium is inserted. |
||
| + | Update() is used to make diskio.library start accessing a new storage medium. It's called implicitly the first time during Setup() and among other things takes care of things like getting rid of the old block cache if any and setting up a new one. The currently available file systems do not use this function because they create a new disk I/O handle every time a new disk/medium is inserted. |
||
| − | As far as examples go there is the code in ntfs-3g |
||
| + | |||
| − | (libntfs-3g/amiga_io.c) and exfat (libexfat/amiga_io.c) ports. |
||
| + | Example code is available in the NTFS-3G (libntfs-3g/amiga_io.c) and ExFAT (libexfat/amiga_io.c) ports. |
||
Latest revision as of 18:18, 16 October 2015
Disk I/O Library is a higher level API for disk/partition I/O that automatically takes care of most technical details. Details like:
- getting the correct device name, unit and flags to call OpenDevice()
- checking that it's of the correct type and what commands to use
- calculating the disk/partition dimensions based on the DosEnvec structure and TD_GETGEOMETRY (if de_LowCyl is zero).
As an additional safety measures it also checks that all read and write accesses are within partition bounds and immediately fails them if they are not.
Disk I/O Library has functions that allow reading and writing data that is not block aligned or a multiple of the block size and it has a built-in block cache.
The functions themselves should be simple use and are described in the autodoc.
The Setup() function is called to get the disk i/o handle. This takes a device/volume name, which is used to find the device node and from there all the other necessary data, and an optional taglist specifying additional parameters.
After Setup(), Query() should be used to get information on the disk/partition and whether there is a storage medium available at all.
Reading and writing is done through ReadBytes/ReadBlocks(). WriteBytes/WriteBlocks() and the write cache is flushed to disk by using FlushIOCache() (this also calls CMD_UPDATE to flush the device driver's write cache if there is one).
When all is done Cleanup() is called to get rid of the disk I/O handle (this also automatically flushes the write cache if any).
AddDiskChangeHandler()/RemDiskChangeHandler() make it simple to add a disk change handler. As with Setup() all that is needed is a device/volume name and all the low level details are hidden.
Update() is used to make diskio.library start accessing a new storage medium. It's called implicitly the first time during Setup() and among other things takes care of things like getting rid of the old block cache if any and setting up a new one. The currently available file systems do not use this function because they create a new disk I/O handle every time a new disk/medium is inserted.
Example code is available in the NTFS-3G (libntfs-3g/amiga_io.c) and ExFAT (libexfat/amiga_io.c) ports.
