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