1 /* 2 * Copyright (C) 1995 Advanced RISC Machines Limited. All rights reserved. 3 * 4 * This software may be freely used, copied, modified, and distributed 5 * provided that the above copyright notice is preserved in all copies of the 6 * software. 7 */ 8 9 /* -*-C-*- 10 * 11 * $Revision: 1.3 $ 12 * $Date: 2004/12/27 14:00:54 $ 13 * 14 * 15 * Project: ANGEL 16 * 17 * Title: Parameter negotiation structures and utilities 18 */ 19 20 #ifndef angel_params_h 21 #define angel_params_h 22 23 #include "angel.h" 24 #include "adp.h" 25 26 #ifndef TARGET 27 # include "host.h" 28 #endif 29 30 /* A single parameter, with tag */ 31 typedef struct Parameter { 32 ADP_Parameter type; 33 unsigned int value; 34 } Parameter; 35 36 /* A list of parameter values, with tag */ 37 typedef struct ParameterList { 38 ADP_Parameter type; 39 unsigned int num_options; 40 unsigned int *option; /* points to array of values */ 41 } ParameterList; 42 43 /* A configuration of one or more parameters */ 44 typedef struct ParameterConfig { 45 unsigned int num_parameters; 46 Parameter *param; /* pointer to array of Parameters */ 47 } ParameterConfig; 48 49 /* A set of parameter options */ 50 typedef struct ParameterOptions { 51 unsigned int num_param_lists; 52 ParameterList *param_list; /* pointer to array of ParamLists */ 53 } ParameterOptions; 54 55 /* 56 * Function: Angel_MatchParams 57 * Purpose: find a configuration from the requested options which is 58 * the best match from the supported options. 59 * 60 * Params: 61 * Input: requested The offered set of parameters. 62 * supported The supported set of parameters. 63 * 64 * Returns: ptr to config A match has been made, ptr to result 65 * will remain valid until next call to 66 * this function. 67 * NULL Match not possible 68 */ 69 const ParameterConfig *Angel_MatchParams( const ParameterOptions *requested, 70 const ParameterOptions *supported ); 71 72 /* 73 * Function: Angel_FindParam 74 * Purpose: find the value of a given parameter from a config. 75 * 76 * Params: 77 * Input: type parameter type to find 78 * config config to search 79 * Output: value parameter value if found 80 * 81 * Returns: TRUE parameter found 82 * FALSE parameter not found 83 */ 84 bool Angel_FindParam( ADP_Parameter type, 85 const ParameterConfig *config, 86 unsigned int *value ); 87 88 /* 89 * Function: Angel_StoreParam 90 * Purpose: store the value of a given parameter in a config. 91 * 92 * Params: 93 * In/Out: config config to store in 94 * Input: type parameter type to store 95 * value parameter value if found 96 * 97 * Returns: TRUE parameter found and new value stored 98 * FALSE parameter not found 99 */ 100 bool Angel_StoreParam( ParameterConfig *config, 101 ADP_Parameter type, 102 unsigned int value ); 103 104 /* 105 * Function: Angel_FindParamList 106 * Purpose: find the parameter list of a given parameter from an options. 107 * 108 * Params: 109 * Input: type parameter type to find 110 * options options block to search 111 * 112 * Returns: pointer to list 113 * NULL parameter not found 114 */ 115 ParameterList *Angel_FindParamList( const ParameterOptions *options, 116 ADP_Parameter type ); 117 118 /* 119 * Function: Angel_BuildParamConfigMessage 120 * Purpose: write a parameter config to a buffer in ADP format. 121 * 122 * Params: 123 * Input: buffer where to write to 124 * config the parameter config to write 125 * 126 * Returns: number of characters written to buffer 127 */ 128 unsigned int Angel_BuildParamConfigMessage( unsigned char *buffer, 129 const ParameterConfig *config ); 130 131 /* 132 * Function: Angel_BuildParamOptionsMessage 133 * Purpose: write a parameter Options to a buffer in ADP format. 134 * 135 * Params: 136 * Input: buffer where to write to 137 * options the options block to write 138 * 139 * Returns: number of characters written to buffer 140 */ 141 unsigned int Angel_BuildParamOptionsMessage( unsigned char *buffer, 142 const ParameterOptions *options ); 143 144 /* 145 * Function: Angel_ReadParamConfigMessage 146 * Purpose: read a parameter config from a buffer where it is in ADP format. 147 * 148 * Params: 149 * Input: buffer where to read from 150 * In/Out: config the parameter config to read to, which must 151 * be set up on entry with a valid array, and 152 * the size of the array in num_parameters. 153 * 154 * Returns: TRUE okay 155 * FALSE not enough space in config 156 */ 157 bool Angel_ReadParamConfigMessage( const unsigned char *buffer, 158 ParameterConfig *config ); 159 160 /* 161 * Function: Angel_ReadParamOptionsMessage 162 * Purpose: read a parameter options from a buffer 163 * where it is in ADP format. 164 * 165 * Params: 166 * Input: buffer where to read from 167 * In/Out: options the parameter options block to read to, 168 * which must be set up on entry with a valid 169 * array, and the size of the array in 170 * num_parameters. Each param_list must 171 * also be set up in the same way. 172 * 173 * Returns: TRUE okay 174 * FALSE not enough space in options 175 */ 176 bool Angel_ReadParamOptionsMessage( const unsigned char *buffer, 177 ParameterOptions *options ); 178 179 #endif /* ndef angel_params_h */ 180 181 /* EOF params.h */ 182