UDI/include/udi/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