XIO_PACK(D3)

NAME
     XIO_PACK - build a packed XIO address
     XIO_PACKED - check if XIO address is packed
     XIO_PORT - extract port from packed XIO address
     XIO_ADDR - extract offset from packed XIO address
     XIO_NOWHERE - nonexistant XIO target

SYNOPSIS
     #include <sys/xtalk/xtalk.h>

     /*
     ** These are really macros, but
     ** if they were functions:
     */

     iopaddr_t
     XIO_PACK(xwidgetnum_t port, iopaddr_t offset)

     int
     XIO_PACKED(iopaddr_t xaddr)

     xwidgetnum_t
     XIO_PORT(iopaddr_t xaddr)

     iopaddr_t
     XIO_ADDR(iopaddr_t xaddr)

     iopaddr_t XIO_NOWHERE;

   Arguments
     offset  is an appropriate 48-bit XIO address (offset).

     port    is a 4-bit XIO target port number.

     xaddr   is

DESCRIPTION
     XIO_PACK() merges an XIO target port number with the XIO target address
     offset into a single number that can be efficiently passed and returned.

     XIO_PACKED() returns nonzero if the parameter is a packed XIO address, or
     zero if the parameter represents an offset, and the XIO target must be
     inferred by the device driver (which should use its assigned XIO "master"
     port).

     XIO_PORT() extracts the target port number from a packed address.

     XIO_ADDR() extracts the target address from a packed address.

     XIO_NOWHERE is a constant containing a packed XIO address that represents
     an impossible DMA target.
     The most common use of packed addresses is when XIO DMA target
     translation results are returned, and it is expected that only rarely
     will packed addresses actually be used, since nearly all DMA is directed
     via the device's assigned master port to system memory.  However, it is
     advised that all drivers using xtalk_dma services watch for and handle
     packed addresses.

     There are a number of objects in the system which the CPU can directly
     access, but which devices can not access over the XIO bus.  While it is
     rare to see XIO_PACKED addresses, it should be even more rare to see
     XIO_NOWHERE; this represents either a programming error in the device
     driver, or an attempt by a user to initiate DMA somewhere silly.

EXAMPLES
     The following is a contrived example of some interrupt code servicing a
     simple DMA engine on an XIO card.
          xaddr = xtalk_dmamap_addr(dmamap, paddr, size);

          if (XIO_PACKED(xaddr)) {
               if (xaddr == XIO_NOWHERE)
                    goto fail;
               xport = XIO_PORT(xaddr);
               xaddr = XIO_ADDR(xaddr);
          } else
               xport = soft->master_port;

          regs->xaddr = xaddr;
          regs->xport = port;
          regs->bytes = size;
          regs->command = DMA_GO;

NOTES
     Backward compatibility dictates the format of the unpacked address:  it
     must be a bare offset, and implicitly refers to a particular device's XIO
     master device, assigned previously.  The most convenient encoding to use
     for packed XIO addresses results in packed addresses to IO port 0 being
     undifferentiable from unpacked values.  This results in the limitation
     that setting up peer-to-peer DMA to XIO widget 0 is not possible; this
     restriction is acceptable, since the device answering at XIO widget 0 is
     not a reasonable DMA target.

SEE ALSO
     xtalk_dma(D3)