1 /*
2  * io.h
3  *
4  * DSP-BIOS Bridge driver support functions for TI OMAP processors.
5  *
6  * The io module manages IO between CHNL and msg_ctrl.
7  *
8  * Copyright (C) 2005-2006 Texas Instruments, Inc.
9  *
10  * This package is free software; you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License version 2 as
12  * published by the Free Software Foundation.
13  *
14  * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
15  * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
16  * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
17  */
18 
19 #ifndef IO_
20 #define IO_
21 
22 #include <dspbridge/cfgdefs.h>
23 #include <dspbridge/devdefs.h>
24 
25 /* IO Objects: */
26 struct io_mgr;
27 
28 /* IO manager attributes: */
29 struct io_attrs {
30 	u8 birq;		/* Channel's I/O IRQ number. */
31 	bool irq_shared;	/* TRUE if the IRQ is shareable. */
32 	u32 word_size;		/* DSP Word size. */
33 	u32 shm_base;		/* Physical base address of shared memory. */
34 	u32 sm_length;		/* Size (in bytes) of shared memory. */
35 };
36 
37 
38 /*
39  *  ======== io_create ========
40  *  Purpose:
41  *      Create an IO manager object, responsible for managing IO between
42  *      CHNL and msg_ctrl.
43  *  Parameters:
44  *      channel_mgr:            Location to store a channel manager object on
45  *                              output.
46  *      hdev_obj:             Handle to a device object.
47  *      mgr_attrts:              IO manager attributes.
48  *      mgr_attrts->birq:        I/O IRQ number.
49  *      mgr_attrts->irq_shared:     TRUE if the IRQ is shareable.
50  *      mgr_attrts->word_size:   DSP Word size in equivalent PC bytes..
51  *  Returns:
52  *      0:                Success;
53  *      -ENOMEM:            Insufficient memory for requested resources.
54  *      -EIO:             Unable to plug channel ISR for configured IRQ.
55  *      -EINVAL: Invalid DSP word size (must be > 0).
56  *               Invalid base address for DSP communications.
57  *  Requires:
58  *      io_init(void) called.
59  *      io_man != NULL.
60  *      mgr_attrts != NULL.
61  *  Ensures:
62  */
63 extern int io_create(struct io_mgr **io_man,
64 			    struct dev_object *hdev_obj,
65 			    const struct io_attrs *mgr_attrts);
66 
67 /*
68  *  ======== io_destroy ========
69  *  Purpose:
70  *      Destroy the IO manager.
71  *  Parameters:
72  *      hio_mgr:         IOmanager object.
73  *  Returns:
74  *      0:        Success.
75  *      -EFAULT:    hio_mgr was invalid.
76  *  Requires:
77  *      io_init(void) called.
78  *  Ensures:
79  */
80 extern int io_destroy(struct io_mgr *hio_mgr);
81 
82 /*
83  *  ======== io_exit ========
84  *  Purpose:
85  *      Discontinue usage of the IO module.
86  *  Parameters:
87  *  Returns:
88  *  Requires:
89  *      io_init(void) previously called.
90  *  Ensures:
91  *      Resources, if any acquired in io_init(void), are freed when the last
92  *      client of IO calls io_exit(void).
93  */
94 extern void io_exit(void);
95 
96 /*
97  *  ======== io_init ========
98  *  Purpose:
99  *      Initialize the IO 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 io_init(void);
108 
109 #endif /* CHNL_ */
110