drivers/staging/tidspbridge/include/dspbridge/dspdefs.h

   1 /*
   2  * dspdefs.h
   3  *
   4  * DSP-BIOS Bridge driver support functions for TI OMAP processors.
   5  *
   6  * Bridge driver entry point and interface function declarations.
   7  *
   8  * Notes:
   9  *   The DSP API obtains it's function interface to
  10  *   the Bridge driver via a call to bridge_drv_entry().
  11  *
  12  *   Bridge services exported to Bridge drivers are initialized by the
  13  *   DSP API on behalf of the Bridge driver.
  14  *
  15  *   Bridge function DBC Requires and Ensures are also made by the DSP API on
  16  *   behalf of the Bridge driver, to simplify the Bridge driver code.
  17  *
  18  * Copyright (C) 2005-2006 Texas Instruments, Inc.
  19  *
  20  * This package is free software; you can redistribute it and/or modify
  21  * it under the terms of the GNU General Public License version 2 as
  22  * published by the Free Software Foundation.
  23  *
  24  * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
  25  * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  26  * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  27  */
  28
  29 #ifndef DSPDEFS_
  30 #define DSPDEFS_
  31
  32 #include <dspbridge/brddefs.h>
  33 #include <dspbridge/cfgdefs.h>
  34 #include <dspbridge/chnlpriv.h>
  35 #include <dspbridge/dehdefs.h>
  36 #include <dspbridge/devdefs.h>
  37 #include <dspbridge/iodefs.h>
  38 #include <dspbridge/msgdefs.h>
  39
  40 /*
  41  *  Any IOCTLS at or above this value are reserved for standard Bridge driver
  42  *  interfaces.
  43  */
  44 #define BRD_RESERVEDIOCTLBASE   0x8000
  45
  46 /* Handle to Bridge driver's private device context. */
  47 struct bridge_dev_context;
  48
  49 /*--------------------------------------------------------------------------- */
  50 /* BRIDGE DRIVER FUNCTION TYPES */
  51 /*--------------------------------------------------------------------------- */
  52
  53 /*
  54  *  ======== bridge_brd_monitor ========
  55  *  Purpose:
  56  *      Bring the board to the BRD_IDLE (monitor) state.
  57  *  Parameters:
  58  *      dev_ctxt:    Handle to Bridge driver defined device context.
  59  *  Returns:
  60  *      0:        Success.
  61  *      -ETIMEDOUT:  Timeout occured waiting for a response from hardware.
  62  *      -EPERM:      Other, unspecified error.
  63  *  Requires:
  64  *      dev_ctxt != NULL
  65  *  Ensures:
  66  *      0:        Board is in BRD_IDLE state;
  67  *      else:           Board state is indeterminate.
  68  */
  69 typedef int(*fxn_brd_monitor) (struct bridge_dev_context *dev_ctxt);
  70
  71 /*
  72  *  ======== fxn_brd_setstate ========
  73  *  Purpose:
  74  *      Sets the Bridge driver state
  75  *  Parameters:
  76  *      dev_ctxt:    Handle to Bridge driver defined device info.
  77  *      brd_state:      Board state
  78  *  Returns:
  79  *      0:        Success.
  80  *      -EPERM:      Other, unspecified error.
  81  *  Requires:
  82  *      dev_ctxt != NULL;
  83  *      brd_state  <= BRD_LASTSTATE.
  84  *  Ensures:
  85  *      brd_state  <= BRD_LASTSTATE.
  86  *  Update the Board state to the specified state.
  87  */
  88 typedef int(*fxn_brd_setstate) (struct bridge_dev_context
  89                                        * dev_ctxt, u32 brd_state);
  90
  91 /*
  92  *  ======== bridge_brd_start ========
  93  *  Purpose:
  94  *      Bring board to the BRD_RUNNING (start) state.
  95  *  Parameters:
  96  *      dev_ctxt:    Handle to Bridge driver defined device context.
  97  *      dsp_addr:       DSP address at which to start execution.
  98  *  Returns:
  99  *      0:        Success.
 100  *      -ETIMEDOUT:  Timeout occured waiting for a response from hardware.
 101  *      -EPERM:      Other, unspecified error.
 102  *  Requires:
 103  *      dev_ctxt != NULL
 104  *      Board is in monitor (BRD_IDLE) state.
 105  *  Ensures:
 106  *      0:        Board is in BRD_RUNNING state.
 107  *                      Interrupts to the PC are enabled.
 108  *      else:           Board state is indeterminate.
 109  */
 110 typedef int(*fxn_brd_start) (struct bridge_dev_context
 111                                     * dev_ctxt, u32 dsp_addr);
 112
 113 /*
 114  *  ======== bridge_brd_mem_copy ========
 115  *  Purpose:
 116  *  Copy memory from one DSP address to another
 117  *  Parameters:
 118  *      dev_context:    Pointer to context handle
 119  *  dsp_dest_addr:  DSP address to copy to
 120  *  dsp_src_addr:   DSP address to copy from
 121  *  ul_num_bytes: Number of bytes to copy
 122  *  mem_type:   What section of memory to copy to
 123  *  Returns:
 124  *      0:        Success.
 125  *      -EPERM:      Other, unspecified error.
 126  *  Requires:
 127  *      dev_context != NULL
 128  *  Ensures:
 129  *      0:        Board is in BRD_RUNNING state.
 130  *                      Interrupts to the PC are enabled.
 131  *      else:           Board state is indeterminate.
 132  */
 133 typedef int(*fxn_brd_memcopy) (struct bridge_dev_context
 134                                       * dev_ctxt,
 135                                       u32 dsp_dest_addr,
 136                                       u32 dsp_src_addr,
 137                                       u32 ul_num_bytes, u32 mem_type);
 138 /*
 139  *  ======== bridge_brd_mem_write ========
 140  *  Purpose:
 141  *      Write a block of host memory into a DSP address, into a given memory
 142  *      space.  Unlike bridge_brd_write, this API does reset the DSP
 143  *  Parameters:
 144  *      dev_ctxt:    Handle to Bridge driver defined device info.
 145  *      dsp_addr:       Address on DSP board (Destination).
 146  *      host_buf:       Pointer to host buffer (Source).
 147  *      ul_num_bytes:     Number of bytes to transfer.
 148  *      mem_type:       Memory space on DSP to which to transfer.
 149  *  Returns:
 150  *      0:        Success.
 151  *      -ETIMEDOUT:  Timeout occured waiting for a response from hardware.
 152  *      -EPERM:      Other, unspecified error.
 153  *  Requires:
 154  *      dev_ctxt != NULL;
 155  *      host_buf != NULL.
 156  *  Ensures:
 157  */
 158 typedef int(*fxn_brd_memwrite) (struct bridge_dev_context
 159                                        * dev_ctxt,
 160                                        u8 *host_buf,
 161                                        u32 dsp_addr, u32 ul_num_bytes,
 162                                        u32 mem_type);
 163
 164 /*
 165  *  ======== bridge_brd_mem_map ========
 166  *  Purpose:
 167  *      Map a MPU memory region to a DSP/IVA memory space
 168  *  Parameters:
 169  *      dev_ctxt:    Handle to Bridge driver defined device info.
 170  *      ul_mpu_addr:      MPU memory region start address.
 171  *      virt_addr:      DSP/IVA memory region u8 address.
 172  *      ul_num_bytes:     Number of bytes to map.
 173  *      map_attrs:       Mapping attributes (e.g. endianness).
 174  *  Returns:
 175  *      0:        Success.
 176  *      -EPERM:      Other, unspecified error.
 177  *  Requires:
 178  *      dev_ctxt != NULL;
 179  *  Ensures:
 180  */
 181 typedef int(*fxn_brd_memmap) (struct bridge_dev_context
 182                                      * dev_ctxt, u32 ul_mpu_addr,
 183                                      u32 virt_addr, u32 ul_num_bytes,
 184                                      u32 map_attr,
 185                                      struct page **mapped_pages);
 186
 187 /*
 188  *  ======== bridge_brd_mem_un_map ========
 189  *  Purpose:
 190  *      UnMap an MPU memory region from DSP/IVA memory space
 191  *  Parameters:
 192  *      dev_ctxt:    Handle to Bridge driver defined device info.
 193  *      virt_addr:      DSP/IVA memory region u8 address.
 194  *      ul_num_bytes:     Number of bytes to unmap.
 195  *  Returns:
 196  *      0:        Success.
 197  *      -EPERM:      Other, unspecified error.
 198  *  Requires:
 199  *      dev_ctxt != NULL;
 200  *  Ensures:
 201  */
 202 typedef int(*fxn_brd_memunmap) (struct bridge_dev_context
 203                                        * dev_ctxt,
 204                                        u32 virt_addr, u32 ul_num_bytes);
 205
 206 /*
 207  *  ======== bridge_brd_stop ========
 208  *  Purpose:
 209  *      Bring board to the BRD_STOPPED state.
 210  *  Parameters:
 211  *      dev_ctxt:    Handle to Bridge driver defined device context.
 212  *  Returns:
 213  *      0:        Success.
 214  *      -ETIMEDOUT:  Timeout occured waiting for a response from hardware.
 215  *      -EPERM:      Other, unspecified error.
 216  *  Requires:
 217  *      dev_ctxt != NULL
 218  *  Ensures:
 219  *      0:        Board is in BRD_STOPPED (stop) state;
 220  *                      Interrupts to the PC are disabled.
 221  *      else:           Board state is indeterminate.
 222  */
 223 typedef int(*fxn_brd_stop) (struct bridge_dev_context *dev_ctxt);
 224
 225 /*
 226  *  ======== bridge_brd_status ========
 227  *  Purpose:
 228  *      Report the current state of the board.
 229  *  Parameters:
 230  *      dev_ctxt:    Handle to Bridge driver defined device context.
 231  *      board_state:    Ptr to BRD status variable.
 232  *  Returns:
 233  *      0:
 234  *  Requires:
 235  *      board_state != NULL;
 236  *      dev_ctxt != NULL
 237  *  Ensures:
 238  *      *board_state is one of
 239  *       {BRD_STOPPED, BRD_IDLE, BRD_RUNNING, BRD_UNKNOWN};
 240  */
 241 typedef int(*fxn_brd_status) (struct bridge_dev_context *dev_ctxt,
 242                                      int *board_state);
 243
 244 /*
 245  *  ======== bridge_brd_read ========
 246  *  Purpose:
 247  *      Read a block of DSP memory, from a given memory space, into a host
 248  *      buffer.
 249  *  Parameters:
 250  *      dev_ctxt:    Handle to Bridge driver defined device info.
 251  *      host_buf:       Pointer to host buffer (Destination).
 252  *      dsp_addr:       Address on DSP board (Source).
 253  *      ul_num_bytes:     Number of bytes to transfer.
 254  *      mem_type:       Memory space on DSP from which to transfer.
 255  *  Returns:
 256  *      0:        Success.
 257  *      -ETIMEDOUT:  Timeout occured waiting for a response from hardware.
 258  *      -EPERM:      Other, unspecified error.
 259  *  Requires:
 260  *      dev_ctxt != NULL;
 261  *      host_buf != NULL.
 262  *  Ensures:
 263  *  Will not write more than ul_num_bytes bytes into host_buf.
 264  */
 265 typedef int(*fxn_brd_read) (struct bridge_dev_context *dev_ctxt,
 266                                    u8 *host_buf,
 267                                    u32 dsp_addr,
 268                                    u32 ul_num_bytes, u32 mem_type);
 269
 270 /*
 271  *  ======== bridge_brd_write ========
 272  *  Purpose:
 273  *      Write a block of host memory into a DSP address, into a given memory
 274  *      space.
 275  *  Parameters:
 276  *      dev_ctxt:    Handle to Bridge driver defined device info.
 277  *      dsp_addr:       Address on DSP board (Destination).
 278  *      host_buf:       Pointer to host buffer (Source).
 279  *      ul_num_bytes:     Number of bytes to transfer.
 280  *      mem_type:       Memory space on DSP to which to transfer.
 281  *  Returns:
 282  *      0:        Success.
 283  *      -ETIMEDOUT:  Timeout occured waiting for a response from hardware.
 284  *      -EPERM:      Other, unspecified error.
 285  *  Requires:
 286  *      dev_ctxt != NULL;
 287  *      host_buf != NULL.
 288  *  Ensures:
 289  */
 290 typedef int(*fxn_brd_write) (struct bridge_dev_context *dev_ctxt,
 291                                     u8 *host_buf,
 292                                     u32 dsp_addr,
 293                                     u32 ul_num_bytes, u32 mem_type);
 294
 295 /*
 296  *  ======== bridge_chnl_create ========
 297  *  Purpose:
 298  *      Create a channel manager object, responsible for opening new channels
 299  *      and closing old ones for a given 'Bridge board.
 300  *  Parameters:
 301  *      channel_mgr:    Location to store a channel manager object on output.
 302  *      hdev_obj:     Handle to a device object.
 303  *      mgr_attrts:      Channel manager attributes.
 304  *      mgr_attrts->max_channels: Max channels
 305  *      mgr_attrts->birq:      Channel's I/O IRQ number.
 306  *      mgr_attrts->irq_shared:   TRUE if the IRQ is shareable.
 307  *      mgr_attrts->word_size: DSP Word size in equivalent PC bytes..
 308  *      mgr_attrts->shm_base:  Base physical address of shared memory, if any.
 309  *      mgr_attrts->usm_length: Bytes of shared memory block.
 310  *  Returns:
 311  *      0:            Success;
 312  *      -ENOMEM:        Insufficient memory for requested resources.
 313  *      -EIO:         Unable to plug ISR for given IRQ.
 314  *      -EFAULT:    Couldn't map physical address to a virtual one.
 315  *  Requires:
 316  *      channel_mgr != NULL.
 317  *      mgr_attrts != NULL
 318  *      mgr_attrts field are all valid:
 319  *          0 < max_channels <= CHNL_MAXCHANNELS.
 320  *          birq <= 15.
 321  *          word_size > 0.
 322  *      hdev_obj != NULL
 323  *      No channel manager exists for this board.
 324  *  Ensures:
 325  */
 326 typedef int(*fxn_chnl_create) (struct chnl_mgr
 327                                       **channel_mgr,
 328                                       struct dev_object
 329                                       * hdev_obj,
 330                                       const struct
 331                                       chnl_mgrattrs * mgr_attrts);
 332
 333 /*
 334  *  ======== bridge_chnl_destroy ========
 335  *  Purpose:
 336  *      Close all open channels, and destroy the channel manager.
 337  *  Parameters:
 338  *      hchnl_mgr:       Channel manager object.
 339  *  Returns:
 340  *      0:        Success.
 341  *      -EFAULT:    hchnl_mgr was invalid.
 342  *  Requires:
 343  *  Ensures:
 344  *      0: Cancels I/O on each open channel. Closes each open channel.
 345  *          chnl_create may subsequently be called for the same device.
 346  */
 347 typedef int(*fxn_chnl_destroy) (struct chnl_mgr *hchnl_mgr);
 348 /*
 349  *  ======== bridge_deh_notify ========
 350  *  Purpose:
 351  *      When notified of DSP error, take appropriate action.
 352  *  Parameters:
 353  *      hdeh_mgr:        Handle to DEH manager object.
 354  *      evnt_mask:    Indicate the type of exception
 355  *      error_info:    Error information
 356  *  Returns:
 357  *
 358  *  Requires:
 359  *      hdeh_mgr != NULL;
 360  *     evnt_mask with a valid exception
 361  *  Ensures:
 362  */
 363 typedef void (*fxn_deh_notify) (struct deh_mgr *hdeh_mgr,
 364                                 u32 evnt_mask, u32 error_info);
 365
 366 /*
 367  *  ======== bridge_chnl_open ========
 368  *  Purpose:
 369  *      Open a new half-duplex channel to the DSP board.
 370  *  Parameters:
 371  *      chnl:           Location to store a channel object handle.
 372  *      hchnl_mgr:      Handle to channel manager, as returned by
 373  *                      CHNL_GetMgr().
 374  *      chnl_mode:          One of {CHNL_MODETODSP, CHNL_MODEFROMDSP} specifies
 375  *                      direction of data transfer.
 376  *      ch_id:        If CHNL_PICKFREE is specified, the channel manager will
 377  *                      select a free channel id (default);
 378  *                      otherwise this field specifies the id of the channel.
 379  *      pattrs:         Channel attributes.  Attribute fields are as follows:
 380  *      pattrs->uio_reqs: Specifies the maximum number of I/O requests which can
 381  *                      be pending at any given time. All request packets are
 382  *                      preallocated when the channel is opened.
 383  *      pattrs->event_obj: This field allows the user to supply an auto reset
 384  *                      event object for channel I/O completion notifications.
 385  *                      It is the responsibility of the user to destroy this
 386  *                      object AFTER closing the channel.
 387  *                      This channel event object can be retrieved using
 388  *                      CHNL_GetEventHandle().
 389  *      pattrs->hReserved: The kernel mode handle of this event object.
 390  *
 391  *  Returns:
 392  *      0:                Success.
 393  *      -EFAULT:            hchnl_mgr is invalid.
 394  *      -ENOMEM:            Insufficient memory for requested resources.
 395  *      -EINVAL:        Invalid number of IOReqs.
 396  *      -ENOSR:    No free channels available.
 397  *      -ECHRNG:       Channel ID is out of range.
 398  *      -EALREADY:        Channel is in use.
 399  *      -EIO:         No free IO request packets available for
 400  *                              queuing.
 401  *  Requires:
 402  *      chnl != NULL.
 403  *      pattrs != NULL.
 404  *      pattrs->event_obj is a valid event handle.
 405  *      pattrs->hReserved is the kernel mode handle for pattrs->event_obj.
 406  *  Ensures:
 407  *      0:                *chnl is a valid channel.
 408  *      else:                   *chnl is set to NULL if (chnl != NULL);
 409  */
 410 typedef int(*fxn_chnl_open) (struct chnl_object
 411                                     **chnl,
 412                                     struct chnl_mgr *hchnl_mgr,
 413                                     s8 chnl_mode,
 414                                     u32 ch_id,
 415                                     const struct
 416                                     chnl_attr * pattrs);
 417
 418 /*
 419  *  ======== bridge_chnl_close ========
 420  *  Purpose:
 421  *      Ensures all pending I/O on this channel is cancelled, discards all
 422  *      queued I/O completion notifications, then frees the resources allocated
 423  *      for this channel, and makes the corresponding logical channel id
 424  *      available for subsequent use.
 425  *  Parameters:
 426  *      chnl_obj:          Handle to a channel object.
 427  *  Returns:
 428  *      0:        Success;
 429  *      -EFAULT:    Invalid chnl_obj.
 430  *  Requires:
 431  *      No thread must be blocked on this channel's I/O completion event.
 432  *  Ensures:
 433  *      0:        chnl_obj is no longer valid.
 434  */
 435 typedef int(*fxn_chnl_close) (struct chnl_object *chnl_obj);
 436
 437 /*
 438  *  ======== bridge_chnl_add_io_req ========
 439  *  Purpose:
 440  *      Enqueue an I/O request for data transfer on a channel to the DSP.
 441  *      The direction (mode) is specified in the channel object. Note the DSP
 442  *      address is specified for channels opened in direct I/O mode.
 443  *  Parameters:
 444  *      chnl_obj:          Channel object handle.
 445  *      host_buf:       Host buffer address source.
 446  *      byte_size:      Number of PC bytes to transfer. A zero value indicates
 447  *                      that this buffer is the last in the output channel.
 448  *                      A zero value is invalid for an input channel.
 449  *!     buf_size:       Actual buffer size in host bytes.
 450  *      dw_dsp_addr:      DSP address for transfer.  (Currently ignored).
 451  *      dw_arg:          A user argument that travels with the buffer.
 452  *  Returns:
 453  *      0:        Success;
 454  *      -EFAULT: Invalid chnl_obj or host_buf.
 455  *      -EPERM:   User cannot mark EOS on an input channel.
 456  *      -ECANCELED: I/O has been cancelled on this channel.  No further
 457  *                      I/O is allowed.
 458  *      -EPIPE:     End of stream was already marked on a previous
 459  *                      IORequest on this channel.  No further I/O is expected.
 460  *      -EINVAL: Buffer submitted to this output channel is larger than
 461  *                      the size of the physical shared memory output window.
 462  *  Requires:
 463  *  Ensures:
 464  *      0: The buffer will be transferred if the channel is ready;
 465  *          otherwise, will be queued for transfer when the channel becomes
 466  *          ready.  In any case, notifications of I/O completion are
 467  *          asynchronous.
 468  *          If byte_size is 0 for an output channel, subsequent CHNL_AddIOReq's
 469  *          on this channel will fail with error code -EPIPE.  The
 470  *          corresponding IOC for this I/O request will have its status flag
 471  *          set to CHNL_IOCSTATEOS.
 472  */
 473 typedef int(*fxn_chnl_addioreq) (struct chnl_object
 474                                         * chnl_obj,
 475                                         void *host_buf,
 476                                         u32 byte_size,
 477                                         u32 buf_size,
 478                                         u32 dw_dsp_addr, u32 dw_arg);
 479
 480 /*
 481  *  ======== bridge_chnl_get_ioc ========
 482  *  Purpose:
 483  *      Dequeue an I/O completion record, which contains information about the
 484  *      completed I/O request.
 485  *  Parameters:
 486  *      chnl_obj:          Channel object handle.
 487  *      timeout:        A value of CHNL_IOCNOWAIT will simply dequeue the
 488  *                      first available IOC.
 489  *      chan_ioc:       On output, contains host buffer address, bytes
 490  *                      transferred, and status of I/O completion.
 491  *      chan_ioc->status:   See chnldefs.h.
 492  *  Returns:
 493  *      0:        Success.
 494  *      -EFAULT: Invalid chnl_obj or chan_ioc.
 495  *      -EREMOTEIO:   CHNL_IOCNOWAIT was specified as the timeout parameter
 496  *                      yet no I/O completions were queued.
 497  *  Requires:
 498  *      timeout == CHNL_IOCNOWAIT.
 499  *  Ensures:
 500  *      0: if there are any remaining IOC's queued before this call
 501  *          returns, the channel event object will be left in a signalled
 502  *          state.
 503  */
 504 typedef int(*fxn_chnl_getioc) (struct chnl_object *chnl_obj,
 505                                       u32 timeout,
 506                                       struct chnl_ioc *chan_ioc);
 507
 508 /*
 509  *  ======== bridge_chnl_cancel_io ========
 510  *  Purpose:
 511  *      Return all I/O requests to the client which have not yet been
 512  *      transferred.  The channel's I/O completion object is
 513  *      signalled, and all the I/O requests are queued as IOC's, with the
 514  *      status field set to CHNL_IOCSTATCANCEL.
 515  *      This call is typically used in abort situations, and is a prelude to
 516  *      chnl_close();
 517  *  Parameters:
 518  *      chnl_obj:          Channel object handle.
 519  *  Returns:
 520  *      0:        Success;
 521  *      -EFAULT:    Invalid chnl_obj.
 522  *  Requires:
 523  *  Ensures:
 524  *      Subsequent I/O requests to this channel will not be accepted.
 525  */
 526 typedef int(*fxn_chnl_cancelio) (struct chnl_object *chnl_obj);
 527
 528 /*
 529  *  ======== bridge_chnl_flush_io ========
 530  *  Purpose:
 531  *      For an output stream (to the DSP), indicates if any IO requests are in
 532  *      the output request queue.  For input streams (from the DSP), will
 533  *      cancel all pending IO requests.
 534  *  Parameters:
 535  *      chnl_obj:              Channel object handle.
 536  *      timeout:            Timeout value for flush operation.
 537  *  Returns:
 538  *      0:            Success;
 539  *      S_CHNLIOREQUEST:    Returned if any IORequests are in the output queue.
 540  *      -EFAULT:        Invalid chnl_obj.
 541  *  Requires:
 542  *  Ensures:
 543  *      0:            No I/O requests will be pending on this channel.
 544  */
 545 typedef int(*fxn_chnl_flushio) (struct chnl_object *chnl_obj,
 546                                        u32 timeout);
 547
 548 /*
 549  *  ======== bridge_chnl_get_info ========
 550  *  Purpose:
 551  *      Retrieve information related to a channel.
 552  *  Parameters:
 553  *      chnl_obj:          Handle to a valid channel object, or NULL.
 554  *      channel_info:   Location to store channel info.
 555  *  Returns:
 556  *      0:        Success;
 557  *      -EFAULT: Invalid chnl_obj or channel_info.
 558  *  Requires:
 559  *  Ensures:
 560  *      0:        channel_info points to a filled in chnl_info struct,
 561  *                      if (channel_info != NULL).
 562  */
 563 typedef int(*fxn_chnl_getinfo) (struct chnl_object *chnl_obj,
 564                                        struct chnl_info *channel_info);
 565
 566 /*
 567  *  ======== bridge_chnl_get_mgr_info ========
 568  *  Purpose:
 569  *      Retrieve information related to the channel manager.
 570  *  Parameters:
 571  *      hchnl_mgr:           Handle to a valid channel manager, or NULL.
 572  *      ch_id:            Channel ID.
 573  *      mgr_info:           Location to store channel manager info.
 574  *  Returns:
 575  *      0:            Success;
 576  *      -EFAULT: Invalid hchnl_mgr or mgr_info.
 577  *      -ECHRNG:   Invalid channel ID.
 578  *  Requires:
 579  *  Ensures:
 580  *      0:            mgr_info points to a filled in chnl_mgrinfo
 581  *                          struct, if (mgr_info != NULL).
 582  */
 583 typedef int(*fxn_chnl_getmgrinfo) (struct chnl_mgr
 584                                           * hchnl_mgr,
 585                                           u32 ch_id,
 586                                           struct chnl_mgrinfo *mgr_info);
 587
 588 /*
 589  *  ======== bridge_chnl_idle ========
 590  *  Purpose:
 591  *      Idle a channel. If this is an input channel, or if this is an output
 592  *      channel and flush_data is TRUE, all currently enqueued buffers will be
 593  *      dequeued (data discarded for output channel).
 594  *      If this is an output channel and flush_data is FALSE, this function
 595  *      will block until all currently buffered data is output, or the timeout
 596  *      specified has been reached.
 597  *
 598  *  Parameters:
 599  *      chnl_obj:          Channel object handle.
 600  *      timeout:        If output channel and flush_data is FALSE, timeout value
 601  *                      to wait for buffers to be output. (Not used for
 602  *                      input channel).
 603  *      flush_data:     If output channel and flush_data is TRUE, discard any
 604  *                      currently buffered data. If FALSE, wait for currently
 605  *                      buffered data to be output, or timeout, whichever
 606  *                      occurs first. flush_data is ignored for input channel.
 607  *  Returns:
 608  *      0:            Success;
 609  *      -EFAULT:        Invalid chnl_obj.
 610  *      -ETIMEDOUT: Timeout occured before channel could be idled.
 611  *  Requires:
 612  *  Ensures:
 613  */
 614 typedef int(*fxn_chnl_idle) (struct chnl_object *chnl_obj,
 615                                     u32 timeout, bool flush_data);
 616
 617 /*
 618  *  ======== bridge_chnl_register_notify ========
 619  *  Purpose:
 620  *      Register for notification of events on a channel.
 621  *  Parameters:
 622  *      chnl_obj:          Channel object handle.
 623  *      event_mask:     Type of events to be notified about: IO completion
 624  *                      (DSP_STREAMIOCOMPLETION) or end of stream
 625  *                      (DSP_STREAMDONE).
 626  *      notify_type:    DSP_SIGNALEVENT.
 627  *      hnotification:  Handle of a dsp_notification object.
 628  *  Returns:
 629  *      0:        Success.
 630  *      -ENOMEM:    Insufficient memory.
 631  *      -EINVAL:     event_mask is 0 and hnotification was not
 632  *                      previously registered.
 633  *      -EFAULT:    NULL hnotification, hnotification event name
 634  *                      too long, or hnotification event name NULL.
 635  *  Requires:
 636  *      Valid chnl_obj.
 637  *      hnotification != NULL.
 638  *      (event_mask & ~(DSP_STREAMIOCOMPLETION | DSP_STREAMDONE)) == 0.
 639  *      notify_type == DSP_SIGNALEVENT.
 640  *  Ensures:
 641  */
 642 typedef int(*fxn_chnl_registernotify)
 643  (struct chnl_object *chnl_obj,
 644   u32 event_mask, u32 notify_type, struct dsp_notification *hnotification);
 645
 646 /*
 647  *  ======== bridge_dev_create ========
 648  *  Purpose:
 649  *      Complete creation of the device object for this board.
 650  *  Parameters:
 651  *      device_ctx:     Ptr to location to store a Bridge device context.
 652  *      hdev_obj:     Handle to a Device Object, created and managed by DSP API.
 653  *      config_param:        Ptr to configuration parameters provided by the
 654  *                      Configuration Manager during device loading.
 655  *      pDspConfig:     DSP resources, as specified in the registry key for this
 656  *                      device.
 657  *  Returns:
 658  *      0:            Success.
 659  *      -ENOMEM:        Unable to allocate memory for device context.
 660  *  Requires:
 661  *      device_ctx != NULL;
 662  *      hdev_obj != NULL;
 663  *      config_param != NULL;
 664  *      pDspConfig != NULL;
 665  *      Fields in config_param and pDspConfig contain valid values.
 666  *  Ensures:
 667  *      0:        All Bridge driver specific DSP resource and other
 668  *                      board context has been allocated.
 669  *      -ENOMEM:    Bridge failed to allocate resources.
 670  *                      Any acquired resources have been freed.  The DSP API
 671  *                      will not call bridge_dev_destroy() if
 672  *                      bridge_dev_create() fails.
 673  *  Details:
 674  *      Called during the CONFIGMG's Device_Init phase. Based on host and
 675  *      DSP configuration information, create a board context, a handle to
 676  *      which is passed into other Bridge BRD and CHNL functions.  The
 677  *      board context contains state information for the device. Since the
 678  *      addresses of all pointer parameters may be invalid when this
 679  *      function returns, they must not be stored into the device context
 680  *      structure.
 681  */
 682 typedef int(*fxn_dev_create) (struct bridge_dev_context
 683                                      **device_ctx,
 684                                      struct dev_object
 685                                      * hdev_obj,
 686                                      struct cfg_hostres
 687                                      * config_param);
 688
 689 /*
 690  *  ======== bridge_dev_ctrl ========
 691  *  Purpose:
 692  *      Bridge driver specific interface.
 693  *  Parameters:
 694  *      dev_ctxt:    Handle to Bridge driver defined device info.
 695  *      dw_cmd:          Bridge driver defined command code.
 696  *      pargs:          Pointer to an arbitrary argument structure.
 697  *  Returns:
 698  *      0 or -EPERM. Actual command error codes should be passed back in
 699  *      the pargs structure, and are defined by the Bridge driver implementor.
 700  *  Requires:
 701  *      All calls are currently assumed to be synchronous.  There are no
 702  *      IOCTL completion routines provided.
 703  *  Ensures:
 704  */
 705 typedef int(*fxn_dev_ctrl) (struct bridge_dev_context *dev_ctxt,
 706                                    u32 dw_cmd, void *pargs);
 707
 708 /*
 709  *  ======== bridge_dev_destroy ========
 710  *  Purpose:
 711  *      Deallocate Bridge device extension structures and all other resources
 712  *      acquired by the Bridge driver.
 713  *      No calls to other Bridge driver functions may subsequently
 714  *      occur, except for bridge_dev_create().
 715  *  Parameters:
 716  *      dev_ctxt:    Handle to Bridge driver defined device information.
 717  *  Returns:
 718  *      0:        Success.
 719  *      -EPERM:      Failed to release a resource previously acquired.
 720  *  Requires:
 721  *      dev_ctxt != NULL;
 722  *  Ensures:
 723  *      0: Device context is freed.
 724  */
 725 typedef int(*fxn_dev_destroy) (struct bridge_dev_context *dev_ctxt);
 726
 727 /*
 728  *  ======== bridge_io_create ========
 729  *  Purpose:
 730  *      Create an object that manages I/O between CHNL and msg_ctrl.
 731  *  Parameters:
 732  *      io_man:         Location to store IO manager on output.
 733  *      hchnl_mgr:       Handle to channel manager.
 734  *      hmsg_mgr:        Handle to message manager.
 735  *  Returns:
 736  *      0:        Success.
 737  *      -ENOMEM:    Memory allocation failure.
 738  *      -EPERM:      Creation failed.
 739  *  Requires:
 740  *      hdev_obj != NULL;
 741  *      Channel manager already created;
 742  *      Message manager already created;
 743  *      mgr_attrts != NULL;
 744  *      io_man != NULL;
 745  *  Ensures:
 746  */
 747 typedef int(*fxn_io_create) (struct io_mgr **io_man,
 748                                     struct dev_object *hdev_obj,
 749                                     const struct io_attrs *mgr_attrts);
 750
 751 /*
 752  *  ======== bridge_io_destroy ========
 753  *  Purpose:
 754  *      Destroy object created in bridge_io_create.
 755  *  Parameters:
 756  *      hio_mgr:         IO Manager.
 757  *  Returns:
 758  *      0:        Success.
 759  *      -ENOMEM:    Memory allocation failure.
 760  *      -EPERM:      Creation failed.
 761  *  Requires:
 762  *      Valid hio_mgr;
 763  *  Ensures:
 764  */
 765 typedef int(*fxn_io_destroy) (struct io_mgr *hio_mgr);
 766
 767 /*
 768  *  ======== bridge_io_on_loaded ========
 769  *  Purpose:
 770  *      Called whenever a program is loaded to update internal data. For
 771  *      example, if shared memory is used, this function would update the
 772  *      shared memory location and address.
 773  *  Parameters:
 774  *      hio_mgr:     IO Manager.
 775  *  Returns:
 776  *      0:    Success.
 777  *      -EPERM:  Internal failure occurred.
 778  *  Requires:
 779  *      Valid hio_mgr;
 780  *  Ensures:
 781  */
 782 typedef int(*fxn_io_onloaded) (struct io_mgr *hio_mgr);
 783
 784 /*
 785  *  ======== fxn_io_getprocload ========
 786  *  Purpose:
 787  *      Called to get the Processor's current and predicted load
 788  *  Parameters:
 789  *      hio_mgr:     IO Manager.
 790  *      proc_load_stat   Processor Load statistics
 791  *  Returns:
 792  *      0:    Success.
 793  *      -EPERM:  Internal failure occurred.
 794  *  Requires:
 795  *      Valid hio_mgr;
 796  *  Ensures:
 797  */
 798 typedef int(*fxn_io_getprocload) (struct io_mgr *hio_mgr,
 799                                          struct dsp_procloadstat *
 800                                          proc_load_stat);
 801
 802 /*
 803  *  ======== bridge_msg_create ========
 804  *  Purpose:
 805  *      Create an object to manage message queues. Only one of these objects
 806  *      can exist per device object.
 807  *  Parameters:
 808  *      msg_man:            Location to store msg_ctrl manager on output.
 809  *      hdev_obj:         Handle to a device object.
 810  *      msg_callback:        Called whenever an RMS_EXIT message is received.
 811  *  Returns:
 812  *      0:            Success.
 813  *      -ENOMEM:        Insufficient memory.
 814  *  Requires:
 815  *      msg_man != NULL.
 816  *      msg_callback != NULL.
 817  *      hdev_obj != NULL.
 818  *  Ensures:
 819  */
 820 typedef int(*fxn_msg_create)
 821  (struct msg_mgr **msg_man,
 822   struct dev_object *hdev_obj, msg_onexit msg_callback);
 823
 824 /*
 825  *  ======== bridge_msg_create_queue ========
 826  *  Purpose:
 827  *      Create a msg_ctrl queue for sending or receiving messages from a Message
 828  *      node on the DSP.
 829  *  Parameters:
 830  *      hmsg_mgr:            msg_ctrl queue manager handle returned from
 831  *                          bridge_msg_create.
 832  *      msgq:               Location to store msg_ctrl queue on output.
 833  *      msgq_id:            Identifier for messages (node environment pointer).
 834  *      max_msgs:           Max number of simultaneous messages for the node.
 835  *      h:                  Handle passed to hmsg_mgr->msg_callback().
 836  *  Returns:
 837  *      0:            Success.
 838  *      -ENOMEM:        Insufficient memory.
 839  *  Requires:
 840  *      msgq != NULL.
 841  *      h != NULL.
 842  *      max_msgs > 0.
 843  *  Ensures:
 844  *      msgq !=NULL <==> 0.
 845  */
 846 typedef int(*fxn_msg_createqueue)
 847  (struct msg_mgr *hmsg_mgr,
 848   struct msg_queue **msgq, u32 msgq_id, u32 max_msgs, void *h);
 849
 850 /*
 851  *  ======== bridge_msg_delete ========
 852  *  Purpose:
 853  *      Delete a msg_ctrl manager allocated in bridge_msg_create().
 854  *  Parameters:
 855  *      hmsg_mgr:    Handle returned from bridge_msg_create().
 856  *  Returns:
 857  *  Requires:
 858  *      Valid hmsg_mgr.
 859  *  Ensures:
 860  */
 861 typedef void (*fxn_msg_delete) (struct msg_mgr *hmsg_mgr);
 862
 863 /*
 864  *  ======== bridge_msg_delete_queue ========
 865  *  Purpose:
 866  *      Delete a msg_ctrl queue allocated in bridge_msg_create_queue.
 867  *  Parameters:
 868  *      msg_queue_obj:  Handle to msg_ctrl queue returned from
 869  *                  bridge_msg_create_queue.
 870  *  Returns:
 871  *  Requires:
 872  *      Valid msg_queue_obj.
 873  *  Ensures:
 874  */
 875 typedef void (*fxn_msg_deletequeue) (struct msg_queue *msg_queue_obj);
 876
 877 /*
 878  *  ======== bridge_msg_get ========
 879  *  Purpose:
 880  *      Get a message from a msg_ctrl queue.
 881  *  Parameters:
 882  *      msg_queue_obj:     Handle to msg_ctrl queue returned from
 883  *                     bridge_msg_create_queue.
 884  *      pmsg:          Location to copy message into.
 885  *      utimeout:      Timeout to wait for a message.
 886  *  Returns:
 887  *      0:       Success.
 888  *      -ETIME:  Timeout occurred.
 889  *      -EPERM:     No frames available for message (max_msgs too
 890  *                     small).
 891  *  Requires:
 892  *      Valid msg_queue_obj.
 893  *      pmsg != NULL.
 894  *  Ensures:
 895  */
 896 typedef int(*fxn_msg_get) (struct msg_queue *msg_queue_obj,
 897                                   struct dsp_msg *pmsg, u32 utimeout);
 898
 899 /*
 900  *  ======== bridge_msg_put ========
 901  *  Purpose:
 902  *      Put a message onto a msg_ctrl queue.
 903  *  Parameters:
 904  *      msg_queue_obj:      Handle to msg_ctrl queue returned from
 905  *                      bridge_msg_create_queue.
 906  *      pmsg:           Pointer to message.
 907  *      utimeout:       Timeout to wait for a message.
 908  *  Returns:
 909  *      0:        Success.
 910  *      -ETIME:   Timeout occurred.
 911  *      -EPERM:      No frames available for message (max_msgs too
 912  *                      small).
 913  *  Requires:
 914  *      Valid msg_queue_obj.
 915  *      pmsg != NULL.
 916  *  Ensures:
 917  */
 918 typedef int(*fxn_msg_put) (struct msg_queue *msg_queue_obj,
 919                                   const struct dsp_msg *pmsg, u32 utimeout);
 920
 921 /*
 922  *  ======== bridge_msg_register_notify ========
 923  *  Purpose:
 924  *      Register notification for when a message is ready.
 925  *  Parameters:
 926  *      msg_queue_obj:      Handle to msg_ctrl queue returned from
 927  *                      bridge_msg_create_queue.
 928  *      event_mask:     Type of events to be notified about: Must be
 929  *                      DSP_NODEMESSAGEREADY, or 0 to unregister.
 930  *      notify_type:    DSP_SIGNALEVENT.
 931  *      hnotification:  Handle of notification object.
 932  *  Returns:
 933  *      0:        Success.
 934  *      -ENOMEM:    Insufficient memory.
 935  *  Requires:
 936  *      Valid msg_queue_obj.
 937  *      hnotification != NULL.
 938  *      notify_type == DSP_SIGNALEVENT.
 939  *      event_mask == DSP_NODEMESSAGEREADY || event_mask == 0.
 940  *  Ensures:
 941  */
 942 typedef int(*fxn_msg_registernotify)
 943  (struct msg_queue *msg_queue_obj,
 944   u32 event_mask, u32 notify_type, struct dsp_notification *hnotification);
 945
 946 /*
 947  *  ======== bridge_msg_set_queue_id ========
 948  *  Purpose:
 949  *      Set message queue id to node environment. Allows bridge_msg_create_queue
 950  *      to be called in node_allocate, before the node environment is known.
 951  *  Parameters:
 952  *      msg_queue_obj:  Handle to msg_ctrl queue returned from
 953  *                  bridge_msg_create_queue.
 954  *      msgq_id:       Node environment pointer.
 955  *  Returns:
 956  *  Requires:
 957  *      Valid msg_queue_obj.
 958  *      msgq_id != 0.
 959  *  Ensures:
 960  */
 961 typedef void (*fxn_msg_setqueueid) (struct msg_queue *msg_queue_obj,
 962                                     u32 msgq_id);
 963
 964 /*
 965  *  Bridge Driver interface function table.
 966  *
 967  *  The information in this table is filled in by the specific Bridge driver,
 968  *  and copied into the DSP API's own space.  If any interface
 969  *  function field is set to a value of NULL, then the DSP API will
 970  *  consider that function not implemented, and return the error code
 971  *  -ENOSYS when a Bridge driver client attempts to call that function.
 972  *
 973  *  This function table contains DSP API version numbers, which are used by the
 974  *  Bridge driver loader to help ensure backwards compatility between older
 975  *  Bridge drivers and newer DSP API.  These must be set to
 976  *  BRD_API_MAJOR_VERSION and BRD_API_MINOR_VERSION, respectively.
 977  *
 978  *  A Bridge driver need not export a CHNL interface.  In this case, *all* of
 979  *  the bridge_chnl_* entries must be set to NULL.
 980  */
 981 struct bridge_drv_interface {
 982         u32 brd_api_major_version;      /* Set to BRD_API_MAJOR_VERSION. */
 983         u32 brd_api_minor_version;      /* Set to BRD_API_MINOR_VERSION. */
 984         fxn_dev_create pfn_dev_create;  /* Create device context */
 985         fxn_dev_destroy pfn_dev_destroy;        /* Destroy device context */
 986         fxn_dev_ctrl pfn_dev_cntrl;     /* Optional vendor interface */
 987         fxn_brd_monitor pfn_brd_monitor;        /* Load and/or start monitor */
 988         fxn_brd_start pfn_brd_start;    /* Start DSP program. */
 989         fxn_brd_stop pfn_brd_stop;      /* Stop/reset board. */
 990         fxn_brd_status pfn_brd_status;  /* Get current board status. */
 991         fxn_brd_read pfn_brd_read;      /* Read board memory */
 992         fxn_brd_write pfn_brd_write;    /* Write board memory. */
 993         fxn_brd_setstate pfn_brd_set_state;     /* Sets the Board State */
 994         fxn_brd_memcopy pfn_brd_mem_copy;       /* Copies DSP Memory */
 995         fxn_brd_memwrite pfn_brd_mem_write;     /* Write DSP Memory w/o halt */
 996         fxn_brd_memmap pfn_brd_mem_map; /* Maps MPU mem to DSP mem */
 997         fxn_brd_memunmap pfn_brd_mem_un_map;    /* Unmaps MPU mem to DSP mem */
 998         fxn_chnl_create pfn_chnl_create;        /* Create channel manager. */
 999         fxn_chnl_destroy pfn_chnl_destroy;      /* Destroy channel manager. */
1000         fxn_chnl_open pfn_chnl_open;    /* Create a new channel. */
1001         fxn_chnl_close pfn_chnl_close;  /* Close a channel. */
1002         fxn_chnl_addioreq pfn_chnl_add_io_req;  /* Req I/O on a channel. */
1003         fxn_chnl_getioc pfn_chnl_get_ioc;       /* Wait for I/O completion. */
1004         fxn_chnl_cancelio pfn_chnl_cancel_io;   /* Cancl I/O on a channel. */
1005         fxn_chnl_flushio pfn_chnl_flush_io;     /* Flush I/O. */
1006         fxn_chnl_getinfo pfn_chnl_get_info;     /* Get channel specific info */
1007         /* Get channel manager info. */
1008         fxn_chnl_getmgrinfo pfn_chnl_get_mgr_info;
1009         fxn_chnl_idle pfn_chnl_idle;    /* Idle the channel */
1010         /* Register for notif. */
1011         fxn_chnl_registernotify pfn_chnl_register_notify;
1012         fxn_io_create pfn_io_create;    /* Create IO manager */
1013         fxn_io_destroy pfn_io_destroy;  /* Destroy IO manager */
1014         fxn_io_onloaded pfn_io_on_loaded;       /* Notify of program loaded */
1015         /* Get Processor's current and predicted load */
1016         fxn_io_getprocload pfn_io_get_proc_load;
1017         fxn_msg_create pfn_msg_create;  /* Create message manager */
1018         /* Create message queue */
1019         fxn_msg_createqueue pfn_msg_create_queue;
1020         fxn_msg_delete pfn_msg_delete;  /* Delete message manager */
1021         /* Delete message queue */
1022         fxn_msg_deletequeue pfn_msg_delete_queue;
1023         fxn_msg_get pfn_msg_get;        /* Get a message */
1024         fxn_msg_put pfn_msg_put;        /* Send a message */
1025         /* Register for notif. */
1026         fxn_msg_registernotify pfn_msg_register_notify;
1027         /* Set message queue id */
1028         fxn_msg_setqueueid pfn_msg_set_queue_id;
1029 };
1030
1031 /*
1032  *  ======== bridge_drv_entry ========
1033  *  Purpose:
1034  *      Registers Bridge driver functions with the DSP API. Called only once
1035  *      by the DSP API.  The caller will first check DSP API version
1036  *      compatibility, and then copy the interface functions into its own
1037  *      memory space.
1038  *  Parameters:
1039  *      drv_intf  Pointer to a location to receive a pointer to the
1040  *                      Bridge driver interface.
1041  *  Returns:
1042  *  Requires:
1043  *      The code segment this function resides in must expect to be discarded
1044  *      after completion.
1045  *  Ensures:
1046  *      drv_intf pointer initialized to Bridge driver's function
1047  *      interface. No system resources are acquired by this function.
1048  *  Details:
1049  *      Called during the Device_Init phase.
1050  */
1051 void bridge_drv_entry(struct bridge_drv_interface **drv_intf,
1052                    const char *driver_file_name);
1053
1054 #endif /* DSPDEFS_ */