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  *      channel_mgr != NULL.
52  *      mgr_attrts != NULL.
53  *  Ensures:
54  *      0:                Subsequent calls to chnl_create() for the same
55  *                              board without an intervening call to
56  *                              chnl_destroy() will fail.
57  */
58 extern int chnl_create(struct chnl_mgr **channel_mgr,
59 			      struct dev_object *hdev_obj,
60 			      const struct chnl_mgrattrs *mgr_attrts);
61 
62 /*
63  *  ======== chnl_destroy ========
64  *  Purpose:
65  *      Close all open channels, and destroy the channel manager.
66  *  Parameters:
67  *      hchnl_mgr:           Channel manager object.
68  *  Returns:
69  *      0:            Success.
70  *      -EFAULT:        hchnl_mgr was invalid.
71  *  Requires:
72  *  Ensures:
73  *      0:            Cancels I/O on each open channel.
74  *                          Closes each open channel.
75  *                          chnl_create may subsequently be called for the
76  *                          same board.
77  */
78 extern int chnl_destroy(struct chnl_mgr *hchnl_mgr);
79 
80 #endif /* CHNL_ */
81