1#!/usr/bin/env python 2 3r""" 4This module provides functions which are useful to plug-in call point programs. 5""" 6 7import sys 8import os 9import re 10import collections 11 12import gen_print as gp 13import gen_misc as gm 14import gen_cmd as gc 15 16PLUG_VAR_PREFIX = os.environ.get("PLUG_VAR_PREFIX", "AUTOBOOT") 17 18 19def get_plug_in_package_name(case=None): 20 r""" 21 Return the plug-in package name (e.g. "OS_Console", "DB_Logging"). 22 23 Description of argument(s): 24 case Indicates whether the value returned 25 should be converted to upper or lower 26 case. Valid values are "upper", "lower" 27 or None. 28 """ 29 30 plug_in_package_name = os.path.basename(gp.pgm_dir_path[:-1]) 31 if case == "upper": 32 return plug_in_package_name.upper() 33 elif case == "lower": 34 return plug_in_package_name.lower() 35 else: 36 return plug_in_package_name 37 38 39def return_plug_vars(general=True, 40 custom=True): 41 r""" 42 Return an OrderedDict which is sorted by key and which contains all of the 43 plug-in environment variables. 44 45 Example excerpt of resulting dictionary: 46 47 plug_var_dict: 48 [AUTOBOOT_BASE_TOOL_DIR_PATH]: /tmp/ 49 [AUTOBOOT_BB_LEVEL]: <blank> 50 [AUTOBOOT_BOOT_FAIL]: 0 51 ... 52 53 This function also does the following: 54 - Set a default value for environment variable 55 AUTOBOOT_OPENBMC_NICKNAME/AUTOIPL_FSP1_NICKNAME if it is not already set. 56 - Register PASSWORD variables to prevent their values from being printed. 57 58 Note: The programmer may set a default for any given environment variable 59 by declaring a global variable of the same name and setting its value. 60 For example, let's say the calling program has this global declaration: 61 62 PERF_EXERCISERS_TOTAL_TIMEOUT = '180' 63 64 If environment variable PERF_EXERCISERS_TOTAL_TIMEOUT is blank or not set, 65 this function will set it to 180. 66 67 Description of argument(s): 68 general Return general plug-in parms (e.g. those 69 beginning with "AUTOBOOT" or "AUTOGUI"). 70 custom Return custom plug-in parms (i.e. those 71 beginning with the upper case name of the 72 plug-in package, for example 73 "OBMC_SAMPLE_PARM1"). 74 """ 75 76 regex_list = [] 77 if not (general or custom): 78 return collections.OrderedDict() 79 plug_in_package_name = get_plug_in_package_name(case="upper") 80 if general: 81 regex_list = [PLUG_VAR_PREFIX, "AUTOGUI"] 82 if custom: 83 regex_list.append(plug_in_package_name) 84 85 regex = "^(" + "|".join(regex_list) + ")_" 86 87 # Set a default for nickname. 88 if os.environ.get("AUTOBOOT_OPENBMC_NICKNAME", "") == "": 89 os.environ['AUTOBOOT_OPENBMC_NICKNAME'] = \ 90 os.environ.get("AUTOBOOT_OPENBMC_HOST", "") 91 92 if os.environ.get("AUTOIPL_FSP1_NICKNAME", "") == "": 93 os.environ['AUTOIPL_FSP1_NICKNAME'] = \ 94 os.environ.get("AUTOIPL_FSP1_NAME", "").split(".")[0] 95 96 # For all variables specified in the parm_def file, we want them to 97 # default to "" rather than being unset. 98 # Process the parm_def file if it exists. 99 parm_def_file_path = gp.pgm_dir_path + "parm_def" 100 if os.path.exists(parm_def_file_path): 101 parm_defs = gm.my_parm_file(parm_def_file_path) 102 else: 103 parm_defs = collections.OrderedDict() 104 # Example parm_defs: 105 # parm_defs: 106 # parm_defs[rest_fail]: boolean 107 # parm_defs[command]: string 108 # parm_defs[esel_stop_file_path]: string 109 110 # Create a list of plug-in environment variables by pre-pending <all caps 111 # plug-in package name>_<all caps var name> 112 plug_in_parm_names = [plug_in_package_name + "_" + x for x in 113 map(str.upper, parm_defs.keys())] 114 # Example plug_in_parm_names: 115 # plug_in_parm_names: 116 # plug_in_parm_names[0]: STOP_REST_FAIL 117 # plug_in_parm_names[1]: STOP_COMMAND 118 # plug_in_parm_names[2]: STOP_ESEL_STOP_FILE_PATH 119 120 # Initialize unset plug-in vars. 121 for var_name in plug_in_parm_names: 122 # If there is a global variable with the same name as the environment 123 # variable, use its value as a default. 124 default_value = gm.get_mod_global(var_name, "") 125 os.environ[var_name] = os.environ.get(var_name, default_value) 126 if os.environ[var_name] == "": 127 os.environ[var_name] = default_value 128 129 plug_var_dict = \ 130 collections.OrderedDict(sorted({k: v for (k, v) in 131 os.environ.items() 132 if re.match(regex, k)}.items())) 133 # Register password values to prevent printing them out. Any plug var 134 # whose name ends in PASSWORD will be registered. 135 password_vals = {k: v for (k, v) in plug_var_dict.items() 136 if re.match(r".*_PASSWORD$", k)}.values() 137 map(gp.register_passwords, password_vals) 138 139 return plug_var_dict 140 141 142def sprint_plug_vars(headers=1, **kwargs): 143 r""" 144 Sprint the plug-in environment variables (i.e. those that begin with the 145 global PLUG_VAR_PREFIX value or those that begin with <plug-in 146 package_name>_ in upper case letters.). 147 148 Example excerpt of output: 149 AUTOBOOT_BASE_TOOL_DIR_PATH=/tmp/ 150 AUTOBOOT_BB_LEVEL= 151 AUTOBOOT_BOOT_FAIL=0 152 AUTOBOOT_BOOT_FAIL_THRESHOLD=1000000 153 154 Description of argument(s): 155 headers Print a header and a footer. 156 kwargs These are passed directly to 157 return_plug_vars. See return_plug_vars 158 doc string for details. 159 """ 160 plug_var_dict = return_plug_vars(**kwargs) 161 buffer = "" 162 if headers: 163 buffer += "\n" + gp.sprint_dashes() 164 for key, value in plug_var_dict.items(): 165 buffer += gp.sprint_varx(key, value) 166 if headers: 167 buffer += gp.sprint_dashes() + "\n" 168 169 return buffer 170 171 172def print_plug_in_header(): 173 r""" 174 Print plug-in header. 175 176 When debug is set, print all plug_prefix variables (e.g. 177 AUTOBOOT_OPENBMC_HOST, etc.) and all plug-in environment variables (e.g. 178 OBMC_SAMPLE_PARM1) with surrounding dashed lines. When debug is not set, 179 print only the plug-in environment variables (e.g. OBMC_SAMPLE_PARM1) with 180 no surrounding dashed lines. 181 182 NOTE: plug-in environment variables means any variable defined in the 183 <plug-in dir>/parm_def file plus any environment variables whose names 184 begin with the upper-case plug-in package name. 185 """ 186 187 dprint_plug_vars() 188 if not debug: 189 qprint_plug_vars(headers=0, general=False, custom=True) 190 191 192def get_plug_vars(): 193 r""" 194 Get all plug-in variables and put them in corresponding global variables. 195 196 This would include all environment variables beginning with either the 197 global PLUG_VAR_PREFIX value or with the upper case version of the plug-in 198 package name + underscore (e.g. OP_SAMPLE_VAR1 for plug-in OP_Sample). 199 200 The global variables to be set will be both with and without the global 201 PLUG_VAR_PREFIX value prefix. For example, if the environment variable in 202 question is AUTOBOOT_OPENBMC_HOST, this function will set global variable 203 AUTOBOOT_OPENBMC_HOST and global variable OPENBMC_HOST. 204 """ 205 206 module = sys.modules['__main__'] 207 plug_var_dict = return_plug_vars() 208 209 # Get all PLUG_VAR_PREFIX environment variables and put them into globals. 210 for key, value in plug_var_dict.items(): 211 setattr(module, key, value) 212 setattr(module, re.sub("^" + PLUG_VAR_PREFIX + "_", "", key), value) 213 214 215def get_plug_default(var_name, 216 default=None): 217 r""" 218 Derive and return a default value for the given parm variable. 219 220 Dependencies: 221 Global variable PLUG_VAR_PREFIX must be set. 222 223 This function will assign a default by checking the following environment 224 variables in the order shown. The first one that has a value will be used. 225 - <upper case package_name>_<var_name> 226 - <PLUG_VAR_PREFIX>_OVERRIDE_<var_name> 227 - <PLUG_VAR_PREFIX>_<var_name> 228 229 If none of these are found, this function will return the value passed by 230 the caller in the "default" parm. 231 232 Example: 233 234 Let's say your plug-in is named "OS_Console" and you call this function as 235 follows: 236 237 get_plug_default("quiet", 0) 238 239 The first of these environment variables that is found to be set will be 240 used to provide the default value. 241 - OS_CONSOLE_QUIET 242 - AUTOBOOT_OVERRIDE_QUIET 243 - AUTOBOOT_QUIET 244 245 If none of those has a value, 0 (as specified by the caller in this 246 example) is returned. 247 248 Let's say the master driver program is named obmc_boot. obmc_boot program 249 is responsible for calling plug-ins. Let's further suppose that the user 250 wishes to run the master program with --debug=0 but wishes to have all 251 plug-ins run with --debug=1. This could be accomplished with the 252 following call: 253 export AUTOBOOT_OVERRIDE_DEBUG=1 ; obmc_boot --debug=0 254 --plug_in_dir_paths=<list of plug ins> 255 256 As another example, let's suppose that the user wishes to have just the 257 OS_Console plug-in run with debug and everything else to default to 258 debug=0. This could be accomplished as follows: 259 export OS_CONSOLE_DEBUG=1 ; obmc_boot --debug=0 --plug_in_dir_paths=<list 260 of plug ins> 261 262 And as one more example, let's say the user wishes to have obmc_boot and 263 OS_Console run without debug but have all other plug-ins run with debug: 264 export AUTOBOOT_OVERRIDE_DEBUG=1 ; export OS_CONSOLE_DEBUG=0 ; obmc_boot 265 --debug=0 --plug_in_dir_paths=<list of plug ins> 266 267 Description of argument(s): 268 var_name The name of the variable for which a 269 default value is to be calculated. 270 default The default value if one cannot be 271 determined. 272 """ 273 274 var_name = var_name.upper() 275 plug_in_package_name = get_plug_in_package_name(case="upper") 276 277 package_var_name = plug_in_package_name + "_" + var_name 278 default_value = os.environ.get(package_var_name, None) 279 if default_value is not None: 280 # A package-name version of the variable was found so return its value. 281 return(default_value) 282 283 plug_var_name = PLUG_VAR_PREFIX + "_OVERRIDE_" + var_name 284 default_value = os.environ.get(plug_var_name, None) 285 if default_value is not None: 286 # A PLUG_VAR_PREFIX version of the variable was found so return its 287 # value. 288 return default_value 289 290 plug_var_name = PLUG_VAR_PREFIX + "_" + var_name 291 default_value = os.environ.get(plug_var_name, None) 292 if default_value is not None: 293 # A PLUG_VAR_PREFIX version of the variable was found so return its 294 # value. 295 return default_value 296 297 return default 298 299 300def srequired_plug_in(req_plug_in_names, 301 plug_in_dir_paths=None): 302 r""" 303 Return an empty string if the required plug-ins are found in 304 plug_in_dir_paths. Otherwise, return an error string. 305 306 Example call: 307 error_message = srequired_plug_in(req_plug_in_names, plug_in_dir_paths) 308 309 Description of argument(s): 310 req_plug_in_names A list of plug_in names that the caller 311 requires (e.g. ['OS_Console']). 312 plug_in_dir_paths A string which is a colon-delimited list 313 of plug-ins specified by the user (e.g. 314 DB_Logging:FFDC:OS_Console:Perf). Path 315 values (e.g. "/home/robot/dir1") will be 316 stripped from this list to do the 317 analysis. Default value is the 318 <PLUG_VAR_PREFIX>_PLUG_IN_DIR_PATHS 319 environment variable. 320 """ 321 322 # Calculate default value for plug_in_dir_paths. 323 if plug_in_dir_paths is None: 324 plug_in_dir_paths = os.environ.get(PLUG_VAR_PREFIX 325 + "_PLUG_IN_DIR_PATHS", "") 326 327 error_message = "" 328 329 # Convert plug_in_dir_paths to a list of base names. 330 plug_in_dir_paths = \ 331 list(filter(None, map(os.path.basename, plug_in_dir_paths.split(":")))) 332 333 # Check for each of the user's required plug-ins. 334 for plug_in_name in req_plug_in_names: 335 if plug_in_name not in plug_in_dir_paths: 336 error_message = "The \"" + get_plug_in_package_name() +\ 337 "\" plug-in cannot run unless the user also selects the \"" +\ 338 plug_in_name + "\" plug in:\n" +\ 339 gp.sprint_var(plug_in_dir_paths) 340 341 return error_message 342 343 344def required_plug_in(req_plug_in_names, 345 plug_in_dir_paths=None): 346 r""" 347 Return True if each of the plug-ins in req_plug_in_names can be found in 348 plug_in_dir_paths Otherwise, return False and print an error message to 349 stderr. 350 351 Example call: 352 if not required_plug_in(['OS_Console'], AUTOBOOT_PLUG_IN_DIR_PATHS): 353 return False 354 355 Description of argument(s): 356 (See Description of arguments for srequired_plug_in (above)). 357 """ 358 359 error_message = srequired_plug_in(req_plug_in_names, plug_in_dir_paths) 360 if not error_message == "": 361 gp.print_error_report(error_message) 362 return False 363 364 return True 365 366 367def compose_plug_in_save_dir_path(plug_in_package_name=None): 368 r""" 369 Create and return a directory path name that is suitable for saving 370 plug-in data. 371 372 The name will be comprised of things such as plug_in package name, pid, 373 etc. in order to guarantee that it is unique for a given test run. 374 375 Description of argument(s): 376 plug_in_package_name The plug-in package name. This defaults 377 to the name of the caller's plug-in 378 package. However, the caller can specify 379 another value in order to retrieve data 380 saved by another plug-in package. 381 """ 382 383 plug_in_package_name = gm.dft(plug_in_package_name, 384 get_plug_in_package_name()) 385 386 BASE_TOOL_DIR_PATH = \ 387 gm.add_trailing_slash(os.environ.get(PLUG_VAR_PREFIX 388 + "_BASE_TOOL_DIR_PATH", 389 "/tmp/")) 390 NICKNAME = os.environ.get("AUTOBOOT_OPENBMC_NICKNAME", "") 391 if NICKNAME == "": 392 NICKNAME = os.environ["AUTOIPL_FSP1_NICKNAME"] 393 MASTER_PID = os.environ[PLUG_VAR_PREFIX + "_MASTER_PID"] 394 gp.pvars(BASE_TOOL_DIR_PATH, NICKNAME, plug_in_package_name, MASTER_PID) 395 return BASE_TOOL_DIR_PATH + gm.username() + "/" + NICKNAME + "/" +\ 396 plug_in_package_name + "/" + str(MASTER_PID) + "/" 397 398 399def create_plug_in_save_dir(plug_in_package_name=None): 400 r""" 401 Create a directory suitable for saving plug-in processing data. See 402 compose_plug_in_save_dir_path for details. 403 404 Description of argument(s): 405 plug_in_package_name See compose_plug_in_save_dir_path for 406 details. 407 """ 408 409 plug_in_save_dir_path = compose_plug_in_save_dir_path(plug_in_package_name) 410 if os.path.isdir(plug_in_save_dir_path): 411 return plug_in_save_dir_path 412 gc.shell_cmd("mkdir -p " + plug_in_save_dir_path) 413 return plug_in_save_dir_path 414 415 416def delete_plug_in_save_dir(plug_in_package_name=None): 417 r""" 418 Delete the plug_in save directory. See compose_plug_in_save_dir_path for 419 details. 420 421 Description of argument(s): 422 plug_in_package_name See compose_plug_in_save_dir_path for 423 details. 424 """ 425 426 gc.shell_cmd("rm -rf " 427 + compose_plug_in_save_dir_path(plug_in_package_name)) 428 429 430def save_plug_in_value(value, plug_in_package_name=None): 431 r""" 432 Save a value in a plug-in save file. The value may be retrieved later via 433 a call to the restore_plug_in_value function. 434 435 This function will figure out the variable name of the value passed and 436 use that name in creating the plug-in save file. 437 438 Example call: 439 440 my_var1 = 5 441 save_plug_in_value(my_var1) 442 443 In this example, the value "5" would be saved to the "my_var1" file in the 444 plug-in save directory. 445 446 Description of argument(s): 447 value The value to be saved. 448 plug_in_package_name See compose_plug_in_save_dir_path for 449 details. 450 """ 451 452 # Get the name of the variable used as argument one to this function. 453 var_name = gp.get_arg_name(0, 1, stack_frame_ix=2) 454 plug_in_save_dir_path = create_plug_in_save_dir(plug_in_package_name) 455 save_file_path = plug_in_save_dir_path + var_name 456 gp.qprint_timen("Saving \"" + var_name + "\" value.") 457 gc.shell_cmd("echo '" + str(value) + "' > " + save_file_path) 458 459 460def restore_plug_in_value(default="", plug_in_package_name=None): 461 r""" 462 Return a value from a plug-in save file. 463 464 The name of the value to be restored will be determined by this function 465 based on the lvalue being assigned. Consider the following example: 466 467 my_var1 = restore_plug_in_value(2) 468 469 In this example, this function would look for the "my_var1" file in the 470 plug-in save directory, read its value and return it. If no such file 471 exists, the default value of 2 would be returned. 472 473 Description of argument(s): 474 default The default value to be returned if there 475 is no plug-in save file for the value in 476 question. 477 plug_in_package_name See compose_plug_in_save_dir_path for 478 details. 479 """ 480 481 # Get the lvalue from the caller's invocation of this function. 482 lvalue = gp.get_arg_name(0, -1, stack_frame_ix=2) 483 plug_in_save_dir_path = create_plug_in_save_dir(plug_in_package_name) 484 save_file_path = plug_in_save_dir_path + lvalue 485 if os.path.isfile(save_file_path): 486 gp.qprint_timen("Restoring " + lvalue + " value from " 487 + save_file_path + ".") 488 value = gm.file_to_list(save_file_path, newlines=0, comments=0, 489 trim=1)[0] 490 if type(default) is bool: 491 # Convert from string to bool. 492 value = (value == 'True') 493 if type(default) is int: 494 # Convert from string to int. 495 value = int(value) 496 gp.qprint_varx(lvalue, value) 497 return value 498 else: 499 gp.qprint_timen("Save file " + save_file_path 500 + " does not exist so returning default value.") 501 gp.qprint_var(default) 502 return default 503 504 505# Create print wrapper functions for all sprint functions defined above. 506# func_names contains a list of all print functions which should be created 507# from their sprint counterparts. 508func_names = ['print_plug_vars'] 509 510# stderr_func_names is a list of functions whose output should go to stderr 511# rather than stdout. 512stderr_func_names = [] 513 514replace_dict = dict(gp.replace_dict) 515replace_dict['mod_qualifier'] = 'gp.' 516func_defs = gp.create_print_wrapper_funcs(func_names, stderr_func_names, 517 replace_dict) 518gp.gp_debug_print(func_defs) 519exec(func_defs) 520