| blob | 50df0199e063b9302fb559cfec4689d99aba975c |
1 /* $Id: foreign.h,v 1.1 1998/11/09 07:48:57 baccala Exp $
2 *
3 * HiSax ISDN driver - foreign chipset interface
4 *
5 * Author Brent Baccala (baccala@FreeSoft.org)
6 *
7 *
8 *
9 * $Log: foreign.h,v $
10 * Revision 1.1 1998/11/09 07:48:57 baccala
11 * Initial DBRI ISDN code. Sometimes works (brings up the link and you
12 * can telnet through it), sometimes doesn't (crashes the machine)
13 *
14 */
16 /*
17 * ISDN operations
18 *
19 * Many of these routines take an "int dev" argument, which is simply
20 * an index into the drivers[] array. Currently, we only support a
21 * single foreign chip, so the value should always be 0. B channel
22 * operations require an "int chan", which should be 0 for channel B1
23 * and 1 for channel B2
24 *
25 * int get_irqnum(int dev)
26 *
27 * returns the interrupt number being used by the chip. ISDN4linux
28 * uses this number to watch the interrupt during initialization and
29 * make sure something is happening.
30 *
31 * int get_liu_state(int dev)
32 *
33 * returns the current state of the ISDN Line Interface Unit (LIU)
34 * as a number between 2 (state F2) and 7 (state F7). 0 may also be
35 * returned if the chip doesn't exist or the LIU hasn't been
36 * activated. The meanings of the states are defined in I.430, ISDN
37 * BRI Physical Layer Interface. The most important two states are
38 * F3 (shutdown) and F7 (syncronized).
39 *
40 * void liu_init(int dev, void (*callback)(void *), void *callback_arg)
41 *
42 * initializes the LIU and optionally registers a callback to be
43 * signaled upon a change of LIU state. The callback will be called
44 * with a single opaque callback_arg. Once the callback has been
45 * triggered, get_liu_state can be used to determine the LIU
46 * current state.
47 *
48 * void liu_activate(int dev, int priority)
49 *
50 * requests LIU activation at a given D-channel priority.
51 * Successful activatation is achieved upon entering state F7, which
52 * will trigger any callback previously registered with
53 * liu_init.
54 *
55 * void liu_deactivate(int dev)
56 *
57 * deactivates LIU. Outstanding D and B channel transactions are
58 * terminated rudely and without callback notification. LIU change
59 * of state callback will be triggered, however.
60 *
61 * void dxmit(int dev, __u8 *buffer, unsigned int count,
62 * void (*callback)(void *, int), void *callback_arg)
63 *
64 * transmits a packet - specified with buffer, count - over the D-channel
65 * interface. Buffer should begin with the LAPD address field and
66 * end with the information field. FCS and flag sequences should not
67 * be included, nor is bit-stuffing required - all these functions are
68 * performed by the chip. The callback function will be called
69 * DURING THE TOP HALF OF AN INTERRUPT HANDLER and will be passed
70 * both the arbitrary callback_arg and an integer error indication:
71 *
72 * 0 - successful transmission; ready for next packet
73 * non-0 - error value
74 *
75 * The callback routine should defer any time-consuming operations
76 * to a bottom-half handler; however, dxmit may be called
77 * from within the callback to request back-to-back transmission of
78 * a second packet (without repeating the priority/collision mechanism)
79 *
80 * A comment about the "collision detect" error, which is signalled
81 * whenever the echoed D-channel data didn't match the transmitted
82 * data. This is part of ISDN's normal multi-drop T-interface
83 * operation, indicating that another device has attempted simultaneous
84 * transmission, but can also result from line noise. An immediate
85 * requeue via dxmit is suggested, but repeated collision
86 * errors may indicate a more serious problem.
87 *
88 * void drecv(int dev, __u8 *buffer, unsigned int size,
89 * void (*callback)(void *, int, unsigned int),
90 * void *callback_arg)
91 *
92 * register a buffer - buffer, size - into which a D-channel packet
93 * can be received. The callback function will be called DURING
94 * THE TOP HALF OF AN INTERRUPT HANDLER and will be passed an
95 * arbitrary callback_arg, an integer error indication and the length
96 * of the received packet, which will start with the address field,
97 * end with the information field, and not contain flag or FCS
98 * bytes. Bit-stuffing will already have been corrected for.
99 * Possible values of second callback argument "error":
100 *
101 * 0 - successful reception
102 * non-0 - error value
103 *
104 * int bopen(int dev, int chan, int hdlcmode, u_char xmit_idle_char)
105 *
106 * This function should be called before any other operations on a B
107 * channel. mode is either non-0 to (de)encapsulate using HDLC or 0
108 * for transparent operation. In addition to arranging for interrupt
109 * handling and channel multiplexing, it sets the xmit_idle_char
110 * which is transmitted on the interface when no data buffer is
111 * available. Suggested values are: 0 for ISDN audio; FF for HDLC
112 * mark idle; 7E for HDLC flag idle. Returns 0 on a successful
113 * open; -1 on error.
114 *
115 * If the chip doesn't support HDLC encapsulation (the Am7930
116 * doesn't), an error will be returned opening L1_MODE_HDLC; the
117 * HiSax driver should retry with L1_MODE_TRANS, then be prepared to
118 * bit-stuff the data before shipping it to the driver.
119 *
120 * void bclose(int dev, int chan)
121 *
122 * Shuts down a B channel when no longer in use.
123 *
124 * void bxmit(int dev, int chan, __u8 *buffer, unsigned int count,
125 * void (*callback)(void *, int), void *callback_arg)
126 *
127 * transmits a data block - specified with buffer, count - over the
128 * B channel interface specified by dev/chan. In mode L1_MODE_HDLC,
129 * a complete HDLC frames should be relayed with a single bxmit.
130 * The callback function will be called DURING THE TOP HALF OF AN
131 * INTERRUPT HANDLER and will be passed the arbitrary callback_arg
132 * and an integer error indication:
133 *
134 * 0 - successful transmission; ready for next packet
135 * non-0 - error
136 *
137 * The callback routine should defer any time-consuming operations
138 * to a bottom-half handler; however, bxmit may be called
139 * from within the callback to request back-to-back transmission of
140 * another data block
141 *
142 * void brecv(int dev, int chan, __u8 *buffer, unsigned int size,
143 * void (*callback)(void *, int, unsigned int), void *callback_arg)
144 *
145 * receive a raw data block - specified with buffer, size - over the
146 * B channel interface specified by dev/chan. The callback function
147 * will be called DURING THE TOP HALF OF AN INTERRUPT HANDLER and
148 * will be passed the arbitrary callback_arg, an integer error
149 * indication and the length of the received packet. In HDLC mode,
150 * the packet will start with the address field, end with the
151 * information field, and will not contain flag or FCS bytes.
152 * Bit-stuffing will already have been corrected for.
153 *
154 * Possible values of second callback argument "error":
155 *
156 * 0 - successful reception
157 * non-0 - error value
158 *
159 * The callback routine should defer any time-consuming operations
160 * to a bottom-half handler; however, brecv may be called
161 * from within the callback to register another buffer and ensure
162 * continuous B channel reception without loss of data
163 * */
190 };