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

   1 /*
   2  * chnl.h
   3  *
   4  * DSP-BIOS Bridge driver support functions for TI OMAP processors.
   5  *
   6  * DSP API channel interface: multiplexes data streams through the single
   7  * physical link managed by a Bridge driver.
   8  *
   9  * See DSP API chnl.h for more details.
  10  *
  11  * Copyright (C) 2005-2006 Texas Instruments, Inc.
  12  *
  13  * This package is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License version 2 as
  15  * published by the Free Software Foundation.
  16  *
  17  * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
  18  * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  19  * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  20  */
  21
  22 #ifndef CHNL_
  23 #define CHNL_
  24
  25 #include <dspbridge/chnlpriv.h>
  26
  27 /*
  28  *  ======== chnl_create ========
  29  *  Purpose:
  30  *      Create a channel manager object, responsible for opening new channels
  31  *      and closing old ones for a given board.
  32  *  Parameters:
  33  *      channel_mgr:    Location to store a channel manager object on output.
  34  *      hdev_obj:     Handle to a device object.
  35  *      mgr_attrts:      Channel manager attributes.
  36  *      mgr_attrts->max_channels:   Max channels
  37  *      mgr_attrts->birq:        Channel's I/O IRQ number.
  38  *      mgr_attrts->irq_shared:     TRUE if the IRQ is shareable.
  39  *      mgr_attrts->word_size:   DSP Word size in equivalent PC bytes..
  40  *  Returns:
  41  *      0:                Success;
  42  *      -EFAULT:            hdev_obj is invalid.
  43  *      -EINVAL: max_channels is 0.
  44  *               Invalid DSP word size (must be > 0).
  45  *               Invalid base address for DSP communications.
  46  *      -ENOMEM:            Insufficient memory for requested resources.
  47  *      -EIO:             Unable to plug channel ISR for configured IRQ.
  48  *      -ECHRNG:     This manager cannot handle this many channels.
  49  *      -EEXIST:       Channel manager already exists for this device.
  50  *  Requires:
  51  *      chnl_init(void) called.
  52  *      channel_mgr != NULL.
  53  *      mgr_attrts != NULL.
  54  *  Ensures:
  55  *      0:                Subsequent calls to chnl_create() for the same
  56  *                              board without an intervening call to
  57  *                              chnl_destroy() will fail.
  58  */
  59 extern int chnl_create(struct chnl_mgr **channel_mgr,
  60                               struct dev_object *hdev_obj,
  61                               const struct chnl_mgrattrs *mgr_attrts);
  62
  63 /*
  64  *  ======== chnl_destroy ========
  65  *  Purpose:
  66  *      Close all open channels, and destroy the channel manager.
  67  *  Parameters:
  68  *      hchnl_mgr:           Channel manager object.
  69  *  Returns:
  70  *      0:            Success.
  71  *      -EFAULT:        hchnl_mgr was invalid.
  72  *  Requires:
  73  *      chnl_init(void) called.
  74  *  Ensures:
  75  *      0:            Cancels I/O on each open channel.
  76  *                          Closes each open channel.
  77  *                          chnl_create may subsequently be called for the
  78  *                          same board.
  79  */
  80 extern int chnl_destroy(struct chnl_mgr *hchnl_mgr);
  81
  82 /*
  83  *  ======== chnl_exit ========
  84  *  Purpose:
  85  *      Discontinue usage of the CHNL module.
  86  *  Parameters:
  87  *  Returns:
  88  *  Requires:
  89  *      chnl_init(void) previously called.
  90  *  Ensures:
  91  *      Resources, if any acquired in chnl_init(void), are freed when the last
  92  *      client of CHNL calls chnl_exit(void).
  93  */
  94 extern void chnl_exit(void);
  95
  96 /*
  97  *  ======== chnl_init ========
  98  *  Purpose:
  99  *      Initialize the CHNL module's private state.
 100  *  Parameters:
 101  *  Returns:
 102  *      TRUE if initialized; FALSE if error occurred.
 103  *  Requires:
 104  *  Ensures:
 105  *      A requirement for each of the other public CHNL functions.
 106  */
 107 extern bool chnl_init(void);
 108
 109 #endif /* CHNL_ */