Legacy Document

Inside Macintosh: Devices /

Chapter 5 - ADB Manager / ADB Manager Reference

ADB Manager Routines / Communicating Through the ADB

ADBOp

You can use the ADBOp function to send a command to an ADB device.

FUNCTION ADBOp (data: Ptr; compRout: ProcPtr; buffer: Ptr; 
                commandNum: Integer): OSErr;

data

A pointer to an optional data area.

compRout

A pointer to a completion routine.

buffer

A pointer to a variable-length data buffer. The first byte of the buffer must contain the buffer's length.

commandNum

A command number. The command number is a 1-byte value that encodes the command to be performed, the register the command refers to, and the desired action the target device should perform.

DESCRIPTION

The ADBOp function transmits over the bus the command byte whose value is given by the commandNum parameter. See Figure 5-2 on page 5-8 for the structure of this command byte. For a Listen command, the ADB Manager also transmits the data pointed to by the buffer parameter. Upon completion of a Talk command, the area pointed to by the buffer parameter contains the data returned by the ADB device. The ADBOp function executes only when the ADB would otherwise be idle; if the bus is busy, the command byte is held in a command queue. If the command queue is full, the ADBOp function returns an error and the command is not placed in the queue.

The length of the data buffer pointed to by the buffer parameter must be contained in its first byte (in the same manner that the first byte of a Pascal string contains the length of the string). The data buffer can include from 0 to 8 bytes of information. For a Listen command, the data buffer should contain any data to be sent to the device. For a Talk command, the contents of the data buffer are valid only on completion of the command. To verify that the Talk command is completed, you should provide a completion routine when you send the command to an ADB device or simply test the value of the first byte of the data buffer (which contains the length of the buffer).

The optional data area to which the data parameter points is intended for storage used by the completion routine pointed to by the compRout parameter. When you use ADBOp to send a command, you can optionally supply a completion routine as a parameter. See "ADB Command Completion Routines," beginning on page 5-47 for details on completion routines.

SPECIAL CONSIDERATIONS

The ADBOp function is always executed asynchronously. The result code returned by ADBOp indicates only whether the ADB command was successfully placed into the ADB command queue, not whether the command itself was successful. A method for interacting with the ADB bus synchronously is illustrated in "Communicating With ADB Devices," beginning on page 5-24.

ASSEMBLY-LANGUAGE INFORMATION

The ADB operation block contains some of the information required by the ADBOp function. You'll need to set up an ADB operation block only if you call ADBOp from assembly-language. (In Pascal, the ADB operation block is defined by the ADBOpBlock data type.)

The registers on entry and exit for ADBOp are

Registers on entry
A0	Address of a parameter block of type ADBOpBlock
D0	A command number
Registers on exit
D0	Result code

The parameter block whose address is passed in register A0 has this structure

:

-->	dataBuffPtr	Ptr	A pointer to a variable-length data buffer. The first byte of the buffer must contain the buffer's length.
-->	opServiceRtPtr	Ptr	A pointer to a completion routine.
-->	opDataAreaPtr	Ptr	A pointer to an optional data area.

RESULT CODES

noErr	0	No error
errADBOp	-1	Command queue is full. Retry command.

SEE ALSO

See Listing 5-2 on page 5-25 for an example of using the ADBOp function.