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_ */
110