2 files changed, 757 insertions, 0 deletions
diff --git a/lib/libgpib/Makefile b/lib/libgpib/Makefile
index caf6bcf..80e890bd 100644
--- a/lib/libgpib/Makefile
+++ b/lib/libgpib/Makefile
@@ -6,4 +6,23 @@ INCS=		gpib.h
 INCSDIR=	${INCLUDEDIR}/gpib
 SRCS=		ibfoo.c
 
+MAN=		gpib.3
+
+# MLINKS are only provided for functions that are actually
+# implemented; update this if missing pieces have been filled in.
+MLINKS+=	gpib.3 ibclr.3
+MLINKS+=	gpib.3 ibdev.3
+MLINKS+=	gpib.3 ibdma.3
+MLINKS+=	gpib.3 ibeos.3
+MLINKS+=	gpib.3 ibeot.3
+MLINKS+=	gpib.3 ibloc.3
+MLINKS+=	gpib.3 ibonl.3
+MLINKS+=	gpib.3 ibpad.3
+MLINKS+=	gpib.3 ibrd.3
+MLINKS+=	gpib.3 ibsad.3
+MLINKS+=	gpib.3 ibsic.3
+MLINKS+=	gpib.3 ibtmo.3
+MLINKS+=	gpib.3 ibtrg.3
+MLINKS+=	gpib.3 ibwrt.3
+
 .include <bsd.lib.mk>
diff --git a/lib/libgpib/gpib.3 b/lib/libgpib/gpib.3
new file mode 100644
index 0000000..a57d3a4
--- /dev/null
+++ b/lib/libgpib/gpib.3
@@ -0,0 +1,738 @@
+.\" 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:
+.Bl -tag -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:
+.Bl -tag -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 occured
+.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
+.Pp
+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:
+.Bl -tag -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
+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 fucntion
+.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.