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