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 .Bl -tag -offset indent -compact
 211 .It EDVR
 212 System error
 213 .It ECIC
 214 Not Active Controller
 215 .It ENOL
 216 Nobody listening
 217 .It EADR
 218 Controller not addressed
 219 .It EARG
 220 Invalid argument
 221 .It ESAC
 222 Not System Controller
 223 .It EABO
 224 I/O Aborted/Time out
 225 .It ENEB
 226 No such controller
 227 .It EOIP
 228 Async I/O in progress
 229 .It ECAP
 230 No such capability
 231 .It EFSO
 232 File system error
 233 .It EBUS
 234 Command byte xfer error
 235 .It ESTB
 236 Serial poll status byte lost
 237 .It ESRQ
 238 SRQ line stuck
 239 .It ETAB
 240 Table problem
 241 .El
 242 .Pp
 243 The variable
 244 .Dv ibsta
 245 contains the controller status.
 246 This is an ORed status value, with the following individual bit names:
 247 .Bl -tag -offset indent -compact
 248 .It ERR
 249 Error
 250 .It TIMO
 251 Timeout
 252 .It END
 253 EOI/EOS
 254 .It SRQI
 255 SRQ
 256 .It RQS
 257 Device requests service
 258 .It SPOLL
 259 Serial Poll
 260 .It EVENT
 261 Event occurred
 262 .It CMPL
 263 I/O complete
 264 .It LOK
 265 Lockout
 266 .It REM
 267 Remote
 268 .It CIC
 269 CIC
 270 .It ATN
 271 ATN
 272 .It TACS
 273 Talker
 274 .It LACS
 275 Listener
 276 .It DTAS
 277 Device trigger status
 278 .It DCAS
 279 Device clear state
 280 .El
 281 .Ss Function Description
 282 The function
 283 .Fn ibdev
 284 is used to open the GPIB device, and establish the parameters to
 285 communicate with a particular bus device. The device is selected
 286 by its primary address
 287 .Fa pad ,
 288 a numerical value between 0 and 30, possibly additionally by its
 289 secondary address
 290 .Fa sad ,
 291 a numerical value between 96 and 126, or 0 to not use secondary
 292 addressing.
 293 The
 294 .Fa tmo
 295 value specifies the timeout to use when communicating with the device.
 296 This can be any of the constants
 297 .Dv TNONE ,
 298 .Dv T10us ,
 299 .Dv T30us ,
 300 .Dv T100us ,
 301 .Dv T300us ,
 302 .Dv T1ms ,
 303 .Dv T3ms ,
 304 .Dv T10ms ,
 305 .Dv T30ms ,
 306 .Dv T100ms ,
 307 .Dv T300ms ,
 308 .Dv T1s ,
 309 .Dv T3s ,
 310 .Dv T10s ,
 311 .Dv T30s ,
 312 .Dv T100s ,
 313 .Dv T300s ,
 314 or
 315 .Dv T1000s .
 316 The boolean parameter
 317 .Fa eot
 318 specifies whether the bus signal
 319 .Li EOI
 320 (end-or-identify) should be asserted when sending the last byte of a
 321 message to the device.
 322 Finally, the
 323 .Fa eos
 324 parameter determines whether any special character should be used to
 325 identify the end of a device message when transferring messages on the
 326 bus.
 327 The lower 8 bits of
 328 .Fa eos
 329 are interpreted as an end-of-string character,
 330 .Li EOS .
 331 This character can be ORed with the following values:
 332 .Bl -tag -compact -offset indent
 333 .It Dv REOS
 334 When receiving a message byte on the bus that matches the
 335 .Li EOS
 336 character, treat it as if the
 337 .Li EOI
 338 signal were asserted, and stop receiving.
 339 .It Dv XEOS
 340 When transmitting a message byte on the bus that matches the
 341 .Li EOS
 342 character, assert the
 343 .Li EOI
 344 bus signal by the same time, and stop sending.
 345 .It Dv BIN
 346 If set, include all 8 bits of the
 347 .Li EOS
 348 character in the comparison; if unset, compare only 7 bit ASCII
 349 values.
 350 .El
 351 Passing 0 as
 352 .Fa eos
 353 will turn off any special character treatment, allowing for a fully
 354 8-bit transparent communications channel to the device.
 355 .Pp
 356 The function
 357 .Fn ibfind
 358 is meant to find the
 359 .Em board index
 360 of a board identified by the name
 361 .Fa bdname .
 362 .Em This function is currently not implemented.
 363 .Pp
 364 All remaining functions take the handle returned by calling
 365 .Fn ibdev
 366 as their first argument
 367 .Fa handle .
 368 .Pp
 369 The function
 370 .Fn ibask
 371 is used to query configuration values that have been set with
 372 .Fn ibconfig .
 373 .Em This function is currently not implemented.
 374 .Pp
 375 The function
 376 .Fn ibbna
 377 is meant to change the access board for the given device to
 378 a new one, named
 379 .Fa bdname .
 380 .Em This function is currently not implemented.
 381 .Pp
 382 The function
 383 .Fn ibcac
 384 is used to become the active controller on the bus, by asserting the
 385 .Li ATN
 386 signal line.
 387 .Em This function is currently not implemented.
 388 .Pp
 389 The function
 390 .Fn ibclr
 391 is used to transmit a
 392 .Em Selected Device Clear
 393 command to the device.
 394 .Pp
 395 The function
 396 .Fn ibcmd
 397 is used to directly write
 398 .Fa cnt
 399 GPIB command bytes from a buffer starting at
 400 .Fa buffer
 401 to the device.
 402 .Em This function is currently not implemented.
 403 .Pp
 404 The function
 405 .Fn ibcmda
 406 does the same as
 407 .Fn ibcmd
 408 except it operates asynchronously, so it returns to the caller
 409 immediately.
 410 .Em This function is currently not implemented.
 411 .Pp
 412 The function
 413 .Fn ibconfig
 414 is used to set certain configuration parameters.
 415 .Em This function is currently not implemented.
 416 .Pp
 417 The function
 418 .Fn ibdiag
 419 is obsolete, and not implemented.
 420 .Pp
 421 The function
 422 .Fn ibdma
 423 is used to enable or disable DMA transfers.
 424 Parameter
 425 .Fa v
 426 is a boolean parameter indicating DMA transfers are to be used.
 427 Depending on the hardware and operating system configuration, DMA
 428 transfers might not be available for a particular access board.
 429 .Pp
 430 The function
 431 .Fn ibeos
 432 configures the end-of-string character.
 433 See
 434 .Fn ibdev
 435 for an explanation.
 436 .Pp
 437 The function
 438 .Fn ibeot
 439 configures the assertion of the
 440 .Li EOI
 441 signal line when transmitting the last byte of a message; see
 442 .Fn ibdev
 443 for an explanation.
 444 .Pp
 445 The function
 446 .Fn ibevent
 447 is used to obtain an event from the board's event queue.
 448 .Em This function is currently not implemented.
 449 .Pp
 450 The function
 451 .Fn ibgts
 452 makes the current controller the standby controller, by deasserting
 453 the
 454 .Li ATN
 455 signal line.
 456 .Em This function is currently not implemented.
 457 .Pp
 458 The function
 459 .Fn ibist
 460 sets the individual status bits of the controller to the value
 461 .Fa v .
 462 .Em This function is currently not implemented.
 463 .Pp
 464 The function
 465 .Fn iblines
 466 returns the status of the control and handshake bus lines into the
 467 area pointed to by
 468 .Fa lines .
 469 .Em This function is currently not implemented.
 470 .Pp
 471 The function
 472 .Fn ibllo
 473 is obsolete, and not implemented.
 474 .Pp
 475 The function
 476 .Fn ibln
 477 checks for a listener at the primary address
 478 .Fa  padval
 479 and the optional secondary address
 480 .Fa sadval .
 481 If a listener was found, the value pointed to by
 482 .Fa listenflag
 483 will be set to a non-zero value.
 484 .Em This function is currently not implemented.
 485 .Pp
 486 The function
 487 .Fn ibloc
 488 turns the device into local mode.
 489 .Pp
 490 The function
 491 .Fn ibonl
 492 is used to close or reinitialize a device handle.
 493 If parameter
 494 .Fa v
 495 is passed as zero, the handle will be closed, and cannot be used
 496 again.
 497 If it is passed as a non-zero value, all parameters of the handle
 498 will be returned to their defaults;
 499 .Em this functionality is currently unsupported.
 500 .Pp
 501 The function
 502 .Fn ibpad
 503 is used to change the primary address of the device being communicated
 504 with to
 505 .Fa pad .
 506 See
 507 .Fn ibdev
 508 for an explanation.
 509 .Pp
 510 The function
 511 .Fn ibpct
 512 is used to make the device associated with the handle the
 513 controller-in-charge.
 514 .Em This function is currently not implemented.
 515 .Pp
 516 The function
 517 .Fn ibpoke
 518 is obsolete, and not implemented.
 519 .Pp
 520 The function
 521 .Fn ibppc
 522 is used to configure the parallel poll response to
 523 .Fa v .
 524 .Em This function is currently not implemented.
 525 .Pp
 526 The function
 527 .Fn ibrd
 528 is used to receive
 529 .Fa cnt
 530 bytes from the device, and store it to the address passed as
 531 .Fa buffer .
 532 .Pp
 533 The function
 534 .Fn ibrda
 535 behaves similar to
 536 .Fn ibrd
 537 except it operates asynchronously, and returns immediately to the
 538 caller.
 539 .Em This function is currently not implemented.
 540 .Pp
 541 The function
 542 .Fn ibrdf
 543 read data from the device, and appends it to the file with the name
 544 .Fa flname .
 545 .Em This function is currently not implemented.
 546 .Pp
 547 The function
 548 .Fn ibrdkey
 549 is obsolete, and not implemented.
 550 .Pp
 551 The function
 552 .Fn ibrpp
 553 performs a parallel poll, and stores the result at the location
 554 pointed to by
 555 .Fa ppr .
 556 .Em This function is currently not implemented.
 557 .Pp
 558 The function
 559 .Fn ibrsc
 560 makes the board specified by the handle the
 561 .Em system controller
 562 if the argument
 563 .Fa v
 564 is non-zero.
 565 .Em This function is currently not implemented.
 566 .Pp
 567 The function
 568 .Fn ibrsp
 569 conducts a serial poll, and stores the result in the byte pointed
 570 to by
 571 .Fa spr .
 572 .Em This function is currently not implemented.
 573 .Pp
 574 The function
 575 .Fn ibrsv
 576 sets the serial poll response of the board to
 577 .Fa v ,
 578 possibly requesting service from the controller if the SRQ bit (0x40)
 579 is set.
 580 .Em This function is currently not implemented.
 581 .Pp
 582 The function
 583 .Fn ibsad
 584 changes the secondary address of the device being communicated with to
 585 .Fa sad .
 586 See
 587 .Fn ibdev
 588 for an explanation.
 589 .Pp
 590 The function
 591 .Fn ibsgnl
 592 is obsolete, and not implemented.
 593 .Pp
 594 The function
 595 .Fn ibsic
 596 asserts the
 597 .Em Interface Clear (IFC)
 598 signal line on the bus for at least 100 microseconds.
 599 This will make all devices attached to the bus to unlisten and untalk.
 600 This function should only be executed on the system controller.
 601 .Pp
 602 The function
 603 .Fn ibsre
 604 asserts the
 605 .Em Remote Enable (REN)
 606 signal line on the bus if argument
 607 .Fa v
 608 is non-zero, or deasserts it otherwise.
 609 .Em This function is currently not implemented.
 610 .Pp
 611 The function
 612 .Fn ibsrq
 613 is obsolete, and not implemented.
 614 .Pp
 615 The function
 616 .Fn ibstop
 617 stops or aborts any asynchronous I/O operation.
 618 .Em This function is currently not implemented.
 619 .Pp
 620 The function
 621 .Fn ibtmo
 622 reconfigures the communication timeout.
 623 See
 624 .Fn ibdev
 625 for an explanation.
 626 .Pp
 627 The function
 628 .Fn ibtrap
 629 is obsolete, and not implemented.
 630 .Pp
 631 The function
 632 .Fn ibtrg
 633 sends a
 634 .Em Group Execute Trigger (GET)
 635 command to the device.
 636 .Pp
 637 The function
 638 .Fn ibwait
 639 waits for a status condition as specified by
 640 .Fa mask .
 641 If
 642 .Fa mask
 643 is given as zero, it returns immediately.
 644 .Em This function is currently not implemented.
 645 .Pp
 646 The function
 647 .Fn ibwrt
 648 is used to send
 649 .Fa cnt
 650 bytes to the device, starting at the address pointed to by
 651 .Fa buffer .
 652 .Pp
 653 The function
 654 .Fn ibwrta
 655 performs the same operation as
 656 .Fn ibwrt
 657 in an asynchronous way, returning immediately to the caller.
 658 .Em This function is currently not implemented.
 659 .Pp
 660 The function
 661 .Fn ibwrtf
 662 opens the file named by
 663 .Fa flname ,
 664 and sends its contents to the device.
 665 .Em This function is currently not implemented.
 666 .Pp
 667 The function
 668 .Fn ibwrtkey
 669 is obsolete, and not implemented.
 670 .Pp
 671 The function
 672 .Fn ibxtrc
 673 is obsolete, and not implemented.
 674 .Sh RETURN VALUES
 675 The function
 676 .Fn ibdev
 677 returns a handle to be used for the remaining functions.
 678 Upon failure, -1 is returned.
 679 .Pp
 680 All other functions return the value of the variable
 681 .Dv ibsta .
 682 .Sh DIAGNOSTICS
 683 None.
 684 .Sh COMPATIBILITY
 685 The
 686 .Nm
 687 library tries to be compatible with the Linux GPIB library,
 688 which in turn appears to be compatible with the GPIB library
 689 shipped by National Instruments.
 690 .Sh ERRORS
 691 Errors in the functions above might set
 692 .Dv errno
 693 to one of these values:
 694 .Bl -tag -width Er
 695 .It Bq Er ENOENT
 696 No such file or directory.
 697 .It Bq Er EIO
 698 Input/output error.
 699 .It Bq Er ENXIO
 700 Device not configured.
 701 .It Bq Er E2BIG
 702 Argument list too long.
 703 .It Bq Er ENOMEM
 704 Cannot allocate memory.
 705 .It Bq Er EACCES
 706 Permission denied.
 707 .It Bq Er EFAULT
 708 Bad address.
 709 .It Bq Er EBUSY
 710 Device busy.
 711 .It Bq Er EINVAL
 712 Invalid argument.
 713 .It Bq Er ENFILE
 714 Too many open files in system.
 715 .It Bq Er EMFILE
 716 Too many open files.
 717 .It Bq Er EOPNOTSUPP
 718 Operation not supported.
 719 .El
 720 .Sh SEE ALSO
 721 .Xr gpib 4
 722 .Sh HISTORY
 723 The
 724 .Nm
 725 library was written by
 726 .An Poul-Henning Kamp
 727 and first appeared in
 728 .Fx 5.4 .
 729 .Sh AUTHORS
 730 This manual page was written by
 731 .An J\(:org Wunsch .
 732 .Sh BUGS
 733 Currently, the library can only handle a single
 734 .Xr gpib 4
 735 device with instance number 0.
 736 .Pp
 737 Many functions are currently not implemented, see above for details.