/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 */
 59extern 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 */
 80extern 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 */
 94extern 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 */
107extern bool chnl_init(void);
108
109#endif /* CHNL_ */