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>Christian Groessler, <htmlurl url="mailto:cpg@aladdin.de" name="cpg@aladdin.de">
   6 <date>21.11.2000
   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 drive 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 (driveid_t drive_id);
  26 </verb></tscreen>
  27
  28 The <tt>drive_id</tt> specifies the drive to access, with 0 being the first
  29 disk drive, 1 the second, and so on.
  30
  31 <tscreen><verb>
  32     unsigned char __fastcall__ dio_close (dhandle_t handle);
  33 </verb></tscreen>
  34
  35 Closes a handle obtained by <tt>dio_open</tt>. Returns status code.
  36 <p>
  37
  38 <sect>Reading and writing sectors<p>
  39
  40 The read and write functions are:
  41
  42 <tscreen><verb>
  43     unsigned char __fastcall__ dio_read (dhandle_t handle,
  44                                          sectnum_t sect_num,
  45                                          void *buffer);
  46 </verb></tscreen>
  47
  48 This function will read the sector specified by sect_num into the memory
  49 location at buffer.
  50
  51 <tscreen><verb>
  52     unsigned char __fastcall__ dio_write (dhandle_t handle,
  53                                           sectnum_t sect_num,
  54                                           const void *buffer);
  55 </verb></tscreen>
  56
  57 This function will write the memory contents at buffer to the sector specified
  58 by <tt>sect_num</tt>. No verify is performed.
  59
  60 <tscreen><verb>
  61     unsigned char __fastcall__ dio_write_verify (dhandle_t handle,
  62                                                  sectnum_t sect_num,
  63                                                  const void *buffer);
  64 </verb></tscreen>
  65
  66 This function will write the memory contents at buffer to the sector specified
  67 by <tt>sect_num</tt>. A verification is performed.
  68 <p>
  69
  70 All these functions will return 0 for success and an OS specific error code in
  71 case of failure.
  72 <p>
  73
  74
  75 <sect>Converting sector numbers<p>
  76
  77 Since the read and write functions expect a sector number, for systems where
  78 the sectors aren't addressed by a logical sector number (e.g. CBM drives),
  79 there are 2 conversion functions. One of them converts a logical sector number
  80 to a head/track/sector triple. The other conversion function works the other
  81 way round.
  82
  83 <tscreen><verb>
  84     unsigned char __fastcall__ dio_phys_to_log (dhandle_t handle,
  85                                                 const dio_phys_pos *physpos,
  86                                                 sectnum_t *sectnum);
  87 </verb></tscreen>
  88
  89 This function converts track/head/sector to logical sector number.
  90
  91 <tscreen><verb>
  92     unsigned char __fastcall__ dio_log_to_phys (dhandle_t handle,
  93                                                 const _sectnum_t *sectnum,
  94                                                 dio_phys_pos *physpos);
  95 </verb></tscreen>
  96
  97 This function converts a logical sector number to track/head/sector notation.
  98 <p>
  99
 100 Note, that on systems which natively use logical sector numbers (e.g. Atari),
 101 the conversion functions are dummies. They ignore head/track
 102 (<tt>dio_phys_to_log</tt>) or return them as zero (<tt>dio_log_to_phys</tt>).
 103 The logical sector number is returned as physical sector and vice versa.
 104 <p>
 105
 106
 107 </article>
 108
 109
 110