Date: Mon, 1 Feb 2010 20:53:55 +0000 (UTC) From: Joerg Wunsch <joerg@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r203356 - head/lib/libgpib Message-ID: <201002012053.o11KrtLh069723@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: joerg Date: Mon Feb 1 20:53:55 2010 New Revision: 203356 URL: http://svn.freebsd.org/changeset/base/203356 Log: Finally, document libgpib. MFC after: 3 days Added: head/lib/libgpib/gpib.3 (contents, props changed) Modified: head/lib/libgpib/Makefile Modified: head/lib/libgpib/Makefile ============================================================================== --- head/lib/libgpib/Makefile Mon Feb 1 20:50:49 2010 (r203355) +++ head/lib/libgpib/Makefile Mon Feb 1 20:53:55 2010 (r203356) @@ -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> Added: head/lib/libgpib/gpib.3 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/lib/libgpib/gpib.3 Mon Feb 1 20:53:55 2010 (r203356) @@ -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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201002012053.o11KrtLh069723>