Pileus Git - ~andy/linux/blob - 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_close ========
  29  *  Purpose:
  30  *      Ensures all pending I/O on this channel is cancelled, discards all
  31  *      queued I/O completion notifications, then frees the resources allocated
  32  *      for this channel, and makes the corresponding logical channel id
  33  *      available for subsequent use.
  34  *  Parameters:
  35  *      chnl_obj:          Channel object handle.
  36  *  Returns:
  37  *      0:        Success;
  38  *      -EFAULT:    Invalid chnl_obj.
  39  *  Requires:
  40  *      chnl_init(void) called.
  41  *      No thread must be blocked on this channel's I/O completion event.
  42  *  Ensures:
  43  *      0:        The I/O completion event for this channel is freed.
  44  *                      chnl_obj is no longer valid.
  45  */
  46 extern int chnl_close(struct chnl_object *chnl_obj);
  47
  48 /*
  49  *  ======== chnl_create ========
  50  *  Purpose:
  51  *      Create a channel manager object, responsible for opening new channels
  52  *      and closing old ones for a given board.
  53  *  Parameters:
  54  *      channel_mgr:    Location to store a channel manager object on output.
  55  *      hdev_obj:     Handle to a device object.
  56  *      mgr_attrts:      Channel manager attributes.
  57  *      mgr_attrts->max_channels:   Max channels
  58  *      mgr_attrts->birq:        Channel's I/O IRQ number.
  59  *      mgr_attrts->irq_shared:     TRUE if the IRQ is shareable.
  60  *      mgr_attrts->word_size:   DSP Word size in equivalent PC bytes..
  61  *  Returns:
  62  *      0:                Success;
  63  *      -EFAULT:            hdev_obj is invalid.
  64  *      -EINVAL: max_channels is 0.
  65  *               Invalid DSP word size (must be > 0).
  66  *               Invalid base address for DSP communications.
  67  *      -ENOMEM:            Insufficient memory for requested resources.
  68  *      -EIO:             Unable to plug channel ISR for configured IRQ.
  69  *      -ECHRNG:     This manager cannot handle this many channels.
  70  *      -EEXIST:       Channel manager already exists for this device.
  71  *  Requires:
  72  *      chnl_init(void) called.
  73  *      channel_mgr != NULL.
  74  *      mgr_attrts != NULL.
  75  *  Ensures:
  76  *      0:                Subsequent calls to chnl_create() for the same
  77  *                              board without an intervening call to
  78  *                              chnl_destroy() will fail.
  79  */
  80 extern int chnl_create(OUT struct chnl_mgr **channel_mgr,
  81                               struct dev_object *hdev_obj,
  82                               IN CONST struct chnl_mgrattrs *mgr_attrts);
  83
  84 /*
  85  *  ======== chnl_destroy ========
  86  *  Purpose:
  87  *      Close all open channels, and destroy the channel manager.
  88  *  Parameters:
  89  *      hchnl_mgr:           Channel manager object.
  90  *  Returns:
  91  *      0:            Success.
  92  *      -EFAULT:        hchnl_mgr was invalid.
  93  *  Requires:
  94  *      chnl_init(void) called.
  95  *  Ensures:
  96  *      0:            Cancels I/O on each open channel.
  97  *                          Closes each open channel.
  98  *                          chnl_create may subsequently be called for the
  99  *                          same board.
 100  */
 101 extern int chnl_destroy(struct chnl_mgr *hchnl_mgr);
 102
 103 /*
 104  *  ======== chnl_exit ========
 105  *  Purpose:
 106  *      Discontinue usage of the CHNL module.
 107  *  Parameters:
 108  *  Returns:
 109  *  Requires:
 110  *      chnl_init(void) previously called.
 111  *  Ensures:
 112  *      Resources, if any acquired in chnl_init(void), are freed when the last
 113  *      client of CHNL calls chnl_exit(void).
 114  */
 115 extern void chnl_exit(void);
 116
 117 /*
 118  *  ======== chnl_init ========
 119  *  Purpose:
 120  *      Initialize the CHNL module's private state.
 121  *  Parameters:
 122  *  Returns:
 123  *      TRUE if initialized; FALSE if error occurred.
 124  *  Requires:
 125  *  Ensures:
 126  *      A requirement for each of the other public CHNL functions.
 127  */
 128 extern bool chnl_init(void);
 129
 130 #endif /* CHNL_ */