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