two 2 byte
transfers)
Figure 2-6. Data Transfer to a 16-Bit Micro Channel Device
o
2 3 system memory addressByte reversal done by the IOCC
(A,B,C AND D represent data in memory)
Note that byte reversal is automatically done
Data on the Micro Channel bus
A o Micro Channel memory
2 3
Figure 2-7. Data Transfer to a 32-Bit Micro Channel Device
2.5.7 Additional PIO Macro Information
In AIX version 3.1.5 and later, TWO versions of macros that provide access to the liD bus are provided in the < sys/ioacc.h > header file. A version of the macros without an X as the last character of their name has no error handling built into it and should be used in conjunction with the pioass.ist or setjmpx I clrjmpx services for handling I/O errors. (This version also exists in the earlier levels of AIX version 3.) A second version of I/O macros (which was added in the AIX 3.1.5 release) is denoted by an X in the last character of th~ir name,
has a low overhead error catching mechanism built into it. These macros provide an alternate mechanism for performing programmed liD by utilizing a very fast kernel mechanism for catching liD errors that occur during the programmed liD transfer. These macros return a 0 return value if no error occurred, or return a non-zero value if an error occurred during the lID transfer.
These macros utilize kernel routines that provide much faster exception handler setup than the setjmpx, clrjmpx exception catching services utilized by
pioassist. In many cases where a small amount of liD is performed at one time, this method will result in a much faster execution time due to the low exception catching setup mechanism utilized by each macro invocation. In other cases where there are large number of programmed liD macros used in a block of code, the pioassist mechanism used in conjunction with the macros without built-in error catching may result in better performance due to the utilization of a single exception handler for all programmed liD instructions contained within the block of code.
2.5.7.1 Macros performing programmed 110 writes
The first set of programmed I/O macros write the specified data to bus memory or bus I/O address space. The BUS_PUTC (put character) macro may also be used to write POS registers.
BUS_PUTL( long *ioaddr, long data)
Write the specified long value (data) to the supplied bus memory or bus I/O address (ioaddr) without error handling.
int BUS_PUTLX( long *ioaddr, long data)
Write the specified long value (data) to the supplied bus memory or bus I/O address (ioaddr) with built-in exception catching. The return value will be 0 for success, otherwise an error (exception) occurred during the transfer.
BUS_PUTS( short *ioaddr, short data)
Write the specified short value (data) to the supplied bus memory or bus I/O address (ioaddr) without error handling.
int BUS_PUTSX( short *ioaddr, ushort data)
Write the specified short value (data) to the supplied bus memory or bus I/O address (ioaddr) with built-in exception catching. The return value will be 0 for success, otherwise an error (exception) occurred during the transfer.
BUS_PUTC( char *ioaddr, char data)
Write the specified character value (data) to the supplied bus memory, bus I/O or POS address (ioaddr) without error handling.
int BUS_PUTCX( char *ioaddr, char data)
Write the specified character value (data) to the supplied bus memory, bus I/O or POS address (ioaddr) with built-in exception catching. The return value will be 0 for success, otherwise an error (exception) occurred during the transfer.
int BUS_PUTSTRX( char*ioaddr, char *saddr, int count)
Copy count bytes from memory specified by saddr to bus memory or bus I/O address starting atthe address specified by ioaddr with built-in exception catching. The return value will be 0 for success, otherwise an error (exception) occurred during the transfer.
2.5.7.2 Macros performing byte reversed 110 writes
int BUS_PUTLRX( long *ioaddr, long data)
Write the speCified long value (data) to the supplied bus memory or bus I/O address (ioaddr) in byte reversed format with built-in exception catching. The return value will be 0 for success, otherwise an error (exception) occurred during the transfer. Note: The 10CC (I/O controller) on the RISC System / 6000 automatically converts 32 bit transters from big end ian format on the system into little endian format as seen by the device, therefore this macro will undo this conversion. This macro should be used when the device or the data on the
device is stored in BIG ENDIAN format instead of the ususal LITTLE ENDIAN format found on most microchannel adapters.
int BUS _PUTSRX( short *ioaddr, short data)
Write the specified short value (data) to the supplied bus memory or bus I/O address (ioaddr) in byte reversed format with built-in exception catching. The return value will be
a
for success, otherwise an error (exception) occurred during the transfer. Note: The loee (I/O controller) on the RISC System / 6000 automatically converts 16 bit transters from big end ian format on the system into little end ian format as seen by the device, therefore this macro will undo this conversion. This macro should be used when the device or the data on the device is stored in BIG ENDIAN format instead of the ususal LITTLE ENDIAN format found on most microchannel adapters.2.5.7.3 Macros performing programmed
1/0reads
The following macros read the specified data from bus memory or bus I/O address space. The BUS_GETC (get character) macro may also be used to read POS registers.
long BUS _ GETL( long *ioaddr)
Read the specified long value from the supplied bus memory or I/O address (ioaddr). This macro is an expression.
int BUS_GETLX( long *ioaddr, long *data)
Reads the specified long value into the variable data from the supplied bus memory or I/O address (ioaddr) with built-in exception catching. The return value will be
a
for success, otherwise an error (exception) occurred during the transfer.short BUS _ GETS( short *ioaddr)
Reads the specified short value from the supplied bus memory or I/O address (ioaddr) without error handling. This macro is an expression.
int BUS_GETSX( short *ioaddr, short *data)
Reads the specified short value (data) from the supplied bus memory or I/O address (ioaddr) with built-in exception catching. The return value will be
a
forsuccess, otherwise an error (exception) occurred during the transfer.
char BUS_GETC(char *ioaddr)
Reads the specified character value (data) from the supplied bus memory, bus I/O or POS address (ioaddr) without error handling. This macro is an
expression.
int BUS_GETCX( char *ioaddr, char *data)
Reads the specified character value (data) from the supplied bus memory, bus I/O or POS address (ioaddr) with built-in exception catching. The return value will be
a
for success, otherwise an error (exception) occurred during the transfer.int BUS_GETSTRX( char *ioaddr, char *daddr, int count)
Copy count bytes from bus memory or bus 1/0 address starting at the address specified by ioaddr to memory starting at daddr with built-in exception catching. The return value will be 0 for success, otherwise an error (exception) occurred during the transfer.
2.5.7.4 Macros performing byte reversed 1/0 reads
int BUS_GETLRX( long *ioaddr, long *data)
Read the specified long value (data) from the supplied bus memory or bus 1/0 address (ioaddr) in byte reversed format with built-in exception catching. The return value will be 0 for success, otherwise an error (exception) occurred during the transfer. Note: The 10CC (I/O controller) on the RISC System I 6000 automatically converts 32 bit transters from little endian format on the device into big end ian format, therefore this macro will undo this conversion. This macro should be used when the device or the data on the device is stored in BIG ENDIAN format instead of the ususal LITTLE ENDIAN format found on most microchannel adapters.
int BUS_GETSRX( short *ioaddr, short data)
Write the specified short value (data) to the supplied bus memory or bus I/O address (ioaddr) in byte reversed format with built-in exception catching. The return value will be 0 for success, otherwise an error (exception) occurred during the transfer. Note: The 10CC (lID controller) on the RISC System I 6000 automatically converts 16 bit transters from little end ian format on the device into big endian format, therefore this macro will undo this conversion. This macro should be used when the device or the data on the device is stored in BIG ENDIAN format .instead of the ususal LITTLE ENDIAN format found on most microchannel adapters.
2.5.7.5 PIO Error Recovery Considerations
In general, all 1/0 operations must include provisions to handle detectible errors. Except for Programmable Option Select (POS) accesses, it is possible for all PIO operations to have a variety of synchronous errors. These generally require the device driver to support synchronous 1/0 error exception handling.
When utilizing the programmed I/O macros with built in exception catching, a non-zero return code indicates that an exception or error occurred during the operation. If the operation was a read, the contents of the destination data area are invalid. If the return code is non-zero it will have one of the exception values defined in < sys/except.h >. If the value is EXCEPT JO then the
exception is an error caused by programmed I/O and should be handled. If the return code is non-zero and not EXCEPT _10 some other error (usually a programming error) has occurred and an assert should be coded to stop the system and provide a dump. If the operation is to be retried, it should be retried up to PIO_RETRY _COUNT times (see < sys/except.h
».
If the operation still fails, it should be considered a permanent error and handled accordingly, usually by returning EIO to the caller of the device driver.POS operations, unlike other PIO operations, cannot detect synchronous 1/0 errors. It is suggested that device driver programmers implement an algorithm which reads back the data after a read or write and compares it to see if a simple data error occurred. If the data miscompares, the POS operation should
be retried, and the data read back again to see if the miscompare recurred.
This should be repeated up to PIO_RETRY_COUNT (see <sys/except.h»
times. If the operation still fails, it should be considered a permanent error and handled accordingly.
2.5.7.6 Programmed I/O Examples w/o error catching
Examples of typical Pia operations follow. To simplify the examples, error catching has been omitted, however must never be omitted in operational code.
When using these macros, ploassist or setJmpx kernel services should be used to catch and handle I/O errors. For more information on error handling of this type refer to Device Handler Error Recovery. I/O errors that are not handled by device drivers will cause a kernel exception to occur, resulting in a system crash. While error handling is required, error recovery is optional but strongly advised. Error recovery involves retrying the failing operations one or more times before shutting down the device.
Perform a 32-bit read of system bus I/O space at address Ox3FO.