lib/libgpib/gpib.3

   1 .\" Copyright (c) 2010, Joerg Wunsch
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd February 1, 2010
  28 .Dt GPIB 3
  29 .Os
  30 .Sh NAME
  31 .\" .Nm ibask ,
  32 .\" .Nm ibbna ,
  33 .\" .Nm ibcac ,
  34 .Nm ibclr ,
  35 .\" .Nm ibcmd ,
  36 .\" .Nm ibcmda ,
  37 .\" .Nm ibconfig ,
  38 .Nm ibdev ,
  39 .\" .Nm ibdiag ,
  40 .Nm ibdma ,
  41 .Nm ibeos ,
  42 .Nm ibeot ,
  43 .\" .Nm ibevent ,
  44 .\" .Nm ibfind ,
  45 .\" .Nm ibgts ,
  46 .\" .Nm ibist ,
  47 .\" .Nm iblines ,
  48 .\" .Nm ibllo ,
  49 .\" .Nm ibln ,
  50 .Nm ibloc ,
  51 .Nm ibonl ,
  52 .Nm ibpad ,
  53 .\" .Nm ibpct ,
  54 .\" .Nm ibpoke ,
  55 .\" .Nm ibppc ,
  56 .Nm ibrd ,
  57 .\" .Nm ibrda ,
  58 .\" .Nm ibrdf ,
  59 .\" .Nm ibrdkey ,
  60 .\" .Nm ibrpp ,
  61 .\" .Nm ibrsc ,
  62 .\" .Nm ibrsp ,
  63 .\" .Nm ibrsv ,
  64 .Nm ibsad ,
  65 .\" .Nm ibsgnl ,
  66 .Nm ibsic ,
  67 .\" .Nm ibsre ,
  68 .\" .Nm ibsrq ,
  69 .\" .Nm ibstop ,
  70 .Nm ibtmo ,
  71 .\" .Nm ibtrap ,
  72 .Nm ibtrg ,
  73 .\" .Nm ibwait ,
  74 .Nm ibwrt
  75 .\" .Nm ibwrta ,
  76 .\" .Nm ibwrtf ,
  77 .\" .Nm ibwrtkey ,
  78 .\" .Nm ibxtrc
  79 .Nd "GPIB library"
  80 .Sh LIBRARY
  81 .Lb libgpib
  82 .Sh SYNOPSIS
  83 .In gpib.h
  84 .Pp
  85 .Dv extern int ibcnt ,
  86 .Dv iberr ,
  87 .Dv ibsta ;
  88 .Pp
  89 .Ft int
  90 .Fn ibask "int handle" "int option" "int *retval"
  91 .Ft int
  92 .Fn ibbna "int handle" "char *bdname"
  93 .Ft int
  94 .Fn ibcac "int handle" "int v"
  95 .Ft int
  96 .Fn ibclr "int handle"
  97 .Ft int
  98 .Fn ibcmd "int handle" "void *buffer" "long cnt"
  99 .Ft int
 100 .Fn ibcmda "int handle" "void *buffer" "long cnt"
 101 .Ft int
 102 .Fn ibconfig "int handle" "int option" "int value"
 103 .Ft int
 104 .Fn ibdev "int boardID" "int pad" "int sad" "int tmo" "int eot" "int eos"
 105 .Ft int
 106 .Fn ibdiag "int handle" "void *buffer" "long cnt"
 107 .Ft int
 108 .Fn ibdma "int handle" "int v"
 109 .Ft int
 110 .Fn ibeos "int handle" "int eos"
 111 .Ft int
 112 .Fn ibeot "int handle" "int eot"
 113 .Ft int
 114 .Fn ibevent "int handle" "short *event"
 115 .Ft int
 116 .Fn ibfind "char *bdname"
 117 .Ft int
 118 .Fn ibgts "int handle" "int v"
 119 .Ft int
 120 .Fn ibist "int handle" "int v"
 121 .Ft int
 122 .Fn iblines "int handle" "short *lines"
 123 .Ft int
 124 .Fn ibllo "int handle"
 125 .Ft int
 126 .Fn ibln "int handle" "int padval" "int sadval" "short *listenflag"
 127 .Ft int
 128 .Fn ibloc "int handle"
 129 .Ft int
 130 .Fn ibonl "int handle" "int v"
 131 .Ft int
 132 .Fn ibpad "int handle" "int pad"
 133 .Ft int
 134 .Fn ibpct "int handle"
 135 .Ft int
 136 .Fn ibpoke "int handle" "int option" "int value"
 137 .Ft int
 138 .Fn ibppc "int handle" "int v"
 139 .Ft int
 140 .Fn ibrd "int handle" "void *buffer" "long cnt"
 141 .Ft int
 142 .Fn ibrda "int handle" "void *buffer" "long cnt"
 143 .Ft int
 144 .Fn ibrdf "int handle" "char *flname"
 145 .Ft int
 146 .Fn ibrdkey "int handle" "void *buffer" "int cnt"
 147 .Ft int
 148 .Fn ibrpp "int handle" "char *ppr"
 149 .Ft int
 150 .Fn ibrsc "int handle" "int v"
 151 .Ft int
 152 .Fn ibrsp "int handle" "char *spr"
 153 .Ft int
 154 .Fn ibrsv "int handle" "int v"
 155 .Ft int
 156 .Fn ibsad "int handle" "int sad"
 157 .Ft int
 158 .Fn ibsgnl "int handle" "int v"
 159 .Ft int
 160 .Fn ibsic "int handle"
 161 .Ft int
 162 .Fn ibsre "int handle" "int v"
 163 .Ft int
 164 .Fn ibsrq "(*func) void)"
 165 .Ft int
 166 .Fn ibstop "int handle"
 167 .Ft int
 168 .Fn ibtmo "int handle" "int tmo"
 169 .Ft int
 170 .Fn ibtrap "int  mask" "int mode"
 171 .Ft int
 172 .Fn ibtrg "int handle"
 173 .Ft int
 174 .Fn ibwait "int handle" "int mask"
 175 .Ft int
 176 .Fn ibwrt "int handle" "const void *buffer" "long cnt"
 177 .Ft int
 178 .Fn ibwrta "int handle" "const void *buffer" "long cnt"
 179 .Ft int
 180 .Fn ibwrtf "int handle" "const char *flname"
 181 .Ft int
 182 .Fn ibwrtkey "int handle" "const void *buffer" "int cnt"
 183 .Ft int
 184 .Fn ibxtrc "int handle" "void *buffer" "long cnt"
 185 .Sh DESCRIPTION
 186 The
 187 .Nm
 188 library provides access to the
 189 .Xr gpib 4
 190 kernel devices.
 191 .Ss Variable Description
 192 The variable
 193 .Dv ibcnt
 194 contains the number of bytes transferred in the most recent call to
 195 .Fn ibcmd ,
 196 .Fn ibrd ,
 197 or
 198 .Fn ibwrt .
 199 .Pp
 200 The name
 201 .Dv ibcntl
 202 is an alias for
 203 .Dv ibcnt ,
 204 provided for backwards compatibility.
 205 .Pp
 206 The variable
 207 .Dv iberr
 208 provides an error code for the most recent library call.
 209 The possible error codes are:
 210 .Pp
 211 .Bl -tag -width 6n -offset indent -compact
 212 .It EDVR
 213 System error
 214 .It ECIC
 215 Not Active Controller
 216 .It ENOL
 217 Nobody listening
 218 .It EADR
 219 Controller not addressed
 220 .It EARG
 221 Invalid argument
 222 .It ESAC
 223 Not System Controller
 224 .It EABO
 225 I/O Aborted/Time out
 226 .It ENEB
 227 No such controller
 228 .It EOIP
 229 Async I/O in progress
 230 .It ECAP
 231 No such capability
 232 .It EFSO
 233 File system error
 234 .It EBUS
 235 Command byte xfer error
 236 .It ESTB
 237 Serial poll status byte lost
 238 .It ESRQ
 239 SRQ line stuck
 240 .It ETAB
 241 Table problem
 242 .El
 243 .Pp
 244 The variable
 245 .Dv ibsta
 246 contains the controller status.
 247 This is an ORed status value, with the following individual bit names:
 248 .Pp
 249 .Bl -tag -width 6n -offset indent -compact
 250 .It ERR
 251 Error
 252 .It TIMO
 253 Timeout
 254 .It END
 255 EOI/EOS
 256 .It SRQI
 257 SRQ
 258 .It RQS
 259 Device requests service
 260 .It SPOLL
 261 Serial Poll
 262 .It EVENT
 263 Event occurred
 264 .It CMPL
 265 I/O complete
 266 .It LOK
 267 Lockout
 268 .It REM
 269 Remote
 270 .It CIC
 271 CIC
 272 .It ATN
 273 ATN
 274 .It TACS
 275 Talker
 276 .It LACS
 277 Listener
 278 .It DTAS
 279 Device trigger status
 280 .It DCAS
 281 Device clear state
 282 .El
 283 .Ss Function Description
 284 The function
 285 .Fn ibdev
 286 is used to open the GPIB device, and establish the parameters to
 287 communicate with a particular bus device. The device is selected
 288 by its primary address
 289 .Fa pad ,
 290 a numerical value between 0 and 30, possibly additionally by its
 291 secondary address
 292 .Fa sad ,
 293 a numerical value between 96 and 126, or 0 to not use secondary
 294 addressing.
 295 The
 296 .Fa tmo
 297 value specifies the timeout to use when communicating with the device.
 298 This can be any of the constants
 299 .Dv TNONE ,
 300 .Dv T10us ,
 301 .Dv T30us ,
 302 .Dv T100us ,
 303 .Dv T300us ,
 304 .Dv T1ms ,
 305 .Dv T3ms ,
 306 .Dv T10ms ,
 307 .Dv T30ms ,
 308 .Dv T100ms ,
 309 .Dv T300ms ,
 310 .Dv T1s ,
 311 .Dv T3s ,
 312 .Dv T10s ,
 313 .Dv T30s ,
 314 .Dv T100s ,
 315 .Dv T300s ,
 316 or
 317 .Dv T1000s .
 318 The boolean parameter
 319 .Fa eot
 320 specifies whether the bus signal
 321 .Li EOI
 322 (end-or-identify) should be asserted when sending the last byte of a
 323 message to the device.
 324 Finally, the
 325 .Fa eos
 326 parameter determines whether any special character should be used to
 327 identify the end of a device message when transferring messages on the
 328 bus.
 329 The lower 8 bits of
 330 .Fa eos
 331 are interpreted as an end-of-string character,
 332 .Li EOS .
 333 This character can be ORed with the following values:
 334 .Pp
 335 .Bl -tag -width 6n -compact -offset indent
 336 .It Dv REOS
 337 When receiving a message byte on the bus that matches the
 338 .Li EOS
 339 character, treat it as if the
 340 .Li EOI
 341 signal were asserted, and stop receiving.
 342 .It Dv XEOS
 343 When transmitting a message byte on the bus that matches the
 344 .Li EOS
 345 character, assert the
 346 .Li EOI
 347 bus signal by the same time, and stop sending.
 348 .It Dv BIN
 349 If set, include all 8 bits of the
 350 .Li EOS
 351 character in the comparison; if unset, compare only 7 bit ASCII
 352 values.
 353 .El
 354 .Pp
 355 Passing 0 as
 356 .Fa eos
 357 will turn off any special character treatment, allowing for a fully
 358 8-bit transparent communications channel to the device.
 359 .Pp
 360 The function
 361 .Fn ibfind
 362 is meant to find the
 363 .Em board index
 364 of a board identified by the name
 365 .Fa bdname .
 366 .Em This function is currently not implemented.
 367 .Pp
 368 All remaining functions take the handle returned by calling
 369 .Fn ibdev
 370 as their first argument
 371 .Fa handle .
 372 .Pp
 373 The function
 374 .Fn ibask
 375 is used to query configuration values that have been set with
 376 .Fn ibconfig .
 377 .Em This function is currently not implemented.
 378 .Pp
 379 The function
 380 .Fn ibbna
 381 is meant to change the access board for the given device to
 382 a new one, named
 383 .Fa bdname .
 384 .Em This function is currently not implemented.
 385 .Pp
 386 The function
 387 .Fn ibcac
 388 is used to become the active controller on the bus, by asserting the
 389 .Li ATN
 390 signal line.
 391 .Em This function is currently not implemented.
 392 .Pp
 393 The function
 394 .Fn ibclr
 395 is used to transmit a
 396 .Em Selected Device Clear
 397 command to the device.
 398 .Pp
 399 The function
 400 .Fn ibcmd
 401 is used to directly write
 402 .Fa cnt
 403 GPIB command bytes from a buffer starting at
 404 .Fa buffer
 405 to the device.
 406 .Em This function is currently not implemented.
 407 .Pp
 408 The function
 409 .Fn ibcmda
 410 does the same as
 411 .Fn ibcmd
 412 except it operates asynchronously, so it returns to the caller
 413 immediately.
 414 .Em This function is currently not implemented.
 415 .Pp
 416 The function
 417 .Fn ibconfig
 418 is used to set certain configuration parameters.
 419 .Em This function is currently not implemented.
 420 .Pp
 421 The function
 422 .Fn ibdiag
 423 is obsolete, and not implemented.
 424 .Pp
 425 The function
 426 .Fn ibdma
 427 is used to enable or disable DMA transfers.
 428 Parameter
 429 .Fa v
 430 is a boolean parameter indicating DMA transfers are to be used.
 431 Depending on the hardware and operating system configuration, DMA
 432 transfers might not be available for a particular access board.
 433 .Pp
 434 The function
 435 .Fn ibeos
 436 configures the end-of-string character.
 437 See
 438 .Fn ibdev
 439 for an explanation.
 440 .Pp
 441 The function
 442 .Fn ibeot
 443 configures the assertion of the
 444 .Li EOI
 445 signal line when transmitting the last byte of a message; see
 446 .Fn ibdev
 447 for an explanation.
 448 .Pp
 449 The function
 450 .Fn ibevent
 451 is used to obtain an event from the board's event queue.
 452 .Em This function is currently not implemented.
 453 .Pp
 454 The function
 455 .Fn ibgts
 456 makes the current controller the standby controller, by deasserting
 457 the
 458 .Li ATN
 459 signal line.
 460 .Em This function is currently not implemented.
 461 .Pp
 462 The function
 463 .Fn ibist
 464 sets the individual status bits of the controller to the value
 465 .Fa v .
 466 .Em This function is currently not implemented.
 467 .Pp
 468 The function
 469 .Fn iblines
 470 returns the status of the control and handshake bus lines into the
 471 area pointed to by
 472 .Fa lines .
 473 .Em This function is currently not implemented.
 474 .Pp
 475 The function
 476 .Fn ibllo
 477 is obsolete, and not implemented.
 478 .Pp
 479 The function
 480 .Fn ibln
 481 checks for a listener at the primary address
 482 .Fa  padval
 483 and the optional secondary address
 484 .Fa sadval .
 485 If a listener was found, the value pointed to by
 486 .Fa listenflag
 487 will be set to a non-zero value.
 488 .Em This function is currently not implemented.
 489 .Pp
 490 The function
 491 .Fn ibloc
 492 turns the device into local mode.
 493 .Pp
 494 The function
 495 .Fn ibonl
 496 is used to close or reinitialize a device handle.
 497 If parameter
 498 .Fa v
 499 is passed as zero, the handle will be closed, and cannot be used
 500 again.
 501 If it is passed as a non-zero value, all parameters of the handle
 502 will be returned to their defaults;
 503 .Em this functionality is currently unsupported.
 504 .Pp
 505 The function
 506 .Fn ibpad
 507 is used to change the primary address of the device being communicated
 508 with to
 509 .Fa pad .
 510 See
 511 .Fn ibdev
 512 for an explanation.
 513 .Pp
 514 The function
 515 .Fn ibpct
 516 is used to make the device associated with the handle the
 517 controller-in-charge.
 518 .Em This function is currently not implemented.
 519 .Pp
 520 The function
 521 .Fn ibpoke
 522 is obsolete, and not implemented.
 523 .Pp
 524 The function
 525 .Fn ibppc
 526 is used to configure the parallel poll response to
 527 .Fa v .
 528 .Em This function is currently not implemented.
 529 .Pp
 530 The function
 531 .Fn ibrd
 532 is used to receive
 533 .Fa cnt
 534 bytes from the device, and store it to the address passed as
 535 .Fa buffer .
 536 .Pp
 537 The function
 538 .Fn ibrda
 539 behaves similar to
 540 .Fn ibrd
 541 except it operates asynchronously, and returns immediately to the
 542 caller.
 543 .Em This function is currently not implemented.
 544 .Pp
 545 The function
 546 .Fn ibrdf
 547 read data from the device, and appends it to the file with the name
 548 .Fa flname .
 549 .Em This function is currently not implemented.
 550 .Pp
 551 The function
 552 .Fn ibrdkey
 553 is obsolete, and not implemented.
 554 .Pp
 555 The function
 556 .Fn ibrpp
 557 performs a parallel poll, and stores the result at the location
 558 pointed to by
 559 .Fa ppr .
 560 .Em This function is currently not implemented.
 561 .Pp
 562 The function
 563 .Fn ibrsc
 564 makes the board specified by the handle the
 565 .Em system controller
 566 if the argument
 567 .Fa v
 568 is non-zero.
 569 .Em This function is currently not implemented.
 570 .Pp
 571 The function
 572 .Fn ibrsp
 573 conducts a serial poll, and stores the result in the byte pointed
 574 to by
 575 .Fa spr .
 576 .Em This function is currently not implemented.
 577 .Pp
 578 The function
 579 .Fn ibrsv
 580 sets the serial poll response of the board to
 581 .Fa v ,
 582 possibly requesting service from the controller if the SRQ bit (0x40)
 583 is set.
 584 .Em This function is currently not implemented.
 585 .Pp
 586 The function
 587 .Fn ibsad
 588 changes the secondary address of the device being communicated with to
 589 .Fa sad .
 590 See
 591 .Fn ibdev
 592 for an explanation.
 593 .Pp
 594 The function
 595 .Fn ibsgnl
 596 is obsolete, and not implemented.
 597 .Pp
 598 The function
 599 .Fn ibsic
 600 asserts the
 601 .Em Interface Clear (IFC)
 602 signal line on the bus for at least 100 microseconds.
 603 This will make all devices attached to the bus to unlisten and untalk.
 604 This function should only be executed on the system controller.
 605 .Pp
 606 The function
 607 .Fn ibsre
 608 asserts the
 609 .Em Remote Enable (REN)
 610 signal line on the bus if argument
 611 .Fa v
 612 is non-zero, or deasserts it otherwise.
 613 .Em This function is currently not implemented.
 614 .Pp
 615 The function
 616 .Fn ibsrq
 617 is obsolete, and not implemented.
 618 .Pp
 619 The function
 620 .Fn ibstop
 621 stops or aborts any asynchronous I/O operation.
 622 .Em This function is currently not implemented.
 623 .Pp
 624 The function
 625 .Fn ibtmo
 626 reconfigures the communication timeout.
 627 See
 628 .Fn ibdev
 629 for an explanation.
 630 .Pp
 631 The function
 632 .Fn ibtrap
 633 is obsolete, and not implemented.
 634 .Pp
 635 The function
 636 .Fn ibtrg
 637 sends a
 638 .Em Group Execute Trigger (GET)
 639 command to the device.
 640 .Pp
 641 The function
 642 .Fn ibwait
 643 waits for a status condition as specified by
 644 .Fa mask .
 645 If
 646 .Fa mask
 647 is given as zero, it returns immediately.
 648 .Em This function is currently not implemented.
 649 .Pp
 650 The function
 651 .Fn ibwrt
 652 is used to send
 653 .Fa cnt
 654 bytes to the device, starting at the address pointed to by
 655 .Fa buffer .
 656 .Pp
 657 The function
 658 .Fn ibwrta
 659 performs the same operation as
 660 .Fn ibwrt
 661 in an asynchronous way, returning immediately to the caller.
 662 .Em This function is currently not implemented.
 663 .Pp
 664 The function
 665 .Fn ibwrtf
 666 opens the file named by
 667 .Fa flname ,
 668 and sends its contents to the device.
 669 .Em This function is currently not implemented.
 670 .Pp
 671 The function
 672 .Fn ibwrtkey
 673 is obsolete, and not implemented.
 674 .Pp
 675 The function
 676 .Fn ibxtrc
 677 is obsolete, and not implemented.
 678 .Sh RETURN VALUES
 679 The function
 680 .Fn ibdev
 681 returns a handle to be used for the remaining functions.
 682 Upon failure, -1 is returned.
 683 .Pp
 684 All other functions return the value of the variable
 685 .Dv ibsta .
 686 .Sh DIAGNOSTICS
 687 None.
 688 .Sh COMPATIBILITY
 689 The
 690 .Nm
 691 library tries to be compatible with the Linux GPIB library,
 692 which in turn appears to be compatible with the GPIB library
 693 shipped by National Instruments.
 694 .Sh ERRORS
 695 Errors in the functions above might set
 696 .Dv errno
 697 to one of these values:
 698 .Bl -tag -width Er
 699 .It Bq Er ENOENT
 700 No such file or directory.
 701 .It Bq Er EIO
 702 Input/output error.
 703 .It Bq Er ENXIO
 704 Device not configured.
 705 .It Bq Er E2BIG
 706 Argument list too long.
 707 .It Bq Er ENOMEM
 708 Cannot allocate memory.
 709 .It Bq Er EACCES
 710 Permission denied.
 711 .It Bq Er EFAULT
 712 Bad address.
 713 .It Bq Er EBUSY
 714 Device busy.
 715 .It Bq Er EINVAL
 716 Invalid argument.
 717 .It Bq Er ENFILE
 718 Too many open files in system.
 719 .It Bq Er EMFILE
 720 Too many open files.
 721 .It Bq Er EOPNOTSUPP
 722 Operation not supported.
 723 .El
 724 .Sh SEE ALSO
 725 .Xr gpib 4
 726 .Sh HISTORY
 727 The
 728 .Nm
 729 library was written by
 730 .An Poul-Henning Kamp
 731 and first appeared in
 732 .Fx 5.4 .
 733 .Sh AUTHORS
 734 This manual page was written by
 735 .An J\(:org Wunsch .
 736 .Sh BUGS
 737 Currently, the library can only handle a single
 738 .Xr gpib 4
 739 device with instance number 0.
 740 .Pp
 741 Many functions are currently not implemented, see above for details.