Modules/UDI/include/udi_init.h

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