Best guide for JMP CIOV docs

[+Stephen]

Title says it - what is the best recommended guide for looking at existing 6502 code, and determining what the JSR CIOV calls do?  I've looked through De Re Atari but it only has one or two examples.  I assume the OS source manuals?

[phaeron]

Do you want to see what's going on inside of CIO, or what the program calling it is doing? The OS manual (not the source listing) will give you the best insight on the CIO interface itself and what the various commands mean. If you want to see what a program is doing through CIO, you can use ".tracecio on" in Altirra's debugger to log the CIO commands as they are issued.

 

[tschak909]

I'll try to explain as succinctly as possible:

Basically, every call to CIOV is of exactly the same pattern:

 

* Set X register to the IOCB, e.g. $10 for IOCB #1, $20 for IOCB #2, etc. This is because each IOCB entry is 16 bytes long.

* Set the IOCB parameters

* JSR CIOV

 

On exit, Y will contain the error, > 127 = error.

 

Basically, each IOCB is of the form:

+0 = Handler index #, 0xFF if free (ICHID)

+1 = Device # (drive) (ICDNO)

+2 = IOCB command (ICCOM)

+3 = status of last operation (ICSTA)

+4 = ICBAL (the buffer address, low byte)

+5 = ICBAH (the buffer address, high byte)

+6 = ICPTL (The address to put byte routine, Atari Basic uses this)

+7 = ICPTH (the address to the put byte routine, ...)

+8 = ICBLL (Buffer length, low byte)

+9 = ICBLH (Buffer Length, high byte)

+10 - +15 = ICAXx (The Aux bytes, 0 to 6, they say 6 is spare, but you can indeed use it as a sixth aux byte in handlers)

 

The X register and IOCB layout is set up so that you can use the indexed,X addressing mode to set parameters for an iocb, e.g. to open

 

        LDX #$10    ; IOCB #1
        LDA #$03	; OPEN
        STA	ICCOM,X	; Store into IOCB #1 command
        LDA <FNAME  ; Filename low byte
        STA ICBAL,X ; Store in ICBAL for IOCB #1
        LDA >FNAME  ; Filename high Byte
        STA ICBAH,X ; Store in ICBAH for IOCB #1
        JSR CIOV	; Do CIOV call
        
FN      .BYTE "D1:FOO.DAT",$9B

Table of CIO operations:

#define IOCB_OPEN        0x03  /* open */
#define IOCB_GETREC      0x05  /* get record */
#define IOCB_GETCHR      0x07  /* get character(s) */
#define IOCB_PUTREC      0x09  /* put record */
#define IOCB_PUTCHR      0x0B  /* put character(s) */
#define IOCB_CLOSE       0x0C  /* close */
#define IOCB_STATIS      0x0D  /* status */
#define IOCB_SPECIL      0x0E  /* special */
#define IOCB_DRAWLN      0x11  /* draw line */
#define IOCB_FILLIN      0x12  /* draw line with right fill */
#define IOCB_RENAME      0x20  /* rename disk file */
#define IOCB_DELETE      0x21  /* delete disk file */
#define IOCB_LOCKFL      0x23  /* lock file (set to read-only) */
#define IOCB_UNLOCK      0x24  /* unlock file */
#define IOCB_POINT       0x25  /* point sector */
#define IOCB_NOTE        0x26  /* note sector */
#define IOCB_GETFL       0x27  /* get file length */
#define IOCB_CHDIR_MYDOS 0x29  /* change directory (MyDOS) */
#define IOCB_MKDIR       0x2A  /* make directory (MyDOS/SpartaDOS) */
#define IOCB_RMDIR       0x2B  /* remove directory (SpartaDOS) */
#define IOCB_CHDIR_SPDOS 0x2C  /* change directory (SpartaDOS) */
#define IOCB_GETCWD      0x30  /* get current directory (MyDOS/SpartaDOS) */
#define IOCB_FORMAT      0xFE  /* format */

 

[Graham Dearsley]

And the OS user guide will give you the AUX codes to use for things like OPEN for input, output, append etc.

[Rybags]

OS manual for definition.

 

Examples, I can't really point anywhere much.

 

It's all fairly simple stuff.  The device specific SPECIAL commands will likely be documented by whatever Dos/handler/whatever provides them.

The built in ones - you're either doing GET/PUT character (0 buffer length) or filling/emptying a buffer.

You want to know the difference between Get/Put characters and record.  A record is terminated by the EOL character.

 

With DOSes probably the most important ones to grasp are NOTE/POINT and the methodology for opening and reading a disk directory.

[E474]

Hi,

 

    If you are using MAC/65, or something similar like ATASM, you could try the I/O macros in IOMAC.LIB.  

 

    I used some of them in DUMP1050 (I think) - the macros are defined in https://github.com/e474/DUMP1050/blob/master/DUMP1050/IOMAC.LIB - you're welcome to browse the rest of the files to see how they're used, and looking at the output of the assembler listings will show you the actual code generated.

 

   Hope this helps!

[+Stephen]

Thanks for all the replies guys.  Sounds like the OS manual will do just fine.  All I need to do at this point, is determine what existing code I have is doing and comment it.  This is really just a learning exercise for me and hopefully will get me into more involved coding in assembly.

[Graham Dearsley]

It is a pity that the OS user manual was never comprehensively updated for the XL/XE OS. There is a supplement but it doesn't cover everything.

There is also an internal document that describes the PBI and how it handles loading drivers into the space normally occupied by the floating point package, if you can find it, but it was never published officially.    

[drac030]

Here are few examples, the description is in Polish, but the code should be easy to comprehend:

 

http://atariki.krap.pl/index.php/Dostęp_do_plików

 

Some XIO are listed here:

 

http://atariki.krap.pl/index.php/Lista_funkcji_specjalnych_CIO_według_urządzeń

 

clicking on the link should transfer you to a page with some generic example code.

 

[+Larry]

Maybe too simplistic for your needs, but there was a really good CIO article in Analog.  I think around issue 13. Had a greenish cover, IIRC.  That was my first intro to CIO.  Bill Wilkinson might have done an Insight article on CIO, also.

[tschak909]

The CIO really is an excellent example of simple and elegant, both in terms of writing a device, and using them. Make a device, and if you can specify a devicespec in a program, it just works.

 

-Thom

[+Larry]

Here are the Insight Atari articles that I mentioned. From 1981, these were OCR'd, so there might be a few OCR errors. But as always from Bill, great info.

-Larry

Insight.zip