a4d9142be2517f19bf95cd637d278fd273a2e1d4
[tpg/acess2.git] / init.h
1 /**
2  * \file udi_init.h
3  */
4 #ifndef _UDI_INIT_H_
5 #define _UDI_INIT_H_
6
7 /**
8  * \brief UDI Initialisation Structure
9  * 
10  * Defines how to initialise and use a UDI driver
11  */
12 struct udi_init_s
13 {
14         /**
15          * \brief Defines the primary region
16          * \note For secondary modules this must be NULL
17          */
18         udi_primary_init_t      *primary_init_info;
19         
20         /**
21          * \brief Defines all secondary regions
22          * Pointer to a list (so, essentially an array) of ::udi_secondary_init_t
23          * It is terminated by an entry with ::udi_secondary_init_t.region_idx
24          * set to zero.
25          * \note If NULL, it is to be treated as an empty list
26          */
27         udi_secondary_init_t    *secondary_init_list;
28         
29         /**
30          * \brief Channel operations
31          * Pointer to a ::udi_ops_init_t.ops_idx == 0  terminated list that
32          * defines the channel opterations usage for each ops vector implemented
33          * in this module.
34          * \note Must contain at least one entry for each metalanguage used
35          */
36         udi_ops_init_t  *ops_init_list;
37         
38         /**
39          * \brief Control Blocks
40          */
41         udi_cb_init_t   *cb_init_list;
42         
43         /**
44          * \brief Generic Control Blocks
45          */
46         udi_gcb_init_t  *gcb_init_list;
47         
48         /**
49          * \brief Overrides for control blocks
50          * Allows a control block to override the ammount of scratch space it
51          * gets for a specific ops vector.
52          */
53         udi_cb_select_t *cb_select_list;
54 } __attribute__((packed));
55
56
57 /**
58  * \name Flags for ::udi_primary_init_t.mgmt_op_flags
59  * \{
60  */
61
62 /**
63  * \brief Tells the environment that this operation may take some time
64  * Used as a hint in scheduling tasks
65  */
66 #define UDI_OP_LONG_EXEC        0x01
67
68 /**
69  * \}
70  */
71
72 /**
73  * \brief Describes the Primary Region
74  * Tells the environment how to set up the driver's primary region.
75  */
76 struct udi_primary_init_s
77 {
78         /**
79          * \brief Management Ops Vector
80          * Pointer to a list of functions for the Management Metalanguage
81          */
82         udi_mgmt_ops_t  *mgmt_ops;
83         
84         /**
85          * \brief Flags for \a mgmt_ops
86          * Each entry in \a mgmt_ops is acommanied by an entry in this array.
87          * Each entry contains the flags that apply to the specified ops vector.
88          * \see UDI_OP_LONG_EXEC
89          */
90         const udi_ubit8_t       *mgmt_op_flags;
91         
92         /**
93          * \brief Scratch space size
94          * Specifies the number of bytes to allocate for each control block
95          * passed by the environment.
96          * \note must not exceed ::UDI_MAX_SCRATCH
97          */
98         udi_size_t      mgmt_scratch_requirement;
99         
100         /**
101          * \todo What is this?
102          */
103         udi_ubit8_t     enumeration_attr_list_length;
104         
105         /**
106          * \brief Size in bytes to allocate to each instance of the primary
107          *        region
108          * Essentially the size of the driver's instance state
109          * \note Must be at least sizeof(udi_init_context_t) and not more
110          *       than UDI_MIN_ALLOC_LIMIT
111          */
112         udi_size_t      rdata_size;
113         
114         /**
115          * \brief Size in bytes to allocate for each call to ::udi_enumerate_req
116          * \note Must not exceed UDI_MIN_ALLOC_LIMIT
117          */
118         udi_size_t      child_data_size;
119         
120         /**
121          * \brief Number of path handles for each parent bound to this driver
122          * \todo What the hell are path handles?
123          */
124         udi_ubit8_t     per_parent_paths;
125 };
126
127 /**
128  * \brief Tells the environment how to create a secondary region
129  */
130 struct udi_secondary_init_s
131 {
132         /**
133          * \brief Region Index
134          * Non-zero driver-dependent index value that identifies the region
135          * \note This corresponds to a "region" declaration in the udiprops.txt
136          *       file.
137          */
138         udi_index_t     region_idx;
139         /**
140          * \brief Number of bytes to allocate
141          * 
142          * \note Again, must be between sizeof(udi_init_context_t) and
143          *       UDI_MIN_ALLOC_LIMIT
144          */
145         udi_size_t      rdata_size;
146 };
147
148 /**
149  * \brief Defines channel endpoints (ways of communicating with the driver)
150  * 
151  */
152 struct udi_ops_init_s
153 {
154         /**
155          * \brief ops index number
156          * Used to uniquely this entry
157          * \note If this is zero, it marks the end of the list
158          */
159         udi_index_t     ops_idx;
160         /**
161          * \brief Metalanguage Index
162          * Defines what metalanguage is used
163          */
164         udi_index_t     meta_idx;
165         /**
166          * \brief Metalanguage Operation
167          * Defines what metalanguage operation is used
168          */
169         udi_index_t     meta_ops_num;
170         /**
171          * \brief Size of the context area
172          * \note If non-zero, must be at least 
173          */
174         udi_size_t      chan_context_size;
175         /**
176          * \brief Pointer to the operations
177          * Pointer to a <<meta>>_<<role>>_ops_t structure
178          */
179         udi_ops_vector_t        *ops_vector;
180         /**
181          * \brief Flags for each entry in \a ops_vector
182          */
183         const udi_ubit8_t       *op_flags;
184 };
185
186 /**
187  * \brief Defines control blocks
188  * Much the same as ::udi_ops_init_t
189  */
190 struct udi_cb_init_s
191 {
192         udi_index_t     cb_idx;
193         udi_index_t     meta_idx;
194         udi_index_t     meta_cb_num;
195         udi_size_t      scratch_requirement;
196         /**
197          * \brief Size of inline memory
198          */
199         udi_size_t      inline_size;
200         /**
201          * \brief Layout of inline memory
202          */
203         udi_layout_t    *inline_layout;
204 };
205
206 /**
207  * \brief Overrides the scratch size for an operation
208  */
209 struct udi_cb_select_s
210 {
211         udi_index_t     ops_idx;
212         udi_index_t     cb_idx;
213 };
214
215 /**
216  * \brief General Control Blocks
217  * These control blocks can only be used as general data storage, not
218  * for any channel operations.
219  */
220 struct udi_gcb_init_s
221 {
222         udi_index_t     cb_idx;
223         udi_size_t      scratch_requirement;
224 };
225
226
227 // ===
228 // ===
229 /**
230  * \brief Environement Imposed Limits
231  */
232 struct udi_limits_s
233 {
234         /**
235          * \brief Maximum legal ammount of memory that can be allocated
236          */
237         udi_size_t      max_legal_alloc;
238         
239         /**
240          * \brief Maximum ammount of guaranteed memory
241          */
242         udi_size_t      max_safe_alloc;
243         /**
244          * \brief Maximum size of the final string from ::udi_trace_write
245          *        or ::udi_log_write
246          */
247         udi_size_t      max_trace_log_formatted_len;
248         /**
249          * \brief Maximum legal size of an instanct attribute value
250          */
251         udi_size_t      max_instance_attr_len;
252         /**
253          * \brief Minumum time difference (in nanoseconds between unique values
254          *        returned by ::udi_time_current
255          */
256         udi_ubit32_t    min_curtime_res;
257         /**
258          * \brief Minimum resolution of timers
259          * \see ::udi_timer_start_repeating, ::udi_timer_start
260          */
261         udi_ubit32_t    min_timer_res;
262 } __attribute__((packed));
263
264 /**
265  * \brief Primary Region Context data
266  */
267 struct udi_init_context_s
268 {
269         udi_index_t     region_idx;
270         udi_limits_t    limits;
271 };
272
273 /**
274  * \brief Channel context data
275  */
276 struct udi_chan_context_s
277 {
278         /**
279          * \brief Pointer to the driver instance's initial region data
280          */
281         void    *rdata;
282 } __attribute__((packed));
283
284 /**
285  * \brief Child Channel context
286  */
287 struct udi_child_chan_context_s
288 {
289         /**
290          * \brief Pointer to the driver instance's initial region data
291          */
292         void    *rdata;
293         /**
294          * \brief Some sort of unique ID number
295          */
296         udi_ubit32_t    child_ID;
297 };
298
299 #endif

UCC git Repository :: git.ucc.asn.au