Main Page | Data Structures | File List | Data Fields | Globals

ticvocab.h

Go to the documentation of this file.
00001 #ifndef _TOKE_TICVOCAB_H
00002 #define _TOKE_TICVOCAB_H
00003 
00004 /*
00005  *                     OpenBIOS - free your system!
00006  *                         ( FCode tokenizer )
00007  *
00008  *  This program is part of a free implementation of the IEEE 1275-1994
00009  *  Standard for Boot (Initialization Configuration) Firmware.
00010  *
00011  *  Copyright (C) 2001-2005 Stefan Reinauer, <stepan@openbios.org>
00012  *
00013  *  This program is free software; you can redistribute it and/or modify
00014  *  it under the terms of the GNU General Public License as published by
00015  *  the Free Software Foundation; version 2 of the License.
00016  *
00017  *  This program is distributed in the hope that it will be useful,
00018  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00019  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00020  *  GNU General Public License for more details.
00021  *
00022  *  You should have received a copy of the GNU General Public License
00023  *  along with this program; if not, write to the Free Software
00024  *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA, 02110-1301 USA
00025  *
00026  */
00027 
00028 /* **************************************************************************
00029  *
00030  *      General-purpose support structures and function prototypes for
00031  *          Threaded Interpretive Code (T. I. C.)-type vocabularies.
00032  *          See ticvocab.c
00033  *
00034  *      (C) Copyright 2005 IBM Corporation.  All Rights Reserved.
00035  *      Module Author:  David L. Paktor    dlpaktor@us.ibm.com
00036  *
00037  **************************************************************************** */
00038 
00039 /* **************************************************************************
00040  *
00041  *      Structures:
00042  *
00043  *      The Threaded Interpretive Code Header data structure consists of:
00044  *          (1)  A pointer to the function name as seen in the source
00045  *          (2)  A link to the next (well, preceding) element
00046  *          (3)  A Pointer to the routine to run as the function's behavior
00047  *               during active processing.  It takes the "parameter field"
00048  *               item as its argument and has no return-value.
00049  *          (4)  The "parameter field" item, which will be passed as an
00050  *               argument to the function. It may be an FCode- or FWord-
00051  *               -token, or an item of another type, or a pointer to data.
00052  *               The function may re-cast it as needed.
00053  *          (5)  The "Definer" of the entry; a member of the subset of FWord-
00054  *               -tokens that may be Definers.
00055  *          (6)  A Pointer to a routine to be run when the word is encountered
00056  *               in a Conditional Compilation section that is being ignored.
00057  *               Certain functions still need to be recognized in that state,
00058  *               and will require special behaviors; those that can be simply
00059  *               ignored will have a NULL pointer in this field.  The function
00060  *               in this field, also, takes the "parameter field" item as its
00061  *               argument and has no return-value.
00062  *          (7)  The size of the data pointed to by the "parameter field" item,
00063  *               if it is a pointer to allocated data; used to allocate space
00064  *               for a copy of the p.f. when making an alias, and to indicate
00065  *               whether the space needs to be freed.  Automatic procedures
00066  *               are too often fooled, so we don't leave things to chance...
00067  *      To accommodate C's insistence on strong-typing, we might need
00068  *          to define different "parameter field" structure-types; see
00069  *          description of "Parameter Field as a union", below.
00070  *
00071  *      It's not an exact name, but we'll still call it a T. I. C. Header
00072  *
00073  *      We will use this structure for most of our vocabularies...
00074  *
00075  ****************************************************************************
00076  *
00077  *     The "Parameter Field" is a union of several alternative types,
00078  *         for convenience, to avert excessive type-casting.  It may
00079  *         either be the Parameter Data itself (if it is small enough)
00080  *         or a pointer to Parameter Data.
00081  *     In the case where the Parameter Field is the data itself, or is a
00082  *         pointer to hard-coded (non-allocated) data, the "size" field
00083  *         will be zero, to indicate that no space allocation is required.
00084  *     The types are (starting with the default for initialization)
00085  *         A long integer (including an FCode Token)
00086  *         An FWord Token
00087  *         A pointer to a boolean variable
00088  *         A pointer to a character or a character string
00089  *         If the parameter field value is intended to be a single character,
00090  *             it must be recast as a long integer, in order to preserve
00091  *             portability across big- and little- -endian platforms.
00092  *
00093  **************************************************************************** */
00094 
00095 /* ************************************************************************** *
00096  *
00097  *      Macros:
00098  *          NO_PARAM_TIC       Create an entry in the initial "Built-In"
00099  *                                 portion of a TIC-type vocabulary with
00100  *                                 an empty "param field".
00101  *          NO_PARAM_IGN       Create an entry with an empty "param field"
00102  *                                 whose action- and "Ignore"- -functions
00103  *                                 are the same.
00104  *          VALPARAM_TIC       " ... with a literal value for the "param field"
00105  *          DUALFUNC_TIC       " ... with a literal "param" and both an action-
00106  *                                 and an "Ignore"- -function.
00107  *          DUFNC_FWT_PARM      A  tic_fwt_hdr_t -type entry with a literal
00108  *                                 "param" and both an action-function and an
00109  *                                 "Ignore"-function.
00110  *          FWORD_TKN_TIC      " ... with an FWord Token for the "param field"
00111  *          DUALFUNC_FWT_TIC   " " ... and both action- and "Ignore"- -function
00112  *          BUILTIN_MAC_TIC    A  tic_mac_hdr_t -type entry with a Macro-
00113  *                                 -Substitution-String "param"
00114  *          BUILTIN_BOOL_TIC   A  tic_bool_hdr_t -type entry with a boolean-
00115  *                                 -variable-pointer "param"
00116  *
00117  **************************************************************************** */
00118 
00119 #include "types.h"
00120 #include "dictionary.h"
00121 
00122 /* **************************************************************************
00123  *
00124  *      In order to work around C's limitations regarding data-typing
00125  *          during initialization, we need to create some alternative
00126  *          data-structures that exactly match the layout of  tic_hdr_t
00127  *          as defined above, but have a different default-type for
00128  *          the parameter field.
00129  *      I apologize in advance for any maintenance awkwardnesses this
00130  *          might engender; I would have come up with a more convenient
00131  *          way to do this if I could.  At least, the pieces that need
00132  *          to be co-ordinated are in close proximity to each other...
00133  *
00134  **************************************************************************** */
00135 
00136 /* **************************************************************************
00137  *
00138  *      The differences are all centered in the "parameter field" of
00139  *          the TIC header structure.  In order to make sure all the
00140  *          alternative types map smoothly into each other, we will
00141  *          create a series of "union" types, differing only in what
00142  *          their default type is.  We will keep the "parameter field"
00143  *          item the size of a Long Integer.
00144  *
00145  **************************************************************************** */
00146 
00147 /* **************************************************************************
00148  *
00149  *      This form is the default type.
00150  *
00151  **************************************************************************** */
00152 
00153 #define TIC_P_DEFLT_TYPE  long
00154 typedef union tic_param
00155     {
00156         TIC_P_DEFLT_TYPE  deflt_elem ;  /*  The "default element" aspect.  */
00157         long              long_val ;    /*  Explicitly specifying "long"   */
00158         fwtoken           fw_token ;    /*  FWord Token                    */
00159         bool             *bool_ptr ;    /*  Pointer to a boolean variable  */
00160         char             *chr_ptr  ;    /*  Pointer to a character string  */
00161 
00162         /*  The "character value" aspect behaves differently on big-
00163          *      versus little- -endian platforms (for initialization,
00164          *      anyway), so we cannot actually use it.
00165          *  Keep this commented-out, as a reminder.
00166          */
00167      /* char             char_val ;    */
00168         /*  We will recast "character value" as an integer.  */
00169 
00170     } tic_param_t ;
00171 
00172 typedef struct tic_hdr
00173     {
00174         char             *name;
00175         struct tic_hdr   *next;
00176         void            (*funct)();      /*  Function for active processing  */
00177         tic_param_t       pfield;
00178         fwtoken           fword_defr;    /*  FWord Token of entry's Definer  */
00179         void            (*ign_func)();   /*  Function in "Ignored" segment   */
00180         int               pfld_size;
00181     }  tic_hdr_t ;
00182 
00183 /* **************************************************************************
00184  *
00185  *      This form is for initialization of an FWord Token list.
00186  *
00187  **************************************************************************** */
00188 
00189 #define TIC_FWT_P_DEFLT_TYPE  fwtoken
00190 typedef union tic_fwt_param
00191     {
00192         TIC_FWT_P_DEFLT_TYPE  deflt_elem ;  /*  "Default element" aspect.  */
00193         long              long_val ;    /*  Long integer                   */
00194         fwtoken           fw_token ;    /*  Explicit FWord Token           */
00195         bool             *bool_ptr ;    /*  Pointer to a boolean variable  */
00196         char             *chr_ptr  ;    /*  Pointer to a character string  */
00197     } tic_fwt_param_t ;
00198 
00199 typedef struct tic_fwt_hdr
00200     {
00201         char               *name;
00202         struct tic_fwt_hdr *next;
00203         void              (*funct)();    /*  Function for active processing  */
00204         tic_fwt_param_t     pfield;
00205         fwtoken             fword_defr;  /*  FWord Token of entry's Definer  */
00206         void              (*ign_func)(); /*  Function in "Ignored" segment   */
00207         int                 pfld_size;
00208     }  tic_fwt_hdr_t ;
00209 
00210 
00211 /* **************************************************************************
00212  *
00213  *      The third form is for initialization of Built-in Macros.  Its
00214  *          default parameter field type is a pointer to a compiled-in
00215  *          (i.e., constant) character string.  Its  pfld_size  can be
00216  *          left as zero, because no allocated-memory copies of the
00217  *          string will be needed, even for aliases.  (User-created
00218  *          macros, however, will need to allocate strings; we will
00219  *          deal with that elsewhere...)
00220  *
00221  **************************************************************************** */
00222 
00223 #define TIC_MAC_P_DEFLT_TYPE  char *
00224 typedef union tic_mac_param
00225     {
00226         TIC_MAC_P_DEFLT_TYPE  deflt_elem ;  /*  "Default element" aspect.  */
00227         long              long_val ;    /*  Long integer                   */
00228         fwtoken           fw_token ;    /*  FWord Token                    */
00229         bool             *bool_ptr ;    /*  Pointer to a boolean variable  */
00230         char            *chr_ptr ;      /*  Explicit Pointer to char str.  */
00231     } tic_mac_param_t ;
00232 
00233 typedef struct tic_mac_hdr
00234     {
00235         char               *name;
00236         struct tic_mac_hdr *next;
00237         void              (*funct)();
00238         tic_mac_param_t     pfield;
00239         fwtoken             fword_defr;
00240         void              (*ign_func)();
00241         int                 pfld_size;
00242     }  tic_mac_hdr_t ;
00243 
00244 /* **************************************************************************
00245  *
00246  *      The next form is for initialization of Condtionals.  Its default
00247  *          parameter field type is a pointer to a boolean variable.
00248  *
00249  **************************************************************************** */
00250 
00251 #define TIC_BOOL_P_DEFLT_TYPE  bool *
00252 typedef union tic_bool_param
00253     {
00254         TIC_BOOL_P_DEFLT_TYPE deflt_elem ;  /*  "Default element" aspect.  */
00255         long              long_val ;    /*  Long integer                   */
00256         fwtoken           fw_token ;    /*  FWord Token                    */
00257         bool             *bool_ptr ;    /*  Explicit Ptr to boolean v'ble  */
00258         char             *chr_ptr  ;    /*  Pointer to a character string  */
00259     } tic_bool_param_t ;
00260 
00261 typedef struct tic_bool_hdr
00262     {
00263         char                *name;
00264         struct tic_bool_hdr *next;
00265         void               (*funct)();
00266         tic_bool_param_t     pfield;
00267         fwtoken              fword_defr;
00268         void               (*ign_func)();
00269         int                  pfld_size;
00270     }  tic_bool_hdr_t ;
00271 
00272 
00273 
00274 /* **************************************************************************
00275  *
00276  *      Various macros to create an entry in the initial "Built-In" portion
00277  *           of a vocabulary-list, specified as an array of one of the
00278  *           matching forms of a T. I. C. Header; each macro adjusts type
00279  *           casting as needed.
00280  *      In all cases, the "size" field will be set to zero, indicating that
00281  *         the "param field" item is either the complete data or a pointer
00282  *         to a hard-coded (non-allocated) data item.
00283  *
00284  **************************************************************************** */
00285 
00286 /* **************************************************************************
00287  *          Macro Name:   NO_PARAM_TIC
00288  *                        Create an entry in the initial "Built-In" portion
00289  *                            of a TIC_HDR -type vocabulary with an empty
00290  *                            "param field"
00291  *                            
00292  *   Arguments:
00293  *       nam      (string)         Name of the entry as seen in the source
00294  *       func     (routine-name)   Name of internal function to call
00295  *
00296  **************************************************************************** */
00297 #define NO_PARAM_TIC(nam, func )  \
00298   { nam , (tic_hdr_t *)NULL , func , { 0 }, UNSPECIFIED , NULL , 0 }
00299 
00300 
00301 /* **************************************************************************
00302  *          Macro Name:   NO_PARAM_IGN
00303  *                        Create an entry with an empty "param field"
00304  *                            whose action-function and "Ignore"-function
00305  *                            are the same.
00306  *                            
00307  *   Arguments:
00308  *       nam      (string)         Name of the entry as seen in the source
00309  *       func     (routine-name)   Name of internal function to call for both
00310  *
00311  *
00312  **************************************************************************** */
00313 #define NO_PARAM_IGN(nam, func )  \
00314   { nam , (tic_hdr_t *)NULL , func , { 0 }, UNSPECIFIED , func , 0 }
00315 
00316 
00317 /* **************************************************************************
00318  *
00319  *      Variations on the above, to compensate for Type-Casting complications
00320  *
00321  **************************************************************************** */
00322 
00323 /* **************************************************************************
00324  *          Macro Name:   VALPARAM_TIC
00325  *                        Create an entry in the initial "Built-In" portion
00326  *                            of a TIC_HDR -type vocabulary with a literal
00327  *                            value for the "param field" and a specifiable
00328  *                            "definer".
00329  *   Arguments:
00330  *       nam      (string)         Name of the entry as seen in the source
00331  *       func     (routine-name)   Name of internal function to call
00332  *       pval     (integer)        The "param field" item
00333  *       definr   (fword_token)    "Definer" of the entry
00334  *
00335  *      The "param field" item will be recast to the required default type.
00336  *
00337  **************************************************************************** */
00338 
00339 #define VALPARAM_TIC(nam, func, pval, definr )  \
00340     { nam , (tic_hdr_t *)NULL , func ,  \
00341         { (TIC_P_DEFLT_TYPE)(pval) }, definr , NULL , 0 }
00342 
00343 
00344 /* **************************************************************************
00345  *          Macro Name:   DUALFUNC_TIC
00346  *                        Create an entry in the initial "Built-In" portion
00347  *                            of a TIC_HDR -type vocabulary with both an
00348  *                            "active" and an "ignoring" function, a literal
00349  *                            value for the "param field" and a specifiable
00350  *                            "definer".
00351  *                            
00352  *   Arguments:
00353  *       nam      (string)         Name of the entry as seen in the source
00354  *       afunc    (routine-name)   Name of internal "active" function
00355  *       pval     (integer)        The "param field" item
00356  *       ifunc    (routine-name)   Name of "ignoring" function
00357  *       definr   (fword_token)    "Definer" of the entry
00358  *
00359  *      The "param field" item will be recast to the required default type.
00360  *
00361  **************************************************************************** */
00362 #define DUALFUNC_TIC(nam, afunc, pval, ifunc, definr )  \
00363     { nam , (tic_hdr_t *)NULL , afunc ,  \
00364         { (TIC_P_DEFLT_TYPE)(pval) }, definr , ifunc , 0 }
00365 
00366 /*  Similar but a  tic_fwt_hdr_t  type structure  */
00367 #define DUFNC_FWT_PARM(nam, afunc, pval, ifunc, definr )  \
00368     { nam , (tic_fwt_hdr_t *)NULL , afunc ,  \
00369         { (TIC_FWT_P_DEFLT_TYPE)(pval) }, definr , ifunc , 0 }
00370 
00371 
00372 /* **************************************************************************
00373  *          Macro Name:   FWORD_TKN_TIC
00374  *                        Create an entry in the initial "Built-In" portion
00375  *                            of an FWord Token list of  tic_fwt_hdr_t  type.
00376  *                            
00377  *   Arguments:
00378  *       nam         (string)         Name of the entry as seen in the source
00379  *       func        (routine-name)   Name of internal function to call
00380  *       fw_tokval   (fword_token)    Value of the FWord Token
00381  *       definr      (fword_token)    "Definer" of the entry
00382  *
00383  *      The "param field" item should not need be recast.
00384  *
00385  **************************************************************************** */
00386 
00387 #define FWORD_TKN_TIC(nam, func, fw_tokval, definr )    \
00388     { nam , (tic_fwt_hdr_t *)NULL , func , { fw_tokval }, definr , NULL , 0 }
00389 
00390 /* **************************************************************************
00391  *          Macro Name:   DUALFUNC_FWT_TIC
00392  *                        Create an entry in the initial "Built-In" portion
00393  *                            of an FWord Token list of  tic_fwt_hdr_t  type
00394  *                            with both an action- and an "Ignore"- -function.
00395  *                            
00396  *   Arguments:
00397  *       nam         (string)         Name of the entry as seen in the source
00398  *       afunc       (routine-name)   Name of internal "Action" function
00399  *       fw_tokval   (fword_token)    Value of the FWord Token
00400  *       ifunc       (routine-name)   Name of "ignoring" function
00401  *       definr      (fword_token)    "Definer" of the entry
00402  *
00403  *      The "param field" item should not need be recast.
00404  *
00405  **************************************************************************** */
00406 #define DUALFUNC_FWT_TIC(nam, afunc, fw_tokval, ifunc, definr )    \
00407     { nam , (tic_fwt_hdr_t *)NULL , afunc , { fw_tokval }, definr , ifunc , 0 }
00408 
00409 /* **************************************************************************
00410  *          Macro Name:   BUILTIN_MAC_TIC
00411  *                        Create an entry in the initial "Built-In" portion
00412  *                            of a Macros vocabulary of  tic_mac_hdr_t  type.
00413  *                            
00414  *   Arguments:
00415  *       nam         (string)         Name of the entry as seen in the source
00416  *       func        (routine-name)   Name of internal function to call
00417  *       alias       (string)         Macro-Substitution string
00418  *
00419  *      The "param field" item should not need be recast.
00420  *      The "definer" will be MACRO_DEF
00421  *      Builtin Macros do not need to be expanded while Ignoring, so
00422  *          the ign_func will be NULL
00423  *
00424  **************************************************************************** */
00425 
00426 #define BUILTIN_MAC_TIC(nam, func, alias )    \
00427     { nam , (tic_mac_hdr_t *)NULL , func , { alias }, MACRO_DEF , NULL , 0 }
00428 
00429 
00430 /* **************************************************************************
00431  *          Macro Name:   BUILTIN_BOOL_TIC
00432  *                        Create an entry in the initial "Built-In" portion
00433  *                            of a Condtionals list of  tic_bool_hdr_t  type.
00434  *                            
00435  *   Arguments:
00436  *       nam         (string)          Name of the entry as seen in the source
00437  *       func        (routine-name)    Name of internal function to call
00438  *       bool_vbl    (boolean v'ble)   Name of the boolean variable.
00439  *
00440  *      The "param field" item should not need be recast.
00441  *      For all of the Condtionals, the "Ignoring" function is the same
00442  *          as the "Active" function.
00443  *      The "definer" will be COMMON_FWORD
00444  *
00445  **************************************************************************** */
00446 
00447 #define BUILTIN_BOOL_TIC(nam, func, bool_vbl )    \
00448     { nam , (tic_bool_hdr_t *)NULL , func , { &bool_vbl },   \
00449         COMMON_FWORD , func , 0 }
00450 
00451 
00452 /* **************************************************************************
00453  *
00454  *     Exported Variables and Function Prototypes the rest of the way...
00455  *
00456  **************************************************************************** */
00457 
00458 extern tic_hdr_t *tic_found;
00459 
00460 void init_tic_vocab( tic_hdr_t *tic_vocab_tbl,
00461                          int max_indx,
00462                              tic_hdr_t **tic_vocab_ptr);
00463 void add_tic_entry( char *tname,
00464                         void (*tfunct)(),
00465                              TIC_P_DEFLT_TYPE tparam,
00466                                  fwtoken fw_defr,
00467                                      int pfldsiz,
00468                                          void (*ign_fnc)(),
00469                                              tic_hdr_t **tic_vocab );
00470 tic_hdr_t *lookup_tic_entry( char *tname, tic_hdr_t *tic_vocab );
00471 bool exists_in_tic_vocab( char *tname, tic_hdr_t *tic_vocab );
00472 bool handle_tic_vocab( char *tname, tic_hdr_t *tic_vocab );
00473 bool create_tic_alias( char *new_name,
00474                                   char *old_name,
00475                                       tic_hdr_t **tic_vocab );
00476 void reset_tic_vocab( tic_hdr_t **tic_vocab, tic_hdr_t *reset_position );
00477 
00478 #endif   /*  _TOKE_TICVOCAB_H    */

Generated on Fri Aug 18 14:03:39 2006 for Toke1.0 by  doxygen 1.4.4