freebsd-src/lib/libgpib/gpib.3

.\" Copyright (c) 2010, Joerg Wunsch
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd February 1, 2010
.Dt GPIB 3
.Os
.Sh NAME
.\" .Nm ibask ,
.\" .Nm ibbna ,
.\" .Nm ibcac ,
.Nm ibclr ,
.\" .Nm ibcmd ,
.\" .Nm ibcmda ,
.\" .Nm ibconfig ,
.Nm ibdev ,
.\" .Nm ibdiag ,
.Nm ibdma ,
.Nm ibeos ,
.Nm ibeot ,
.\" .Nm ibevent ,
.\" .Nm ibfind ,
.\" .Nm ibgts ,
.\" .Nm ibist ,
.\" .Nm iblines ,
.\" .Nm ibllo ,
.\" .Nm ibln ,
.Nm ibloc ,
.Nm ibonl ,
.Nm ibpad ,
.\" .Nm ibpct ,
.\" .Nm ibpoke ,
.\" .Nm ibppc ,
.Nm ibrd ,
.\" .Nm ibrda ,
.\" .Nm ibrdf ,
.\" .Nm ibrdkey ,
.\" .Nm ibrpp ,
.\" .Nm ibrsc ,
.\" .Nm ibrsp ,
.\" .Nm ibrsv ,
.Nm ibsad ,
.\" .Nm ibsgnl ,
.Nm ibsic ,
.\" .Nm ibsre ,
.\" .Nm ibsrq ,
.\" .Nm ibstop ,
.Nm ibtmo ,
.\" .Nm ibtrap ,
.Nm ibtrg ,
.\" .Nm ibwait ,
.Nm ibwrt
.\" .Nm ibwrta ,
.\" .Nm ibwrtf ,
.\" .Nm ibwrtkey ,
.\" .Nm ibxtrc
.Nd "GPIB library"
.Sh LIBRARY
.Lb libgpib
.Sh SYNOPSIS
.In gpib.h
.Pp
.Dv extern int ibcnt ,
.Dv iberr ,
.Dv ibsta ;
.Pp
.Ft int
.Fn ibask "int handle" "int option" "int *retval"
.Ft int
.Fn ibbna "int handle" "char *bdname"
.Ft int
.Fn ibcac "int handle" "int v"
.Ft int
.Fn ibclr "int handle"
.Ft int
.Fn ibcmd "int handle" "void *buffer" "long cnt"
.Ft int
.Fn ibcmda "int handle" "void *buffer" "long cnt"
.Ft int
.Fn ibconfig "int handle" "int option" "int value"
.Ft int
.Fn ibdev "int boardID" "int pad" "int sad" "int tmo" "int eot" "int eos"
.Ft int
.Fn ibdiag "int handle" "void *buffer" "long cnt"
.Ft int
.Fn ibdma "int handle" "int v"
.Ft int
.Fn ibeos "int handle" "int eos"
.Ft int
.Fn ibeot "int handle" "int eot"
.Ft int
.Fn ibevent "int handle" "short *event"
.Ft int
.Fn ibfind "char *bdname"
.Ft int
.Fn ibgts "int handle" "int v"
.Ft int
.Fn ibist "int handle" "int v"
.Ft int
.Fn iblines "int handle" "short *lines"
.Ft int
.Fn ibllo "int handle"
.Ft int
.Fn ibln "int handle" "int padval" "int sadval" "short *listenflag"
.Ft int
.Fn ibloc "int handle"
.Ft int
.Fn ibonl "int handle" "int v"
.Ft int
.Fn ibpad "int handle" "int pad"
.Ft int
.Fn ibpct "int handle"
.Ft int
.Fn ibpoke "int handle" "int option" "int value"
.Ft int
.Fn ibppc "int handle" "int v"
.Ft int
.Fn ibrd "int handle" "void *buffer" "long cnt"
.Ft int
.Fn ibrda "int handle" "void *buffer" "long cnt"
.Ft int
.Fn ibrdf "int handle" "char *flname"
.Ft int
.Fn ibrdkey "int handle" "void *buffer" "int cnt"
.Ft int
.Fn ibrpp "int handle" "char *ppr"
.Ft int
.Fn ibrsc "int handle" "int v"
.Ft int
.Fn ibrsp "int handle" "char *spr"
.Ft int
.Fn ibrsv "int handle" "int v"
.Ft int
.Fn ibsad "int handle" "int sad"
.Ft int
.Fn ibsgnl "int handle" "int v"
.Ft int
.Fn ibsic "int handle"
.Ft int
.Fn ibsre "int handle" "int v"
.Ft int
.Fn ibsrq "(*func) void)"
.Ft int
.Fn ibstop "int handle"
.Ft int
.Fn ibtmo "int handle" "int tmo"
.Ft int
.Fn ibtrap "int  mask" "int mode"
.Ft int
.Fn ibtrg "int handle"
.Ft int
.Fn ibwait "int handle" "int mask"
.Ft int
.Fn ibwrt "int handle" "const void *buffer" "long cnt"
.Ft int
.Fn ibwrta "int handle" "const void *buffer" "long cnt"
.Ft int
.Fn ibwrtf "int handle" "const char *flname"
.Ft int
.Fn ibwrtkey "int handle" "const void *buffer" "int cnt"
.Ft int
.Fn ibxtrc "int handle" "void *buffer" "long cnt"
.Sh DESCRIPTION
The
.Nm
library provides access to the
.Xr gpib 4
kernel devices.
.Ss Variable Description
The variable
.Dv ibcnt
contains the number of bytes transferred in the most recent call to
.Fn ibcmd ,
.Fn ibrd ,
or
.Fn ibwrt .
.Pp
The name
.Dv ibcntl
is an alias for
.Dv ibcnt ,
provided for backwards compatibility.
.Pp
The variable
.Dv iberr
provides an error code for the most recent library call.
The possible error codes are:
.Pp
.Bl -tag -width 6n -offset indent -compact
.It EDVR
System error
.It ECIC
Not Active Controller
.It ENOL
Nobody listening
.It EADR
Controller not addressed
.It EARG
Invalid argument
.It ESAC
Not System Controller
.It EABO
I/O Aborted/Time out
.It ENEB
No such controller
.It EOIP
Async I/O in progress
.It ECAP
No such capability
.It EFSO
File system error
.It EBUS
Command byte xfer error
.It ESTB
Serial poll status byte lost
.It ESRQ
SRQ line stuck
.It ETAB
Table problem
.El
.Pp
The variable
.Dv ibsta
contains the controller status.
This is an ORed status value, with the following individual bit names:
.Pp
.Bl -tag -width 6n -offset indent -compact
.It ERR
Error
.It TIMO
Timeout
.It END
EOI/EOS
.It SRQI
SRQ
.It RQS
Device requests service
.It SPOLL
Serial Poll
.It EVENT
Event occurred
.It CMPL
I/O complete
.It LOK
Lockout
.It REM
Remote
.It CIC
CIC
.It ATN
ATN
.It TACS
Talker
.It LACS
Listener
.It DTAS
Device trigger status
.It DCAS
Device clear state
.El
.Ss Function Description
The function
.Fn ibdev
is used to open the GPIB device, and establish the parameters to
communicate with a particular bus device. The device is selected
by its primary address
.Fa pad ,
a numerical value between 0 and 30, possibly additionally by its
secondary address
.Fa sad ,
a numerical value between 96 and 126, or 0 to not use secondary
addressing.
The
.Fa tmo
value specifies the timeout to use when communicating with the device.
This can be any of the constants
.Dv TNONE ,
.Dv T10us ,
.Dv T30us ,
.Dv T100us ,
.Dv T300us ,
.Dv T1ms ,
.Dv T3ms ,
.Dv T10ms ,
.Dv T30ms ,
.Dv T100ms ,
.Dv T300ms ,
.Dv T1s ,
.Dv T3s ,
.Dv T10s ,
.Dv T30s ,
.Dv T100s ,
.Dv T300s ,
or
.Dv T1000s .
The boolean parameter
.Fa eot
specifies whether the bus signal
.Li EOI
(end-or-identify) should be asserted when sending the last byte of a
message to the device.
Finally, the
.Fa eos
parameter determines whether any special character should be used to
identify the end of a device message when transferring messages on the
bus.
The lower 8 bits of
.Fa eos
are interpreted as an end-of-string character,
.Li EOS .
This character can be ORed with the following values:
.Pp
.Bl -tag -width 6n -compact -offset indent
.It Dv REOS
When receiving a message byte on the bus that matches the
.Li EOS
character, treat it as if the
.Li EOI
signal were asserted, and stop receiving.
.It Dv XEOS
When transmitting a message byte on the bus that matches the
.Li EOS
character, assert the
.Li EOI
bus signal by the same time, and stop sending.
.It Dv BIN
If set, include all 8 bits of the
.Li EOS
character in the comparison; if unset, compare only 7 bit ASCII
values.
.El
.Pp
Passing 0 as
.Fa eos
will turn off any special character treatment, allowing for a fully
8-bit transparent communications channel to the device.
.Pp
The function
.Fn ibfind
is meant to find the
.Em board index
of a board identified by the name
.Fa bdname .
.Em This function is currently not implemented.
.Pp
All remaining functions take the handle returned by calling
.Fn ibdev
as their first argument
.Fa handle .
.Pp
The function
.Fn ibask
is used to query configuration values that have been set with
.Fn ibconfig .
.Em This function is currently not implemented.
.Pp
The function
.Fn ibbna
is meant to change the access board for the given device to
a new one, named
.Fa bdname .
.Em This function is currently not implemented.
.Pp
The function
.Fn ibcac
is used to become the active controller on the bus, by asserting the
.Li ATN
signal line.
.Em This function is currently not implemented.
.Pp
The function
.Fn ibclr
is used to transmit a
.Em Selected Device Clear
command to the device.
.Pp
The function
.Fn ibcmd
is used to directly write
.Fa cnt
GPIB command bytes from a buffer starting at
.Fa buffer
to the device.
.Em This function is currently not implemented.
.Pp
The function
.Fn ibcmda
does the same as
.Fn ibcmd
except it operates asynchronously, so it returns to the caller
immediately.
.Em This function is currently not implemented.
.Pp
The function
.Fn ibconfig
is used to set certain configuration parameters.
.Em This function is currently not implemented.
.Pp
The function
.Fn ibdiag
is obsolete, and not implemented.
.Pp
The function
.Fn ibdma
is used to enable or disable DMA transfers.
Parameter
.Fa v
is a boolean parameter indicating DMA transfers are to be used.
Depending on the hardware and operating system configuration, DMA
transfers might not be available for a particular access board.
.Pp
The function
.Fn ibeos
configures the end-of-string character.
See
.Fn ibdev
for an explanation.
.Pp
The function
.Fn ibeot
configures the assertion of the
.Li EOI
signal line when transmitting the last byte of a message; see
.Fn ibdev
for an explanation.
.Pp
The function
.Fn ibevent
is used to obtain an event from the board's event queue.
.Em This function is currently not implemented.
.Pp
The function
.Fn ibgts
makes the current controller the standby controller, by deasserting
the
.Li ATN
signal line.
.Em This function is currently not implemented.
.Pp
The function
.Fn ibist
sets the individual status bits of the controller to the value
.Fa v .
.Em This function is currently not implemented.
.Pp
The function
.Fn iblines
returns the status of the control and handshake bus lines into the
area pointed to by
.Fa lines .
.Em This function is currently not implemented.
.Pp
The function
.Fn ibllo
is obsolete, and not implemented.
.Pp
The function
.Fn ibln
checks for a listener at the primary address
.Fa  padval
and the optional secondary address
.Fa sadval .
If a listener was found, the value pointed to by
.Fa listenflag
will be set to a non-zero value.
.Em This function is currently not implemented.
.Pp
The function
.Fn ibloc
turns the device into local mode.
.Pp
The function
.Fn ibonl
is used to close or reinitialize a device handle.
If parameter
.Fa v
is passed as zero, the handle will be closed, and cannot be used
again.
If it is passed as a non-zero value, all parameters of the handle
will be returned to their defaults;
.Em this functionality is currently unsupported.
.Pp
The function
.Fn ibpad
is used to change the primary address of the device being communicated
with to
.Fa pad .
See
.Fn ibdev
for an explanation.
.Pp
The function
.Fn ibpct
is used to make the device associated with the handle the
controller-in-charge.
.Em This function is currently not implemented.
.Pp
The function
.Fn ibpoke
is obsolete, and not implemented.
.Pp
The function
.Fn ibppc
is used to configure the parallel poll response to
.Fa v .
.Em This function is currently not implemented.
.Pp
The function
.Fn ibrd
is used to receive
.Fa cnt
bytes from the device, and store it to the address passed as
.Fa buffer .
.Pp
The function
.Fn ibrda
behaves similar to
.Fn ibrd
except it operates asynchronously, and returns immediately to the
caller.
.Em This function is currently not implemented.
.Pp
The function
.Fn ibrdf
read data from the device, and appends it to the file with the name
.Fa flname .
.Em This function is currently not implemented.
.Pp
The function
.Fn ibrdkey
is obsolete, and not implemented.
.Pp
The function
.Fn ibrpp
performs a parallel poll, and stores the result at the location
pointed to by
.Fa ppr .
.Em This function is currently not implemented.
.Pp
The function
.Fn ibrsc
makes the board specified by the handle the
.Em system controller
if the argument
.Fa v
is non-zero.
.Em This function is currently not implemented.
.Pp
The function
.Fn ibrsp
conducts a serial poll, and stores the result in the byte pointed
to by
.Fa spr .
.Em This function is currently not implemented.
.Pp
The function
.Fn ibrsv
sets the serial poll response of the board to
.Fa v ,
possibly requesting service from the controller if the SRQ bit (0x40)
is set.
.Em This function is currently not implemented.
.Pp
The function
.Fn ibsad
changes the secondary address of the device being communicated with to
.Fa sad .
See
.Fn ibdev
for an explanation.
.Pp
The function
.Fn ibsgnl
is obsolete, and not implemented.
.Pp
The function
.Fn ibsic
asserts the
.Em Interface Clear (IFC)
signal line on the bus for at least 100 microseconds.
This will make all devices attached to the bus to unlisten and untalk.
This function should only be executed on the system controller.
.Pp
The function
.Fn ibsre
asserts the
.Em Remote Enable (REN)
signal line on the bus if argument
.Fa v
is non-zero, or deasserts it otherwise.
.Em This function is currently not implemented.
.Pp
The function
.Fn ibsrq
is obsolete, and not implemented.
.Pp
The function
.Fn ibstop
stops or aborts any asynchronous I/O operation.
.Em This function is currently not implemented.
.Pp
The function
.Fn ibtmo
reconfigures the communication timeout.
See
.Fn ibdev
for an explanation.
.Pp
The function
.Fn ibtrap
is obsolete, and not implemented.
.Pp
The function
.Fn ibtrg
sends a
.Em Group Execute Trigger (GET)
command to the device.
.Pp
The function
.Fn ibwait
waits for a status condition as specified by
.Fa mask .
If
.Fa mask
is given as zero, it returns immediately.
.Em This function is currently not implemented.
.Pp
The function
.Fn ibwrt
is used to send
.Fa cnt
bytes to the device, starting at the address pointed to by
.Fa buffer .
.Pp
The function
.Fn ibwrta
performs the same operation as
.Fn ibwrt
in an asynchronous way, returning immediately to the caller.
.Em This function is currently not implemented.
.Pp
The function
.Fn ibwrtf
opens the file named by
.Fa flname ,
and sends its contents to the device.
.Em This function is currently not implemented.
.Pp
The function
.Fn ibwrtkey
is obsolete, and not implemented.
.Pp
The function
.Fn ibxtrc
is obsolete, and not implemented.
.Sh RETURN VALUES
The function
.Fn ibdev
returns a handle to be used for the remaining functions.
Upon failure, -1 is returned.
.Pp
All other functions return the value of the variable
.Dv ibsta .
.Sh DIAGNOSTICS
None.
.Sh COMPATIBILITY
The
.Nm
library tries to be compatible with the Linux GPIB library,
which in turn appears to be compatible with the GPIB library
shipped by National Instruments.
.Sh ERRORS
Errors in the functions above might set
.Dv errno
to one of these values:
.Bl -tag -width Er
.It Bq Er ENOENT
No such file or directory.
.It Bq Er EIO
Input/output error.
.It Bq Er ENXIO
Device not configured.
.It Bq Er E2BIG
Argument list too long.
.It Bq Er ENOMEM
Cannot allocate memory.
.It Bq Er EACCES
Permission denied.
.It Bq Er EFAULT
Bad address.
.It Bq Er EBUSY
Device busy.
.It Bq Er EINVAL
Invalid argument.
.It Bq Er ENFILE
Too many open files in system.
.It Bq Er EMFILE
Too many open files.
.It Bq Er EOPNOTSUPP
Operation not supported.
.El
.Sh SEE ALSO
.Xr gpib 4
.Sh HISTORY
The
.Nm
library was written by
.An Poul-Henning Kamp
and first appeared in
.Fx 5.4 .
.Sh AUTHORS
This manual page was written by
.An J\(:org Wunsch .
.Sh BUGS
Currently, the library can only handle a single
.Xr gpib 4
device with instance number 0.
.Pp
Many functions are currently not implemented, see above for details.