Tools/Source/TianoTools/Common/EfiUtilityMsgs.c

   1 /*++
   2
   3 Copyright (c) 2004, Intel Corporation
   4 All rights reserved. This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12 Module Name:
  13
  14   EfiUtilityMsgs.c
  15
  16 Abstract:
  17
  18   EFI tools utility functions to display warning, error, and informational
  19   messages.
  20
  21 --*/
  22
  23 #include <stdio.h>
  24 #include <string.h>
  25 #include <ctype.h>
  26 #include <stdarg.h>
  27
  28 /*
  29 #include "Tiano.h"
  30 */
  31 #include "EfiUtilityMsgs.h"
  32
  33 #define MAX_LINE_LEN  200
  34
  35 //
  36 // Declare module globals for keeping track of the the utility's
  37 // name and other settings.
  38 //
  39 static STATUS mStatus                 = STATUS_SUCCESS;
  40 static CHAR8  mUtilityName[50]        = { 0 };
  41 static UINT32 mDebugMsgMask           = 0;
  42 static CHAR8  *mSourceFileName        = NULL;
  43 static UINT32 mSourceFileLineNum      = 0;
  44 static UINT32 mErrorCount             = 0;
  45 static UINT32 mWarningCount           = 0;
  46 static UINT32 mMaxErrors              = 0;
  47 static UINT32 mMaxWarnings            = 0;
  48 static UINT32 mMaxWarningsPlusErrors  = 0;
  49 static INT8   mPrintLimitsSet         = 0;
  50
  51 static
  52 void
  53 PrintMessage (
  54   CHAR8   *Type,
  55   CHAR8   *FileName,
  56   UINT32  LineNumber,
  57   UINT32  MessageCode,
  58   CHAR8   *Text,
  59   CHAR8   *MsgFmt,
  60   va_list List
  61   );
  62
  63 static
  64 void
  65 PrintLimitExceeded (
  66   VOID
  67   );
  68
  69 void
  70 Error (
  71   CHAR8   *FileName,
  72   UINT32  LineNumber,
  73   UINT32  MessageCode,
  74   CHAR8   *Text,
  75   CHAR8   *MsgFmt,
  76   ...
  77   )
  78 /*++
  79
  80 Routine Description:
  81   Prints an error message.
  82
  83 Arguments:
  84   All arguments are optional, though the printed message may be useless if
  85   at least something valid is not specified.
  86
  87   FileName - name of the file or application. If not specified, then the
  88              utilty name (as set by the utility calling SetUtilityName()
  89              earlier) is used. Otherwise "Unknown utility" is used.
  90
  91   LineNumber - the line number of error, typically used by parsers. If the
  92                utility is not a parser, then 0 should be specified. Otherwise
  93                the FileName and LineNumber info can be used to cause
  94                MS Visual Studio to jump to the error.
  95
  96   MessageCode - an application-specific error code that can be referenced in
  97               other documentation.
  98
  99   Text        - the text in question, typically used by parsers.
 100
 101   MsgFmt - the format string for the error message. Can contain formatting
 102            controls for use with the varargs.
 103
 104 Returns:
 105   None.
 106
 107 Notes:
 108   We print the following (similar to the Warn() and Debug()
 109   W
 110   Typical error/warning message format:
 111
 112   bin\VfrCompile.cpp(330) : error C2660: 'AddVfrDataStructField' : function does not take 2 parameters
 113
 114   BUGBUG -- these three utility functions are almost identical, and
 115   should be modified to share code.
 116
 117   Visual Studio does not find error messages with:
 118
 119      " error :"
 120      " error 1:"
 121      " error c1:"
 122      " error 1000:"
 123      " error c100:"
 124
 125   It does find:
 126      " error c1000:"
 127 --*/
 128 {
 129   va_list List;
 130   //
 131   // If limits have been set, then check that we have not exceeded them
 132   //
 133   if (mPrintLimitsSet) {
 134     //
 135     // See if we've exceeded our total count
 136     //
 137     if (mMaxWarningsPlusErrors != 0) {
 138       if (mErrorCount + mWarningCount > mMaxWarningsPlusErrors) {
 139         PrintLimitExceeded ();
 140         return ;
 141       }
 142     }
 143     //
 144     // See if we've exceeded our error count
 145     //
 146     if (mMaxErrors != 0) {
 147       if (mErrorCount > mMaxErrors) {
 148         PrintLimitExceeded ();
 149         return ;
 150       }
 151     }
 152   }
 153
 154   mErrorCount++;
 155   va_start (List, MsgFmt);
 156   PrintMessage ("error", FileName, LineNumber, MessageCode, Text, MsgFmt, List);
 157   va_end (List);
 158   //
 159   // Set status accordingly
 160   //
 161   if (mStatus < STATUS_ERROR) {
 162     mStatus = STATUS_ERROR;
 163   }
 164 }
 165
 166 void
 167 ParserError (
 168   UINT32  MessageCode,
 169   CHAR8   *Text,
 170   CHAR8   *MsgFmt,
 171   ...
 172   )
 173 /*++
 174
 175 Routine Description:
 176   Print a parser error, using the source file name and line number
 177   set by a previous call to SetParserPosition().
 178
 179 Arguments:
 180   MessageCode   - application-specific error code
 181   Text          - text to print in the error message
 182   MsgFmt        - format string to print at the end of the error message
 183
 184 Returns:
 185   NA
 186
 187 --*/
 188 {
 189   va_list List;
 190   //
 191   // If limits have been set, then check them
 192   //
 193   if (mPrintLimitsSet) {
 194     //
 195     // See if we've exceeded our total count
 196     //
 197     if (mMaxWarningsPlusErrors != 0) {
 198       if (mErrorCount + mWarningCount > mMaxWarningsPlusErrors) {
 199         PrintLimitExceeded ();
 200         return ;
 201       }
 202     }
 203     //
 204     // See if we've exceeded our error count
 205     //
 206     if (mMaxErrors != 0) {
 207       if (mErrorCount > mMaxErrors) {
 208         PrintLimitExceeded ();
 209         return ;
 210       }
 211     }
 212   }
 213
 214   mErrorCount++;
 215   va_start (List, MsgFmt);
 216   PrintMessage ("error", mSourceFileName, mSourceFileLineNum, MessageCode, Text, MsgFmt, List);
 217   va_end (List);
 218   //
 219   // Set status accordingly
 220   //
 221   if (mStatus < STATUS_ERROR) {
 222     mStatus = STATUS_ERROR;
 223   }
 224 }
 225
 226 void
 227 ParserWarning (
 228   UINT32  ErrorCode,
 229   CHAR8   *OffendingText,
 230   CHAR8   *MsgFmt,
 231   ...
 232   )
 233 /*++
 234
 235 Routine Description:
 236   Print a parser warning, using the source file name and line number
 237   set by a previous call to SetParserPosition().
 238
 239 Arguments:
 240   ErrorCode     - application-specific error code
 241   OffendingText - text to print in the warning message
 242   MsgFmt        - format string to print at the end of the warning message
 243
 244 Returns:
 245   NA
 246
 247 --*/
 248 {
 249   va_list List;
 250   //
 251   // If limits have been set, then check them
 252   //
 253   if (mPrintLimitsSet) {
 254     //
 255     // See if we've exceeded our total count
 256     //
 257     if (mMaxWarningsPlusErrors != 0) {
 258       if (mErrorCount + mWarningCount > mMaxWarningsPlusErrors) {
 259         PrintLimitExceeded ();
 260         return ;
 261       }
 262     }
 263     //
 264     // See if we've exceeded our warning count
 265     //
 266     if (mMaxWarnings != 0) {
 267       if (mWarningCount > mMaxWarnings) {
 268         PrintLimitExceeded ();
 269         return ;
 270       }
 271     }
 272   }
 273
 274   mWarningCount++;
 275   va_start (List, MsgFmt);
 276   PrintMessage ("warning", mSourceFileName, mSourceFileLineNum, ErrorCode, OffendingText, MsgFmt, List);
 277   va_end (List);
 278   //
 279   // Set status accordingly
 280   //
 281   if (mStatus < STATUS_WARNING) {
 282     mStatus = STATUS_WARNING;
 283   }
 284 }
 285
 286 void
 287 Warning (
 288   CHAR8   *FileName,
 289   UINT32  LineNumber,
 290   UINT32  MessageCode,
 291   CHAR8   *Text,
 292   CHAR8   *MsgFmt,
 293   ...
 294   )
 295 /*++
 296
 297 Routine Description:
 298   Print a warning message.
 299
 300 Arguments:
 301   FileName    - name of the file where the warning was detected, or the name
 302                 of the application that detected the warning
 303
 304   LineNumber  - the line number where the warning was detected (parsers).
 305                 0 should be specified if the utility is not a parser.
 306
 307   MessageCode - an application-specific warning code that can be referenced in
 308                 other documentation.
 309
 310   Text        - the text in question (parsers)
 311
 312   MsgFmt      - the format string for the warning message. Can contain formatting
 313                 controls for use with varargs.
 314
 315 Returns:
 316   None.
 317
 318 --*/
 319 {
 320   va_list List;
 321   //
 322   // If limits have been set, then check them
 323   //
 324   if (mPrintLimitsSet) {
 325     //
 326     // See if we've exceeded our total count
 327     //
 328     if (mMaxWarningsPlusErrors != 0) {
 329       if (mErrorCount + mWarningCount > mMaxWarningsPlusErrors) {
 330         PrintLimitExceeded ();
 331         return ;
 332       }
 333     }
 334     //
 335     // See if we've exceeded our warning count
 336     //
 337     if (mMaxWarnings != 0) {
 338       if (mWarningCount > mMaxWarnings) {
 339         PrintLimitExceeded ();
 340         return ;
 341       }
 342     }
 343   }
 344
 345   mWarningCount++;
 346   va_start (List, MsgFmt);
 347   PrintMessage ("warning", FileName, LineNumber, MessageCode, Text, MsgFmt, List);
 348   va_end (List);
 349   //
 350   // Set status accordingly
 351   //
 352   if (mStatus < STATUS_WARNING) {
 353     mStatus = STATUS_WARNING;
 354   }
 355 }
 356
 357 void
 358 DebugMsg (
 359   CHAR8   *FileName,
 360   UINT32  LineNumber,
 361   UINT32  MsgMask,
 362   CHAR8   *Text,
 363   CHAR8   *MsgFmt,
 364   ...
 365   )
 366 /*++
 367
 368 Routine Description:
 369   Print a warning message.
 370
 371 Arguments:
 372   FileName    - typically the name of the utility printing the debug message, but
 373                 can be the name of a file being parsed.
 374
 375   LineNumber  - the line number in FileName (parsers)
 376
 377   MsgMask     - an application-specific bitmask that, in combination with mDebugMsgMask,
 378                 determines if the debug message gets printed.
 379
 380   Text        - the text in question (parsers)
 381
 382   MsgFmt      - the format string for the debug message. Can contain formatting
 383                 controls for use with varargs.
 384
 385 Returns:
 386   None.
 387
 388 --*/
 389 {
 390   va_list List;
 391   //
 392   // If the debug mask is not applicable, then do nothing.
 393   //
 394   if ((MsgMask != 0) && ((mDebugMsgMask & MsgMask) == 0)) {
 395     return ;
 396   }
 397
 398   va_start (List, MsgFmt);
 399   PrintMessage ("debug", FileName, LineNumber, 0, Text, MsgFmt, List);
 400   va_end (List);
 401 }
 402
 403 static
 404 void
 405 PrintMessage (
 406   CHAR8   *Type,
 407   CHAR8   *FileName,
 408   UINT32  LineNumber,
 409   UINT32  MessageCode,
 410   CHAR8   *Text,
 411   CHAR8   *MsgFmt,
 412   va_list List
 413   )
 414 /*++
 415
 416 Routine Description:
 417   Worker routine for all the utility printing services. Prints the message in
 418   a format that Visual Studio will find when scanning build outputs for
 419   errors or warnings.
 420
 421 Arguments:
 422   Type        - "warning" or "error" string to insert into the message to be
 423                 printed. The first character of this string (converted to uppercase)
 424                 is used to preceed the MessageCode value in the output string.
 425
 426   FileName    - name of the file where the warning was detected, or the name
 427                 of the application that detected the warning
 428
 429   LineNumber  - the line number where the warning was detected (parsers).
 430                 0 should be specified if the utility is not a parser.
 431
 432   MessageCode - an application-specific warning code that can be referenced in
 433                 other documentation.
 434
 435   Text        - part of the message to print
 436
 437   MsgFmt      - the format string for the message. Can contain formatting
 438                 controls for use with varargs.
 439   List        - the variable list.
 440
 441 Returns:
 442   None.
 443
 444 Notes:
 445   If FileName == NULL then this utility will use the string passed into SetUtilityName().
 446
 447   LineNumber is only used if the caller is a parser, in which case FileName refers to the
 448   file being parsed.
 449
 450   Text and MsgFmt are both optional, though it would be of little use calling this function with
 451   them both NULL.
 452
 453   Output will typically be of the form:
 454     <FileName>(<LineNumber>) : <Type> <Type[0]><MessageCode>: <Text> : <MsgFmt>
 455
 456     Parser (LineNumber != 0)
 457       VfrCompile.cpp(330) : error E2660: AddVfrDataStructField : function does not take 2 parameters
 458     Generic utility (LineNumber == 0)
 459       UtilityName : error E1234 : Text string : MsgFmt string and args
 460
 461 --*/
 462 {
 463   CHAR8 Line[MAX_LINE_LEN];
 464   CHAR8 Line2[MAX_LINE_LEN];
 465   CHAR8 *Cptr;
 466   //
 467   // If given a filename, then add it (and the line number) to the string.
 468   // If there's no filename, then use the program name if provided.
 469   //
 470   if (FileName != NULL) {
 471     Cptr = FileName;
 472   } else if (mUtilityName[0] != 0) {
 473     Cptr = mUtilityName;
 474   } else {
 475     Cptr = "Unknown utility";
 476   }
 477
 478   strcpy (Line, Cptr);
 479   if (LineNumber != 0) {
 480     sprintf (Line2, "(%d)", LineNumber);
 481     strcat (Line, Line2);
 482   }
 483   //
 484   // Have to print an error code or Visual Studio won't find the
 485   // message for you. It has to be decimal digits too.
 486   //
 487   sprintf (Line2, " : %s %c%04d", Type, toupper (Type[0]), MessageCode);
 488   strcat (Line, Line2);
 489   fprintf (stdout, "%s", Line);
 490   //
 491   // If offending text was provided, then print it
 492   //
 493   if (Text != NULL) {
 494     fprintf (stdout, ": %s ", Text);
 495   }
 496   //
 497   // Print formatted message if provided
 498   //
 499   if (MsgFmt != NULL) {
 500     vsprintf (Line2, MsgFmt, List);
 501     fprintf (stdout, ": %s", Line2);
 502   }
 503
 504   fprintf (stdout, "\n");
 505 }
 506
 507 void
 508 ParserSetPosition (
 509   CHAR8   *SourceFileName,
 510   UINT32  LineNum
 511   )
 512 /*++
 513
 514 Routine Description:
 515   Set the position in a file being parsed. This can be used to
 516   print error messages deeper down in a parser.
 517
 518 Arguments:
 519   SourceFileName - name of the source file being parsed
 520   LineNum        - line number of the source file being parsed
 521
 522 Returns:
 523   NA
 524
 525 --*/
 526 {
 527   mSourceFileName     = SourceFileName;
 528   mSourceFileLineNum  = LineNum;
 529 }
 530
 531 void
 532 SetUtilityName (
 533   CHAR8   *UtilityName
 534   )
 535 /*++
 536
 537 Routine Description:
 538   All printed error/warning/debug messages follow the same format, and
 539   typically will print a filename or utility name followed by the error
 540   text. However if a filename is not passed to the print routines, then
 541   they'll print the utility name if you call this function early in your
 542   app to set the utility name.
 543
 544 Arguments:
 545   UtilityName  -  name of the utility, which will be printed with all
 546                   error/warning/debug messags.
 547
 548 Returns:
 549   NA
 550
 551 --*/
 552 {
 553   //
 554   // Save the name of the utility in our local variable. Make sure its
 555   // length does not exceed our buffer.
 556   //
 557   if (UtilityName != NULL) {
 558     if (strlen (UtilityName) >= sizeof (mUtilityName)) {
 559       Error (UtilityName, 0, 0, "application error", "utility name length exceeds internal buffer size");
 560       strncpy (mUtilityName, UtilityName, sizeof (mUtilityName) - 1);
 561       mUtilityName[sizeof (mUtilityName) - 1] = 0;
 562       return ;
 563     } else {
 564       strcpy (mUtilityName, UtilityName);
 565     }
 566   } else {
 567     Error (NULL, 0, 0, "application error", "SetUtilityName() called with NULL utility name");
 568   }
 569 }
 570
 571 STATUS
 572 GetUtilityStatus (
 573   VOID
 574   )
 575 /*++
 576
 577 Routine Description:
 578   When you call Error() or Warning(), this module keeps track of it and
 579   sets a local mStatus to STATUS_ERROR or STATUS_WARNING. When the utility
 580   exits, it can call this function to get the status and use it as a return
 581   value.
 582
 583 Arguments:
 584   None.
 585
 586 Returns:
 587   Worst-case status reported, as defined by which print function was called.
 588
 589 --*/
 590 {
 591   return mStatus;
 592 }
 593
 594 void
 595 SetDebugMsgMask (
 596   UINT32  DebugMask
 597   )
 598 /*++
 599
 600 Routine Description:
 601   Set the debug printing mask. This is used by the DebugMsg() function
 602   to determine when/if a debug message should be printed.
 603
 604 Arguments:
 605   DebugMask  - bitmask, specific to the calling application
 606
 607 Returns:
 608   NA
 609
 610 --*/
 611 {
 612   mDebugMsgMask = DebugMask;
 613 }
 614
 615 void
 616 SetPrintLimits (
 617   UINT32  MaxErrors,
 618   UINT32  MaxWarnings,
 619   UINT32  MaxWarningsPlusErrors
 620   )
 621 /*++
 622
 623 Routine Description:
 624   Set the limits of how many errors, warnings, and errors+warnings
 625   we will print.
 626
 627 Arguments:
 628   MaxErrors       - maximum number of error messages to print
 629   MaxWarnings     - maximum number of warning messages to print
 630   MaxWarningsPlusErrors
 631                   - maximum number of errors+warnings to print
 632
 633 Returns:
 634   NA
 635
 636 --*/
 637 {
 638   mMaxErrors              = MaxErrors;
 639   mMaxWarnings            = MaxWarnings;
 640   mMaxWarningsPlusErrors  = MaxWarningsPlusErrors;
 641   mPrintLimitsSet         = 1;
 642 }
 643
 644 static
 645 void
 646 PrintLimitExceeded (
 647   VOID
 648   )
 649 {
 650   static INT8 mPrintLimitExceeded = 0;
 651   //
 652   // If we've already printed the message, do nothing. Otherwise
 653   // temporarily increase our print limits so we can pass one
 654   // more message through.
 655   //
 656   if (mPrintLimitExceeded == 0) {
 657     mPrintLimitExceeded++;
 658     mMaxErrors++;
 659     mMaxWarnings++;
 660     mMaxWarningsPlusErrors++;
 661     Error (NULL, 0, 0, "error/warning print limit exceeded", NULL);
 662     mMaxErrors--;
 663     mMaxWarnings--;
 664     mMaxWarningsPlusErrors--;
 665   }
 666 }
 667
 668 #if 0
 669 void
 670 TestUtilityMessages (
 671   VOID
 672   )
 673 {
 674   char *ArgStr = "ArgString";
 675   int  ArgInt;
 676
 677   ArgInt  = 0x12345678;
 678   //
 679   // Test without setting utility name
 680   //
 681   fprintf (stdout, "* Testing without setting utility name\n");
 682   fprintf (stdout, "** Test debug message not printed\n");
 683   DebugMsg (NULL, 0, 0x00000001, NULL, NULL);
 684   fprintf (stdout, "** Test warning with two strings and two args\n");
 685   Warning (NULL, 0, 1234, "Text1", "Text2 %s 0x%X", ArgStr, ArgInt);
 686   fprintf (stdout, "** Test error with two strings and two args\n");
 687   Warning (NULL, 0, 1234, "Text1", "Text2 %s 0x%X", ArgStr, ArgInt);
 688   fprintf (stdout, "** Test parser warning with nothing\n");
 689   ParserWarning (0, NULL, NULL);
 690   fprintf (stdout, "** Test parser error with nothing\n");
 691   ParserError (0, NULL, NULL);
 692   //
 693   // Test with utility name set now
 694   //
 695   fprintf (stdout, "** Testingin with utility name set\n");
 696   SetUtilityName ("MyUtilityName");
 697   //
 698   // Test debug prints
 699   //
 700   SetDebugMsgMask (2);
 701   fprintf (stdout, "** Test debug message with one string\n");
 702   DebugMsg (NULL, 0, 0x00000002, "Text1", NULL);
 703   fprintf (stdout, "** Test debug message with one string\n");
 704   DebugMsg (NULL, 0, 0x00000002, NULL, "Text2");
 705   fprintf (stdout, "** Test debug message with two strings\n");
 706   DebugMsg (NULL, 0, 0x00000002, "Text1", "Text2");
 707   fprintf (stdout, "** Test debug message with two strings and two args\n");
 708   DebugMsg (NULL, 0, 0x00000002, "Text1", "Text2 %s 0x%X", ArgStr, ArgInt);
 709   //
 710   // Test warning prints
 711   //
 712   fprintf (stdout, "** Test warning with no strings\n");
 713   Warning (NULL, 0, 1234, NULL, NULL);
 714   fprintf (stdout, "** Test warning with one string\n");
 715   Warning (NULL, 0, 1234, "Text1", NULL);
 716   fprintf (stdout, "** Test warning with one string\n");
 717   Warning (NULL, 0, 1234, NULL, "Text2");
 718   fprintf (stdout, "** Test warning with two strings and two args\n");
 719   Warning (NULL, 0, 1234, "Text1", "Text2 %s 0x%X", ArgStr, ArgInt);
 720   //
 721   // Test error prints
 722   //
 723   fprintf (stdout, "** Test error with no strings\n");
 724   Error (NULL, 0, 1234, NULL, NULL);
 725   fprintf (stdout, "** Test error with one string\n");
 726   Error (NULL, 0, 1234, "Text1", NULL);
 727   fprintf (stdout, "** Test error with one string\n");
 728   Error (NULL, 0, 1234, NULL, "Text2");
 729   fprintf (stdout, "** Test error with two strings and two args\n");
 730   Error (NULL, 0, 1234, "Text1", "Text2 %s 0x%X", ArgStr, ArgInt);
 731   //
 732   // Test parser prints
 733   //
 734   fprintf (stdout, "** Test parser errors\n");
 735   ParserSetPosition (__FILE__, __LINE__ + 1);
 736   ParserError (1234, NULL, NULL);
 737   ParserSetPosition (__FILE__, __LINE__ + 1);
 738   ParserError (1234, "Text1", NULL);
 739   ParserSetPosition (__FILE__, __LINE__ + 1);
 740   ParserError (1234, NULL, "Text2");
 741   ParserSetPosition (__FILE__, __LINE__ + 1);
 742   ParserError (1234, "Text1", "Text2");
 743   ParserSetPosition (__FILE__, __LINE__ + 1);
 744   ParserError (1234, "Text1", "Text2 %s 0x%X", ArgStr, ArgInt);
 745
 746   fprintf (stdout, "** Test parser warnings\n");
 747   ParserSetPosition (__FILE__, __LINE__ + 1);
 748   ParserWarning (4321, NULL, NULL);
 749   ParserSetPosition (__FILE__, __LINE__ + 1);
 750   ParserWarning (4321, "Text1", NULL);
 751   ParserSetPosition (__FILE__, __LINE__ + 1);
 752   ParserWarning (4321, NULL, "Text2");
 753   ParserSetPosition (__FILE__, __LINE__ + 1);
 754   ParserWarning (4321, "Text1", "Text2");
 755   ParserSetPosition (__FILE__, __LINE__ + 1);
 756   ParserWarning (4321, "Text1", "Text2 %s 0x%X", ArgStr, ArgInt);
 757 }
 758 #endif