HSISETUP(3H) — MISC REFERENCE MANUAL PAGES

NAME

HsiSetup− prepare HSI to transfer data

SYNOPSIS

#include <hsidefs.h>

int HsiSetup(hsi, receiving, npxl, nlines, format, rcvaddr)
HSIDEV ∗hsi;
int receiving, npxl, nlines, format, rcvaddr;

DESCRIPTION

HsiSetup prepares the HSI for data transfer, but does not actually transfer data. The responsibility for effecting the data transfer is left to the user application.

The receiving argument is 1 to specify that the HSI is receiving pixels from the Chap, or 0 to specify that the HSI is sending pixels to the Chap. Pixels are transfered in nlines lines of npxl pixels each. When the HSI is sending, rcvaddr specifies the yapbus receiver address used by the Chap; when the HSI is receiving, rcvaddr specifies the yapbus address of the HSI, to which the Chap will address its transmission. Prior to calling HsiSetup, a Chap routine (for example, YSCopy) must be started to send or receive data from the HSI.

After calling HsiSetup, the user application makes read (when receiving) or write (when sending) accesses to the HSI data window to exchange data with the HSI. Programs using 32-bit unsigned long data should reference the 32-bit data window, whose address is given by HsiDW32Addr(3H). Programs using 16-bit unsigned short data should use the 16-bit data window, whose address is given by HsiDW16Addr(3H). Refer to the HSI Tutorial document for an explanation of the data window.

After all data has been sent to or received from the HSI, the user program should call HsiWaitDone to wait for the HSI to report completion of the service, and then it should call HsiGetStatus to obtain the completion status of the transfer.

FORMATS

When the HSI is sending, the format argument may be one of the following values (see the HSI Tutorial for an explanation of HSI pixel formats). The numbers in square brackets represent the ratio of 32-bit longs entering the HSI to pixels leaving the HSI for the yapbus; the first number of each pair should be doubled when using 16-bit short values. Alpha8 and alpha16 are integers representing 8-bit and 16-bit alpha values, respectively. HSI_FMT_16RGBA[2/1]
HSI_FMT_8RGBA [1/1]
HSI_FMT_16RGB(alpha16) [3/2]
HSI_FMT_8RGB(alpha8) [3/4]
Optionally, the constant HSI_FMT_REORDER may be logically ored with one of the above values; this causes the ordering of the four bytes in each long to be reversed as they enter the HSI from the VMEbus.

When the HSI is receiving, the format argument may be either 0 or HSI_FMT_REORDER. The number of longs read from the HSI data window is twice the number of pixels received from the Chap.

RETURN VALUE

HsiSetup returns 0 upon successful setup. It returns −1 to indicate an error (this is typically due to an illegal parameter value); call HsiGetStatus to determine the exact nature of the error.

Museum