Print this page
10521 Convert iec61883(7I) to mandoc
   1 IEC61883(7I)                    Ioctl Requests                    IEC61883(7I)
   2 
   3 
   4 
   5 NAME
   6        iec61883 - IEC 61883 interfaces
   7 
   8 SYNOPSIS
   9        #include <sys/av/iec61883.h>
  10 
  11 
  12 DESCRIPTION
  13        The set of interfaces described in this man page can be used to control
  14        and exchange data with consumer audio/video devices using protocols
  15        specified inIEC 61883 Consumer Electronic Audio/Video Equipment -
  16        Digital Interface, including Common Isochronous Packet (CIP),
  17        Connection Management Procedures (CMP) and Function Control Protocol
  18        (FCP).
  19 



  20 
  21        An iec61883 compliant driver exports two device nodes for isochronous
  22        and for asynchronous transactions. See the FILES section of this man
  23        page for the namespace definition.
  24 
  25    Isochronous Transfers
  26        Two methods are provided to receive/transmit isochronous data: using
  27        mmap(2) in combination with ioctl(2), and read(2) or write(2).
  28 
  29    Mmap/Ioctl
  30        This method provides better performance and finer-grained control than
  31        read/write, and is a method of choice for most applications. The data
  32        buffer is mapped into a user process address space, which means no data
  33        copying between the kernel and an application is necessary.
  34        Synchronization between user processes and the driver is performed
  35        using ioctl(2) commands.
  36 
  37 
  38        An application allocates resources for isochronous transfer using
  39        IEC61883_ISOCH_INIT. Then the data buffer can be mapped into the
  40        process space using mmap(2).
  41 
  42 
  43        A circular data buffer consists of one or more equal size frame buffers
  44        (further referred to as frames, unless to avoid ambiguity with AV
  45        frames).  Frames are numbered starting with zero and are always
  46        transferred sequentially.  Frames consist equal sized packets. Each
  47        packet contains a CIP header and one or more data blocks.
  48 
  49 
  50        A driver and an application act as a producer and a consumer: producer
  51        supplies full frames (filled with data) to the consumer, and the
  52        producer is not allowed to access those frames until the consumer
  53        claims them empty.
  54 
  55 
  56        A transfer can be initiated and suspended with IEC61883_START and
  57        IEC61883_STOP commands respectively. IEC61883_RECV or IEC61883_XMIT is
  58        used for producer-consumer synchronization.
  59 
  60    Read/Write
  61        Using this method, an application calls read(2) or write(2) to receive
  62        or transmit a specified amount of data. Bus-specific overhead, such as
  63        isochronous packet headers, is handled by the driver and is not exposed
  64        to applications. Data returned by read(2) contains CIP headers and data
  65        blocks. Empty packets are not returned by read(2). write(2) data should
  66        meet the same requirements.
  67 
  68 
  69        If one or more channels have been allocated since open(2) (see
  70        IEC61883_ISOCH_INIT), the data is received/transmitted using channel
  71        that was created the last.
  72 
  73 
  74        If no channels were allocated, the driver uses the broadcast channel by
  75        default and allocates the default-size data buffer. During transmit,
  76        the first packet's CIP header is used to auto-detect the data format.
  77        If it is one of the formats supported by the driver, it is properly
  78        transmitted (with inserted empty packets and timestamps).
  79 
  80 
  81        For both methods, if during transmit the driver runs out of data, it
  82        transmits empty packets containing only a CIP header of the next to be
  83        transmitted packet, as defined in IEC 61883-1.
  84 
  85    Connection Management Procedures
  86        Applications wishing to follow Connection Management Procedures (CMP)
  87        in combination with isochronous transfers should use the ioctl(2)
  88        IEC61883_PLUG_INIT, IEC61883_PLUG_FINI, IEC61883_PLUG_REG_READ and
  89        IEC61883_PLUG_REG_CAS commands.
  90 
  91    Asynchronous Transactions
  92        read(2), write(2), ioctl(2), and poll(2) can be used with asynchronous
  93        nodes. Asynchronous data exchange between a driver and an application
  94        utilizes a common data structure called asynchronous request (ARQ):
  95 
  96          typedef struct iec61883_arq {
  97                  int        arq_type;
  98                  int        arq_len;
  99                  union {
 100                          uint32_t   quadlet;
 101                          uint64_t   octlet;
 102                          uint8_t    buf[8];
 103                  } arq_data;
 104          } iec61883_arq_t;
 105 
 106 
 107 
 108 
 109        arq_type contains ARQ type:
 110 
 111        IEC61883_ARQ_FCP_CMD
 112        IEC61883_ARQ_FCP_RESP
 113 
 114            FCP command and response frame respectively. Outgoing frames are
 115            sent using write(2), incoming frames are received with read(2).
 116 
 117            See IEC 61883-1 for the FCP frame structure definition.
 118 
 119 
 120        IEC61883_ARQ_BUS_RESET
 121 
 122            Returned by the driver when a bus reset occurs. There is no data
 123            associated with this request type, and arq_len is set to 0.
 124 
 125 
 126 
 127        If arq_len is 4 or 8, then data should be supplied in arq_data.quadlet
 128        or arq_data.octlet respectively, otherwise up to 8 bytes can be put in
 129        arq_data.buf, with the rest of the data following immediately after.
 130 
 131    write(2)
 132        For a request to be sent to a target, an iec61883_arq_t structure along
 133        with associated data is passed to the driver using write(2).  write()
 134        blocks until the request is completed.
 135 
 136    read(2)
 137        A driver collects incoming ARQs in the internal buffer. Buffer size can
 138        be changed using the ioctl(2) command IEC61883_FCP_SET_IBUF_SIZE.
 139 
 140 
 141        Reading an ARQ takes one or two steps depending on data length. An
 142        application first reads sizeof (iec61883_arq_t) bytes: if arq_len is
 143        less than or equal 4, which is usually the case, no additional step is
 144        needed. Otherwise, the remaining arq_len - 4 bytes should be read and
 145        concatenated.
 146 
 147 
 148        read(2) blocks until the specified amount of data is available, unless
 149        O_NONBLOCK or O_NDELAY flag was set during open(2), in which case
 150        read(2) returns immediately.
 151 
 152    poll(2)
 153        Applications can poll(2) asynchronous nodes on the POLLIN event.
 154 
 155    Bus Reset
 156        In case of a bus reset, the driver notifies an application by
 157        generating an ARQ of type IEC61883_ARQ_BUS_RESET.
 158 
 159 
 160        If there were established isochronous connections before bus reset, the
 161        driver attempts to restore all connections as described in IEC 61883
 162        and resume any active transfers that were in progress.
 163 
 164 IOCTLS
 165        The following commands only apply to isochronous nodes:
 166 
 167        IEC61883_ISOCH_INIT
 168 
 169            This command allocates a data buffer and isochronous resources (if
 170            necessary) for the isochronous transfer. The argument is a pointer
 171            to the structure:
 172 
 173              typedef struct iec61883_isoch_init {
 174                    int ii_version;       /* interface version */
 175                    int   ii_pkt_size;    /* packet size */
 176                    int   ii_frame_size;  /* packets/frame */
 177                    int   ii_frame_cnt;   /* # of frames */
 178                    int   ii_direction;   /* xfer direction */
 179                    int   ii_bus_speed;   /* bus speed */
 180                    uint64_t ii_channel;  /* channel mask */
 181                    int   ii_dbs;         /* DBS */
 182                    int   ii_fn;          /* FN */
 183                    int   ii_rate_n;      /* rate numerator */
 184                    int   ii_rate_d;      /* rate denominator */
 185                    int   ii_ts_mode;     /* timestamp mode */
 186                    int   ii_flags;       /* flags */
 187                    int   ii_handle;      /* isoch handle */
 188                    int   ii_frame_rcnt;  /* # of frames */
 189                    off_t   *ii_mmap_off  /* mmap offset */
 190                    int   ii_rchannel;    /* channel */
 191                    int   ii_error;       /* error code */
 192              } iec61883_isoch_init_t;
 193 
 194 
 195            ii_version should be set to IEC61883_V1_0.
 196 
 197            The driver attempts to allocate a data buffer consisting of
 198            ii_frame_cnt frames, with ii_frame_size packets in each frame.
 199            Packet size in bytes is specified by ii_pkt_size specifies and
 200            should be a multiple of 512 and compatible with ii_bus_speed.
 201 
 202            ii_direction can take one of the following values:
 203 
 204            IEC61883_DIR_RECV
 205 
 206                Receiving isochronous data.
 207 
 208 
 209            IEC61883_DIR_XMIT
 210 
 211                Transmitting isochronous data.
 212 
 213            ii_bus_speed chooses bus speed to be used and can be either
 214            IEC61883_S100, IEC61883_S200 or IEC61883_S400.
 215 
 216            ii_channel is a mask that specifies an isochronous channel number
 217            to be used, with the Nth bit representing channel N. When
 218            transmitting data, several bits can be set at a time, in which case
 219            the driver chooses one, for example, 0x3FF means a range from 0 to
 220            9. In case of receive, only one bit can be set.
 221 
 222            ii_dbs specifies data block size in quadlets, for example, DBS
 223            value for SD-DVCR is 0x78. Refer to IEC 61883 for more details on
 224            DBS.
 225 
 226            ii_fn specifies fraction number, which defines the number of blocks
 227            in which a source packet is divided. Allowed values are from 0 to
 228            3. Refer to IEC 61883 for more details on FN.
 229 
 230            Data rate expected by the AV device can be lower than the bus
 231            speed, in which case the driver has to periodically insert empty
 232            packets into the data stream to avoid device buffer overflows. This
 233            rate is specified with a fraction N/D, set by ii_rate_n and
 234            ii_rate_d respectively. Any integer numbers can be used, or the
 235            following predefined constants:
 236 
 237            IEC61883_RATE_N_DV_NTSC IEC61883_RATE_D_DV_NTSC

 238 
 239                Data rate expected by DV-NTSC devices.

 240 
 241 
 242            IEC61883_RATE_N_DV_PAL IEC61883_RATE_D_DV_PAL
 243 
 244                Data rate expected by DV-PAL devices.
 245 
 246            During data transmission, a timestamp based on the current value of
 247            the cycle timer is usually required. ii_ts_mode defines timestamp
 248            mode to be used:
 249 
 250            IEC61883_TS_SYT

 251 
 252                Driver puts a timestamp in the SYT field of the first CIP
 253                header of each frame.
 254 


 255 
 256            IEC61883_TS_NONE
 257 
 258                No timestamps.
 259 
 260            ii_dbs, ii_fn, ii_rate_n, ii_rate_d and ii_ts_mode are only
 261            required for transmission. In other case these should be set to 0.
 262 
 263            ii_flags should be set to 0.
 264 
 265            If command succeeds, ii_handle contains a handle that should be
 266            used with other isochronous commands. ii_frame_rcnt contains the
 267            number of allocated frames (can be less than ii_frame_cnt).
 268            ii_mmap_off contains an offset to be used in mmap(2), for example,
 269            to map an entire data receive buffer:
 270 
 271              pa = mmap(NULL, init.ii_pkt_size *
 272                    init.ii_frame_size * init.ii_frame_rcnt,
 273                    PROT_READ, MAP_PRIVATE, fd, init.ii_mmap_off);
 274 
 275 
 276            ii_rchannel contains channel number.
 277 
 278            In case of command success, ii_error is set to 0; otherwise one of
 279            the following values can be returned:
 280 
 281            IEC61883_ERR_NOMEM
 282 
 283                Not enough memory for the data buffer.
 284 

 285 
 286            IEC61883_ERR_NOCHANNEL
 287 
 288                Cannot allocate isochronous channel.
 289 

 290 
 291            IEC61883_ERR_PKT_SIZE
 292 
 293                Packet size is not allowed at this bus speed.
 294 
 295 
 296            IEC61883_ERR_VERSION
 297 
 298                Interface version is not supported.
 299 
 300 
 301            IEC61883_ERR_INVAL
 302 
 303                One or more the parameters are invalid
 304 
 305 
 306            IEC61883_ERR_OTHER
 307 
 308                Unspecified error type.
 309 
 310 
 311 
 312        IEC61883_ISOCH_FINI
 313 
 314            Argument is a handle returned by IEC61883_ISOCH_INIT. This command
 315            frees any resources associated with this handle. There must be no
 316            active transfers and the data buffer must be unmapped; otherwise
 317            the command fails.
 318 
 319 
 320        IEC61883_START
 321 
 322            This command starts an isochronous transfer. The argument is a
 323            handle returned by IEC61883_ISOCH_INIT.
 324 
 325 
 326        IEC61883_STOP
 327 
 328            This command stops an isochronous transfer. The argument is a
 329            handle returned by IEC61883_ISOCH_INIT.
 330 
 331 
 332        IEC61883_RECV
 333 
 334            This command is used to receive full frames and return empty frames
 335            to the driver. The argument is a pointer to the structure:
 336 
 337              typedef struct iec61883_recv {
 338                      int rx_handle;     /* isoch handle */
 339                      int rx_flags;      /* flags */
 340              iec61883_xfer_t rx_xfer;   /* xfer params */
 341              } iec61883_recv_t;
 342 
 343              typedef struct iec61883_xfer {
 344                      int   xf_empty_idx; /* first empty frame */
 345                      int xf_empty_cnt;   /* empty frame count */
 346                      int   xf_full_idx;  /* first full frame */
 347                      int   xf_full_cnt;  /* full frame count */
 348                      int   xf_error;     /* error */
 349              } iec61883_xfer_t;
 350 
 351 
 352            rx_flags should be set to 0.
 353 
 354            An application sets xf_empty_idx and xf_empty_cnt to indicate
 355            frames it no longer needs. E.g. if a buffer consists of 6 frames,
 356            xf_empty_idx is 4, xf_empty_cnt is 3 - means that frames 4, 5 and 0
 357            can now be reused by the driver. If there are no empty frames, for
 358            example, the first time this command is called, xf_empty_cnt should
 359            be set to 0.
 360 
 361            When the command returns, xf_full_idx and xf_full_cnt specifies the
 362            frames that are full. xf_error is always 0.
 363 
 364            In general, AV frame boundaries are not aligned with the frame
 365            buffer boundaries, because the first received packet might not be
 366            the first packet of an AV frame, and, in contrast with the
 367            read/write method, the driver does not remove empty CIP packets.
 368 
 369            Applications should detect empty packets by comparing adjacent
 370            packets' continuity counters (DBC field of the CIP header).
 371 
 372 
 373        IEC61883_XMIT
 374 
 375            This command is used to transmit full frames and get more empty
 376            frames from the driver. The argument is a pointer to the structure:
 377 
 378              typedef struct iec61883_xmit {
 379                      int   tx_handle;         /* isoch handle */
 380                      int   tx_flags;          /* flags */
 381                      iec61883_xfer_t tx_xfer; /* xfer params */
 382                      int   tx_miss_cnt;       /* missed cycles */
 383               } iec61883_xmit_t;
 384 
 385 
 386            tx_flags should be set to zero.
 387 
 388            The application sets xf_full_idx and xf_full_cnt to specify frames
 389            it wishes to transmit. If there are no frames to transmit (e.g. the
 390            first time this command is called), xf_full_cnt should be set to 0.
 391 
 392            When the command returns, xf_empty_idx and xf_empty_cnt specifies
 393            empty frames which can be to transmit more data. xf_error is always
 394            0.
 395 
 396            tx_miss_cnt contains the number of isochronous cycles missed since
 397            last transfer due to data buffer under run. This can happen when an
 398            application does not supply data fast enough.


 399 
 400            For the purposes of time stamping, the driver considers the first
 401            packet in a frame buffer to be the first packet of an AV frame.
 402 
 403 
 404        IEC61883_PLUG_INIT
 405 
 406            This command returns a handle for the specified plug. The argument
 407            is a pointer to the structure:
 408 
 409              typedef struct iec61883_plug_init {
 410                      int   pi_ver;     /* interface version */
 411                      int   pi_loc;     /* plug location */
 412                      int   pi_type;    /* plug type */
 413                      int   pi_num;     /* plug number */
 414                      int   pi_flags;   /* flags */
 415                      int   pi_handle;  /* plug handle */
 416                      int   pi_rnum;    /* plug number */
 417               } iec61883_plug_init_t;
 418 
 419 
 420            pi_ver should be set to IEC61883_V1_0.
 421 
 422            pi_loc specifies plug location:
 423 
 424            IEC61883_LOC_LOCAL


 425 
 426                On the local unit (local plug). A plug control register (PCR)
 427                is allocated.  Command fails if the plug already exists

 428 
 429 
 430            IEC61883_LOC_REMOTE
 431 
 432                On the remote unit (remote plug). The plug should exist on the
 433                remote unit, otherwise the command fails.
 434 
 435            pi_type specifies isochronous plug type:
 436 
 437            IEC61883_PLUG_IN IEC61883_PLUG_OUT

 438 
 439                Input or output plugs.
 440 


 441 
 442            IEC61883_PLUG_MASTER_IN IEC61883_PLUG_MASTER_OUT
 443 
 444                Master input or master output plug. These plugs always exist on
 445                the local unit.
 446 
 447            pi_num specifies plug number. This should be 0 for master plugs,
 448            and from 0 to 31 for input/output plugs. Alternatively, a special
 449            value IEC61883_PLUG_ANY can be used to let the driver choose a free
 450            plug number, create the plug and return the number in pi_rnum.
 451 
 452            pi_flags should be set to 0.
 453 
 454            If the command succeeds, pi_handle contains a handle that should be
 455            used with other plug commands.
 456 
 457 
 458        IEC61883_PLUG_FINI
 459 
 460            Argument is a handle returned by IEC61883_PLUG_INIT. This command
 461            frees any resources associated with this handle, including the PCR.
 462 
 463 
 464        IEC61883_PLUG_REG_READ
 465 
 466            Read plug register value. The argument is a pointer to the
 467            structure:
 468 
 469              typedef struct iec61883_plug_reg_val {
 470                      int         pr_handle; /* plug handle */
 471                      uint32_t     pr_val;    /* register value */
 472              } iec61883_plug_reg_val_t;
 473 


 474 
 475            pr_handle is a handle returned by IEC61883_PLUG_INIT. Register
 476            value is returned in pr_val.
 477 
 478 
 479        IEC61883_PLUG_REG_CAS
 480 
 481            Atomically compare and swap plug register value. The argument is a
 482            pointer to the structure:
 483 
 484              typedef struct iec61883_plug_reg_lock {
 485                      int        pl_handle; /* plug handle */
 486                      uint32_t   pl_arg;    /* compare arg */
 487                      uint32_t   pl_data;   /* write value */
 488                      UINT32_t   pl_old;    /* original value */
 489              } iec61883_plug_reg_lock_t;
 490 
 491 
 492            pr_handle is a handle returned by IEC61883_PLUG_INIT.
 493 
 494            Original register value is compared with pl_arg and if they are
 495            equal, register value is replaced with pl_data. In any case, the
 496            original value is stored in pl_old.
 497 
 498 
 499 
 500        The following commands only apply to asynchronous nodes:
 501 
 502        IEC61883_ARQ_GET_IBUF_SIZE
 503 
 504            This command returns current incoming ARQ buffer size. The argument
 505            is a pointer to int.
 506 
 507 
 508        IEC61883_ARQ_SET_IBUF_SIZE
 509 
 510            This command changes incoming ARQ buffer size. The argument is the
 511            new buffer size in bytes.
 512 
 513 
 514 FILES
 515        /dev/av/N/async
 516                           Device node for asynchronous data
 517 

 518 
 519        /dev/av/N/isoch
 520                           Device has been disconnected
 521 
 522 
 523 ERRORS
 524        EIO
 525                  Bus operation failed.
 526 
 527                  DMA failure.
 528 

 529 
 530        EFAULT
 531                  ioctl(2) argument points to an illegal address.
 532 


 533 
 534        EINVAL
 535                  Invalid argument or argument combination.
 536 
 537 
 538        ENODEV
 539                  Device has been disconnected.
 540 
 541 
 542 ATTRIBUTES
 543        See attributes(5) for descriptions of the following attributes:
 544 
 545 
 546 
 547 
 548        +----------------+-----------------+
 549        |ATTRIBUTE TYPE  | ATTRIBUTE VALUE |
 550        +----------------+-----------------+
 551        |Architecture    | All             |
 552        +----------------+-----------------+
 553        |Stability level | Committed       |
 554        +----------------+-----------------+
 555 
 556 SEE ALSO
 557        ioctl(2), mmap(2), open(2), poll(2), read(2), write(2), attributes(5),
 558        av1394(7D)
 559 

 560 
 561        IEC 61883 Consumer audio/video equipment - Digital interface
 562 
 563 
 564        IEEE Std 1394-1995 Standard for a High Performance Serial Bus
 565 
 566 
 567 
 568                                 March 27, 2009                    IEC61883(7I)
   1 IEC61883(7I)                    Ioctl Requests                    IEC61883(7I)
   2 


   3 NAME
   4      iec61883 - IEC 61883 interfaces
   5 
   6 SYNOPSIS
   7      #include <sys/av/iec61883.h>
   8 

   9 DESCRIPTION
  10      The set of interfaces described in this man page can be used to control
  11      and exchange data with consumer audio/video devices using protocols
  12      specified in IIEC 61883 Consumer Electronic Audio/Video Equipment -
  13      Digital Interface including Common Isochronous Packet (CIP), Connection
  14      Management Procedures (CMP) and Function Control Protocol (FCP).

  15 
  16      An iec61883 compliant driver exports two device nodes for isochronous and
  17      for asynchronous transactions.  See the FILES section of this man page
  18      for the namespace definition.
  19 




  20    Isochronous Transfers
  21      Two methods are provided to receive/transmit isochronous data: using
  22      mmap(2) in combination with ioctl(2), and read(2) or write(2).
  23 
  24    Mmap/Ioctl
  25      This method provides better performance and finer-grained control than
  26      read/write, and is a method of choice for most applications.  The data
  27      buffer is mapped into a user process address space, which means no data
  28      copying between the kernel and an application is necessary.
  29      Synchronization between user processes and the driver is performed using
  30      ioctl(2) commands.
  31 

  32      An application allocates resources for isochronous transfer using
  33      IEC61883_ISOCH_INIT.  Then the data buffer can be mapped into the process
  34      space using mmap(2).
  35 

  36      A circular data buffer consists of one or more equal size frame buffers
  37      (further referred to as frames, unless to avoid ambiguity with AV
  38      frames).  Frames are numbered starting with zero and are always
  39      transferred sequentially.  Frames consist equal sized packets.  Each
  40      packet contains a CIP header and one or more data blocks.
  41 

  42      A driver and an application act as a producer and a consumer: producer
  43      supplies full frames (filled with data) to the consumer, and the producer
  44      is not allowed to access those frames until the consumer claims them
  45      empty.
  46 

  47      A transfer can be initiated and suspended with IEC61883_START and
  48      IEC61883_STOP commands respectively.  IEC61883_RECV or IEC61883_XMIT is
  49      used for producer-consumer synchronization.
  50 
  51    Read/Write
  52      Using this method, an application calls read(2) or write(2) to receive or
  53      transmit a specified amount of data.  Bus-specific overhead, such as
  54      isochronous packet headers, is handled by the driver and is not exposed
  55      to applications.  Data returned by read(2) contains CIP headers and data
  56      blocks.  Empty packets are not returned by read(2).  write(2) data should
  57      meet the same requirements.
  58 

  59      If one or more channels have been allocated since open(2) (see
  60      IEC61883_ISOCH_INIT), the data is received/transmitted using channel that
  61      was created the last.
  62 

  63      If no channels were allocated, the driver uses the broadcast channel by
  64      default and allocates the default-size data buffer.  During transmit, the
  65      first packet's CIP header is used to auto-detect the data format.  If it
  66      is one of the formats supported by the driver, it is properly transmitted
  67      (with inserted empty packets and timestamps).
  68 

  69      For both methods, if during transmit the driver runs out of data, it
  70      transmits empty packets containing only a CIP header of the next to be
  71      transmitted packet, as defined in IEC 61883-1.
  72 
  73    Connection Management Procedures
  74      Applications wishing to follow Connection Management Procedures (CMP) in
  75      combination with isochronous transfers should use the ioctl(2)
  76      IEC61883_PLUG_INIT, IEC61883_PLUG_FINI, IEC61883_PLUG_REG_READ and
  77      IEC61883_PLUG_REG_CAS commands.
  78 
  79    Asynchronous Transactions
  80      read(2), write(2), ioctl(2), and poll(2) can be used with asynchronous
  81      nodes.  Asynchronous data exchange between a driver and an application
  82      utilizes a common data structure called asynchronous request (ARQ):
  83 
  84        typedef struct iec61883_arq {
  85                int        arq_type;
  86                int        arq_len;
  87                union {
  88                        uint32_t   quadlet;
  89                        uint64_t   octlet;
  90                        uint8_t    buf[8];
  91                } arq_data;
  92        } iec61883_arq_t;
  93 



  94      arq_type contains ARQ type:
  95 
  96      IEC61883_ARQ_FCP_CMD
  97      IEC61883_ARQ_FCP_RESP
  98 
  99         FCP command and response frame respectively.  Outgoing frames are sent
 100         using write(2), incoming frames are received with read(2).
 101 
 102         See IIEC 61883-1 for the FCP frame structure definition.
 103 

 104      IEC61883_ARQ_BUS_RESET
 105 
 106         Returned by the driver when a bus reset occurs.  There is no data
 107         associated with this request type, and arq_len is set to 0.
 108 
 109      If arq_len is 4 or 8, then data should be supplied in arq_data.quadlet or
 110      arq_data.octlet respectively, otherwise up to 8 bytes can be put in


 111      arq_data.buf, with the rest of the data following immediately after.
 112 
 113    write(2)
 114      For a request to be sent to a target, an iec61883_arq_t structure along
 115      with associated data is passed to the driver using write(2).  write(2)
 116      blocks until the request is completed.
 117 
 118    read(2)
 119      A driver collects incoming ARQs in the internal buffer.  Buffer size can
 120      be changed using the ioctl(2) command IEC61883_FCP_SET_IBUF_SIZE.
 121 

 122      Reading an ARQ takes one or two steps depending on data length.  An
 123      application first reads `sizeof (iec61883_arq_t)' bytes: if arq_len is
 124      less than or equal 4, which is usually the case, no additional step is
 125      needed.  Otherwise, the remaining `arq_len - 4' bytes should be read and
 126      concatenated.
 127 

 128      read(2) blocks until the specified amount of data is available, unless
 129      O_NONBLOCK or O_NDELAY flag was set during open(2), in which case read(2)
 130      returns immediately.
 131 
 132    poll(2)
 133      Applications can poll(2) asynchronous nodes on the POLLIN event.
 134 
 135    Bus Reset
 136      In case of a bus reset, the driver notifies an application by generating
 137      an ARQ of type IEC61883_ARQ_BUS_RESET.
 138 

 139      If there were established isochronous connections before bus reset, the
 140      driver attempts to restore all connections as described in IEC 61883 and
 141      resume any active transfers that were in progress.
 142 
 143 IOCTLS
 144      The following commands only apply to isochronous nodes:
 145 
 146      IEC61883_ISOCH_INIT
 147 
 148         This command allocates a data buffer and isochronous resources (if
 149         necessary) for the isochronous transfer.  The argument is a pointer to
 150         the structure:
 151 
 152           typedef struct iec61883_isoch_init {
 153                 int   ii_version;     /* interface version */
 154                 int   ii_pkt_size;    /* packet size */
 155                 int   ii_frame_size;  /* packets/frame */
 156                 int   ii_frame_cnt;   /* # of frames */
 157                 int   ii_direction;   /* xfer direction */
 158                 int   ii_bus_speed;   /* bus speed */
 159                 uint64_t ii_channel;  /* channel mask */
 160                 int   ii_dbs;         /* DBS */
 161                 int   ii_fn;          /* FN */
 162                 int   ii_rate_n;      /* rate numerator */
 163                 int   ii_rate_d;      /* rate denominator */
 164                 int   ii_ts_mode;     /* timestamp mode */
 165                 int   ii_flags;       /* flags */
 166                 int   ii_handle;      /* isoch handle */
 167                 int   ii_frame_rcnt;  /* # of frames */
 168                 off_t *ii_mmap_off    /* mmap offset */
 169                 int   ii_rchannel;    /* channel */
 170                 int   ii_error;       /* error code */
 171           } iec61883_isoch_init_t;
 172 

 173         ii_version should be set to IEC61883_V1_0.
 174 
 175         The driver attempts to allocate a data buffer consisting of
 176         ii_frame_cnt frames, with ii_frame_size packets in each frame.  Packet
 177         size in bytes is specified by ii_pkt_size specifies and should be a
 178         multiple of 512 and compatible with ii_bus_speed.
 179 
 180         ii_direction can take one of the following values:
 181 
 182         IEC61883_DIR_RECV  Receiving isochronous data.
 183 
 184         IEC61883_DIR_XMIT  Transmitting isochronous data.
 185 





 186         ii_bus_speed chooses bus speed to be used and can be either
 187         IEC61883_S100, IEC61883_S200 or IEC61883_S400.
 188 
 189         ii_channel is a mask that specifies an isochronous channel number to
 190         be used, with the Nth bit representing channel N.  When transmitting
 191         data, several bits can be set at a time, in which case the driver
 192         chooses one, for example, 0x3FF means a range from 0 to 9.  In case of
 193         receive, only one bit can be set.
 194 
 195         ii_dbs specifies data block size in quadlets, for example, DBS value
 196         for SD-DVCR is 0x78.  Refer to IEC 61883 for more details on DBS.

 197 
 198         ii_fn specifies fraction number, which defines the number of blocks in
 199         which a source packet is divided.  Allowed values are from 0 to 3.
 200         Refer to IEC 61883 for more details on FN.
 201 
 202         Data rate expected by the AV device can be lower than the bus speed,
 203         in which case the driver has to periodically insert empty packets into
 204         the data stream to avoid device buffer overflows.  This rate is
 205         specified with a fraction N/D, set by ii_rate_n and ii_rate_d
 206         respectively.  Any integer numbers can be used, or the following
 207         predefined constants:
 208 
 209         IEC61883_RATE_N_DV_NTSC
 210         IEC61883_RATE_D_DV_NTSC  Data rate expected by DV-NTSC devices.
 211 
 212         IEC61883_RATE_N_DV_PAL
 213         IEC61883_RATE_D_DV_PAL   Data rate expected by DV-PAL devices.
 214 





 215         During data transmission, a timestamp based on the current value of
 216         the cycle timer is usually required.  ii_ts_mode defines timestamp
 217         mode to be used:
 218 
 219         IEC61883_TS_SYT   Driver puts a timestamp in the SYT field of the
 220                           first CIP header of each frame.
 221 
 222         IEC61883_TS_NONE  No timestamps.

 223 
 224         ii_dbs, ii_fn, ii_rate_n, ii_rate_d and ii_ts_mode are only required
 225         for transmission.  In other case these should be set to 0.
 226 







 227         ii_flags should be set to 0.
 228 
 229         If command succeeds, ii_handle contains a handle that should be used
 230         with other isochronous commands.  ii_frame_rcnt contains the number of
 231         allocated frames (can be less than ii_frame_cnt).  ii_mmap_off
 232         contains an offset to be used in mmap(2), for example, to map an
 233         entire data receive buffer:
 234 
 235           pa = mmap(NULL, init.ii_pkt_size *
 236                 init.ii_frame_size * init.ii_frame_rcnt,
 237                 PROT_READ, MAP_PRIVATE, fd, init.ii_mmap_off);
 238 

 239         ii_rchannel contains channel number.
 240 
 241         In case of command success, ii_error is set to 0; otherwise one of the
 242         following values can be returned:
 243 
 244         IEC61883_ERR_NOMEM      Not enough memory for the data buffer.
 245 
 246         IEC61883_ERR_NOCHANNEL  Cannot allocate isochronous channel.
 247 
 248         IEC61883_ERR_PKT_SIZE   Packet size is not allowed at this bus speed.
 249 
 250         IEC61883_ERR_VERSION    Interface version is not supported.
 251 
 252         IEC61883_ERR_INVAL      One or more the parameters are invalid
 253 
 254         IEC61883_ERR_OTHER      Unspecified error type.
 255 





















 256      IEC61883_ISOCH_FINI
 257 
 258         Argument is a handle returned by IEC61883_ISOCH_INIT.  This command
 259         frees any resources associated with this handle.  There must be no
 260         active transfers and the data buffer must be unmapped; otherwise the
 261         command fails.
 262 

 263      IEC61883_START
 264 
 265         This command starts an isochronous transfer.  The argument is a handle
 266         returned by IEC61883_ISOCH_INIT.
 267 

 268      IEC61883_STOP
 269 
 270         This command stops an isochronous transfer.  The argument is a handle
 271         returned by IEC61883_ISOCH_INIT.
 272 

 273      IEC61883_RECV
 274 
 275         This command is used to receive full frames and return empty frames to
 276         the driver.  The argument is a pointer to the structure:
 277 
 278           typedef struct iec61883_recv {
 279                   int   rx_handle;    /* isoch handle */
 280                   int   rx_flags;     /* flags */
 281                   iec61883_xfer_t rx_xfer;   /* xfer params */
 282           } iec61883_recv_t;
 283 
 284           typedef struct iec61883_xfer {
 285                   int   xf_empty_idx; /* first empty frame */
 286                   int   xf_empty_cnt; /* empty frame count */
 287                   int   xf_full_idx;  /* first full frame */
 288                   int   xf_full_cnt;  /* full frame count */
 289                   int   xf_error;     /* error */
 290           } iec61883_xfer_t;
 291 

 292         rx_flags should be set to 0.
 293 
 294         An application sets xf_empty_idx and xf_empty_cnt to indicate frames
 295         it no longer needs.  E. g.  if a buffer consists of 6 frames,
 296         xf_empty_idx is 4, xf_empty_cnt is 3 - means that frames 4, 5 and 0
 297         can now be reused by the driver.  If there are no empty frames, for
 298         example, the first time this command is called, xf_empty_cnt should be
 299         set to 0.
 300 
 301         When the command returns, xf_full_idx and xf_full_cnt specifies the
 302         frames that are full.  xf_error is always 0.
 303 
 304         In general, AV frame boundaries are not aligned with the frame buffer
 305         boundaries, because the first received packet might not be the first
 306         packet of an AV frame, and, in contrast with the read/write method,
 307         the driver does not remove empty CIP packets.
 308 
 309         Applications should detect empty packets by comparing adjacent
 310         packets' continuity counters (DBC field of the CIP header).
 311 

 312      IEC61883_XMIT
 313 
 314         This command is used to transmit full frames and get more empty frames
 315         from the driver.  The argument is a pointer to the structure:
 316 
 317           typedef struct iec61883_xmit {
 318                   int   tx_handle;         /* isoch handle */
 319                   int   tx_flags;          /* flags */
 320                   iec61883_xfer_t tx_xfer; /* xfer params */
 321                   int   tx_miss_cnt;       /* missed cycles */
 322            } iec61883_xmit_t;
 323 

 324         tx_flags should be set to zero.
 325 
 326         The application sets xf_full_idx and xf_full_cnt to specify frames it
 327         wishes to transmit.  If there are no frames to transmit (e. g. the
 328         first time this command is called), xf_full_cnt should be set to 0.
 329 
 330         When the command returns, xf_empty_idx and xf_empty_cnt specifies
 331         empty frames which can be to transmit more data.  xf_error is always
 332         0.
 333 
 334         tx_miss_cnt contains the number of isochronous cycles missed since
 335         last transfer due to data buffer under run.  This can happen when an
 336         application does not supply data fast enough.  For the purposes of
 337         time stamping, the driver considers the first packet in a frame buffer
 338         to be the first packet of an AV frame.
 339 




 340      IEC61883_PLUG_INIT
 341 
 342         This command returns a handle for the specified plug.  The argument is
 343         a pointer to the structure:
 344 
 345           typedef struct iec61883_plug_init {
 346                   int   pi_ver;     /* interface version */
 347                   int   pi_loc;     /* plug location */
 348                   int   pi_type;    /* plug type */
 349                   int   pi_num;     /* plug number */
 350                   int   pi_flags;   /* flags */
 351                   int   pi_handle;  /* plug handle */
 352                   int   pi_rnum;    /* plug number */
 353            } iec61883_plug_init_t;
 354 

 355         pi_ver should be set to IEC61883_V1_0.
 356 
 357         pi_loc specifies plug location:
 358 
 359         IEC61883_LOC_LOCAL   On the local unit (local plug).  A plug control
 360                              register (PCR) is allocated.  Command fails if
 361                              the plug already exists
 362 
 363         IEC61883_LOC_REMOTE  On the remote unit (remote plug).  The plug
 364                              should exist on the remote unit, otherwise the
 365                              command fails.
 366 






 367         pi_type specifies isochronous plug type:
 368 
 369         IEC61883_PLUG_IN
 370         IEC61883_PLUG_OUT
 371 
 372            Input or output plugs.
 373 
 374         IEC61883_PLUG_MASTER_IN
 375         IEC61883_PLUG_MASTER_OUT
 376 


 377            Master input or master output plug.  These plugs always exist on
 378            the local unit.
 379 
 380         pi_num specifies plug number.  This should be 0 for master plugs, and
 381         from 0 to 31 for input/output plugs.  Alternatively, a special value
 382         IEC61883_PLUG_ANY can be used to let the driver choose a free plug
 383         number, create the plug and return the number in pi_rnum.
 384 
 385         pi_flags should be set to 0.
 386 
 387         If the command succeeds, pi_handle contains a handle that should be
 388         used with other plug commands.
 389 

 390      IEC61883_PLUG_FINI
 391 
 392         Argument is a handle returned by IEC61883_PLUG_INIT.  This command
 393         frees any resources associated with this handle, including the PCR.
 394 

 395      IEC61883_PLUG_REG_READ
 396 
 397         Read plug register value.  The argument is a pointer to the structure:

 398 
 399           typedef struct iec61883_plug_reg_val {
 400                   int         pr_handle; /* plug handle */
 401                   uint32_t    pr_val;    /* register value */
 402           } iec61883_plug_reg_val_t;
 403 
 404         pr_handle is a handle returned by IEC61883_PLUG_INIT.  Register value
 405         is returned in pr_val.
 406 




 407      IEC61883_PLUG_REG_CAS
 408 
 409         Atomically compare and swap plug register value.  The argument is a
 410         pointer to the structure:
 411 
 412           typedef struct iec61883_plug_reg_lock {
 413                   int        pl_handle; /* plug handle */
 414                   uint32_t   pl_arg;    /* compare arg */
 415                   uint32_t   pl_data;   /* write value */
 416                   UINT32_t   pl_old;    /* original value */
 417           } iec61883_plug_reg_lock_t;
 418 

 419         pr_handle is a handle returned by IEC61883_PLUG_INIT.
 420 
 421         Original register value is compared with pl_arg and if they are equal,
 422         register value is replaced with pl_data.  In any case, the original
 423         value is stored in pl_old.
 424 


 425      The following commands only apply to asynchronous nodes:
 426 
 427      IEC61883_ARQ_GET_IBUF_SIZE
 428 
 429         This command returns current incoming ARQ buffer size.  The argument
 430         is a pointer to int.
 431 

 432      IEC61883_ARQ_SET_IBUF_SIZE
 433 
 434         This command changes incoming ARQ buffer size.  The argument is the
 435         new buffer size in bytes.
 436 

 437 FILES
 438      /dev/av/N/async  Device node for asynchronous data

 439 
 440      /dev/av/N/isoch  Device has been disconnected
 441 




 442 ERRORS
 443      EIO     Bus operation failed.  DMA failure.

 444 
 445      EFAULT  ioctl(2) argument points to an illegal address.
 446 
 447      EINVAL  Invalid argument or argument combination.
 448 
 449      ENODEV  Device has been disconnected.

 450 
 451 ARCHITECTURE
 452      All
 453 
 454 INTERFACE STABILITY
 455      Committed
 456 



















 457 SEE ALSO
 458      ioctl(2), mmap(2), open(2), poll(2), read(2), write(2), attributes(5),
 459      av1394(7D)
 460 
 461      IIEC 61883 Consumer audio/video equipment - Digital interface.
 462 
 463      IEEE Std 1394-1995 Standard for a High Performance Serial Bus.
 464 
 465 illumos                          July 9, 2018                          illumos