git.sur5r.net Git - cc65/blob - doc/dio.sgml

   1 <!doctype linuxdoc system>
   2
   3 <article>
   4 <title>Diskette Sector I/O Routines
   5 <author><url url="mailto:chris@groessler.org" name="Christian Groessler">
   6
   7 <abstract>
   8 The cc65 library provides functions to read and write raw disk sectors.
   9 Include the dio.h header file to get the necessary definitions.
  10 </abstract>
  11
  12 <!-- Table of contents -->
  13 <toc>
  14
  15 <!-- Begin the document -->
  16
  17 <sect>Opening the disk for low level I/O<p>
  18
  19 Prior to using these functions a handle to the device has to be obtained. This
  20 is done with the <tt>dio_open</tt> function. After use, the handle should be
  21 released with the <tt>dio_close</tt> function.
  22
  23 <tscreen><verb>
  24     dhandle_t __fastcall__ dio_open (unsigned char device);
  25 </verb></tscreen>
  26
  27 The <tt>device</tt> specifies the device to access.
  28
  29 <tscreen><verb>
  30     unsigned char __fastcall__ dio_close (dhandle_t handle);
  31 </verb></tscreen>
  32
  33 Closes a handle obtained by <tt>dio_open</tt>. Returns status code.
  34 <p>
  35
  36 <sect>Reading and writing sectors<p>
  37
  38 The read and write functions are:
  39
  40 <tscreen><verb>
  41     unsigned char __fastcall__ dio_read (dhandle_t handle,
  42                                          unsigned sect_num,
  43                                          void *buffer);
  44 </verb></tscreen>
  45
  46 This function will read the sector specified by <tt>sect_num</tt> into the memory
  47 location at buffer.
  48
  49 <tscreen><verb>
  50     unsigned char __fastcall__ dio_write (dhandle_t handle,
  51                                           unsigned sect_num,
  52                                           const void *buffer);
  53 </verb></tscreen>
  54
  55 This function will write the memory contents at buffer to the sector specified
  56 by <tt>sect_num</tt>. No verify is performed.
  57
  58 <tscreen><verb>
  59     unsigned char __fastcall__ dio_write_verify (dhandle_t handle,
  60                                                  unsigned sect_num,
  61                                                  const void *buffer);
  62 </verb></tscreen>
  63
  64 This function will write the memory contents at buffer to the sector specified
  65 by <tt>sect_num</tt>. A verification is performed.
  66 <p>
  67
  68 Use the <tt><ref name="dio_query_sectsize" id="sectsizecount"></tt> function to query
  69 the size of a sector and the <tt><ref name="dio_query_sectcount" id="sectsizecount"></tt>
  70 function to query the number of available sectors.
  71 <p>
  72
  73 All these functions will return 0 for success and an OS specific error code in
  74 case of failure.
  75 <p>
  76
  77 <sect>Querying sector size and count<label id="sectsizecount"><p>
  78
  79 Some systems support multiple diskette formats which have different sector sizes
  80 and/or different sector counts.
  81 <p>
  82
  83 The following function returns the sector size of the currently inserted disk:
  84
  85 <tscreen><verb>
  86     unsigned __fastcall__ dio_query_sectsize (dhandle_t handle);
  87 </verb></tscreen>
  88
  89 On the Atari platform, the sector size is handled specially. Please refer
  90 to the DIO section in the <url url="atari.html" name="Atari-specific
  91 platform documentation">.
  92 <p>
  93
  94 The following function returns the sector count of the currently inserted disk:
  95
  96 <tscreen><verb>
  97     unsigned __fastcall__ dio_query_sectcount (dhandle_t handle);
  98 </verb></tscreen>
  99
 100 <sect>Converting sector numbers<p>
 101
 102 Since the read and write functions expect a sector number, for systems where
 103 the sectors aren't addressed by a logical sector number (e.g. CBM devices),
 104 there are 2 conversion functions. One of them converts a logical sector number
 105 to a head/track/sector triple. The other conversion function works the other
 106 way round.
 107
 108 <tscreen><verb>
 109     unsigned char __fastcall__ dio_phys_to_log (dhandle_t handle,
 110                                                 const dio_phys_pos *physpos,
 111                                                 unsigned *sectnum);
 112 </verb></tscreen>
 113
 114 This function converts track/head/sector to logical sector number.
 115
 116 <tscreen><verb>
 117     unsigned char __fastcall__ dio_log_to_phys (dhandle_t handle,
 118                                                 const unsigned *sectnum,
 119                                                 dio_phys_pos *physpos);
 120 </verb></tscreen>
 121
 122 This function converts a logical sector number to track/head/sector notation.
 123 <p>
 124
 125 Note, that on systems which natively use logical sector numbers (e.g. Atari),
 126 the conversion functions are dummies. They ignore head/track
 127 (<tt>dio_phys_to_log</tt>) or return them as zero (<tt>dio_log_to_phys</tt>).
 128 The logical sector number is returned as physical sector and vice versa.
 129 <p>
 130
 131
 132 </article>