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.2 $
12 *     $Date: 1998/01/08 11:12:26 $
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 */
31typedef struct Parameter {
32      ADP_Parameter     type;
33      unsigned int      value;
34} Parameter;
35
36/* A list of parameter values, with tag */
37typedef 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 */
44typedef struct ParameterConfig {
45      unsigned int      num_parameters;
46      Parameter        *param;  /* pointer to array of Parameters */
47} ParameterConfig;
48
49/* A set of parameter options */
50typedef 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 */
69const 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 */
84bool 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 */
100bool 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 */
115ParameterList *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 */
128unsigned 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 */
141unsigned 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 */
157bool 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 */
176bool Angel_ReadParamOptionsMessage( const unsigned char *buffer,
177                                    ParameterOptions    *options );
178
179#endif /* ndef angel_params_h */
180
181/* EOF params.h */
182