145 lines
3.4 KiB
Plaintext
145 lines
3.4 KiB
Plaintext
.TH XIO_PACK D3
|
|
.IX "\f4XIO_ADDR\f1(D3)"
|
|
.IX "\f4XIO_NOWHERE\f1(D3)"
|
|
.IX "\f4XIO_PACK\f1(D3)"
|
|
.IX "\f4XIO_PACKED\f1(D3)"
|
|
.IX "\f4XIO_PORT\f1(D3)"
|
|
.SH NAME
|
|
.nf
|
|
\f4XIO_PACK\f1 \- build a packed XIO address
|
|
\f4XIO_PACKED\f1 \- check if XIO address is packed
|
|
\f4XIO_PORT\f1 \- extract port from packed XIO address
|
|
\f4XIO_ADDR\f1 \- extract offset from packed XIO address
|
|
\f4XIO_NOWHERE\f1 \- nonexistant XIO target
|
|
.fi
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ds fT \f1
|
|
.if t .ds fT \f4
|
|
\*(fT#include <sys/xtalk/xtalk.h>
|
|
.sp .8v
|
|
/*
|
|
** These are really macros, but
|
|
** if they were functions:
|
|
*/
|
|
.sp .8v
|
|
iopaddr_t
|
|
XIO_PACK(xwidgetnum_t \f2port\*(fT, iopaddr_t \f2offset\*(fT)
|
|
.sp .8v
|
|
int
|
|
XIO_PACKED(iopaddr_t \f2xaddr\*(fT)
|
|
.sp .8v
|
|
xwidgetnum_t
|
|
XIO_PORT(iopaddr_t \f2xaddr\*(fT)
|
|
.sp .8v
|
|
iopaddr_t
|
|
XIO_ADDR(iopaddr_t \f2xaddr\*(fT)
|
|
.sp .8v
|
|
iopaddr_t XIO_NOWHERE;
|
|
.fi
|
|
.SS Arguments
|
|
.IP "\f2offset\f1" 8n
|
|
is an appropriate 48-bit XIO address (offset).
|
|
.IP "\f2port\f1" 8n
|
|
is a 4-bit XIO target port number.
|
|
.IP "\f2xaddr\f1" 8n
|
|
is
|
|
.SH DESCRIPTION
|
|
.P
|
|
.IR 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.
|
|
.P
|
|
.IR 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).
|
|
.P
|
|
.IR XIO_PORT ()
|
|
extracts the target port number
|
|
from a packed address.
|
|
.P
|
|
.IR XIO_ADDR ()
|
|
extracts the target address
|
|
from a packed address.
|
|
.P
|
|
.I XIO_NOWHERE
|
|
is a constant containing a packed
|
|
XIO address that represents an
|
|
impossible DMA target.
|
|
.P
|
|
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.
|
|
.P
|
|
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.
|
|
.SH EXAMPLES
|
|
.P
|
|
The following is a contrived example
|
|
of some interrupt code servicing a simple
|
|
DMA engine on an XIO card.
|
|
.if t .ft 4
|
|
.nf
|
|
...
|
|
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;
|
|
...
|
|
.fi
|
|
.ft 1
|
|
.SH NOTES
|
|
.P
|
|
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.
|
|
.\" .SH FILES
|
|
.SH "SEE ALSO"
|
|
xtalk_dma(D3)
|
|
.\" .SH DIAGNOSTICS
|