4231a8193e
replace "== None" with "is None" and "!= None" with "is not None" Cc: Yonghong Zhu <yonghong.zhu@intel.com> Cc: Liming Gao <liming.gao@intel.com> Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Jaben Carsey <jaben.carsey@intel.com> Reviewed-by: Yonghong Zhu <yonghong.zhu@intel.com>
430 lines
21 KiB
Python
430 lines
21 KiB
Python
## @file
|
|
# This module provide command line entry for generating package document!
|
|
#
|
|
# Copyright (c) 2011 - 2018, Intel Corporation. All rights reserved.<BR>
|
|
#
|
|
# This program and the accompanying materials are licensed and made available
|
|
# under the terms and conditions of the BSD License which accompanies this
|
|
# distribution. The full text of the license may be found at
|
|
# http://opensource.org/licenses/bsd-license.php
|
|
#
|
|
# THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
|
|
#
|
|
|
|
import os, sys, logging, traceback, subprocess
|
|
from optparse import OptionParser
|
|
|
|
import plugins.EdkPlugins.edk2.model.baseobject as baseobject
|
|
import plugins.EdkPlugins.edk2.model.doxygengen as doxygengen
|
|
|
|
gArchMarcoDict = {'ALL' : 'MDE_CPU_IA32 MDE_CPU_X64 MDE_CPU_EBC MDE_CPU_IPF _MSC_EXTENSIONS __GNUC__ __INTEL_COMPILER',
|
|
'IA32_MSFT': 'MDE_CPU_IA32 _MSC_EXTENSIONS',
|
|
'IA32_GNU' : 'MDE_CPU_IA32 __GNUC__',
|
|
'X64_MSFT' : 'MDE_CPU_X64 _MSC_EXTENSIONS ASM_PFX= OPTIONAL= ',
|
|
'X64_GNU' : 'MDE_CPU_X64 __GNUC__ ASM_PFX= OPTIONAL= ',
|
|
'IPF_MSFT' : 'MDE_CPU_IPF _MSC_EXTENSIONS ASM_PFX= OPTIONAL= ',
|
|
'IPF_GNU' : 'MDE_CPU_IPF __GNUC__ ASM_PFX= OPTIONAL= ',
|
|
'EBC_INTEL': 'MDE_CPU_EBC __INTEL_COMPILER ASM_PFX= OPTIONAL= '}
|
|
|
|
def parseCmdArgs():
|
|
parser = OptionParser(version="Package Document Generation Tools - Version 0.1")
|
|
parser.add_option('-w', '--workspace', action='store', type='string', dest='WorkspacePath',
|
|
help='Specify workspace absolute path. For example: c:\\tianocore')
|
|
parser.add_option('-p', '--decfile', action='store', dest='PackagePath',
|
|
help='Specify the absolute path for package DEC file. For example: c:\\tianocore\\MdePkg\\MdePkg.dec')
|
|
parser.add_option('-x', '--doxygen', action='store', dest='DoxygenPath',
|
|
help='Specify the absolute path of doxygen tools installation. For example: C:\\Program Files\\doxygen\bin\doxygen.exe')
|
|
parser.add_option('-o', '--output', action='store', dest='OutputPath',
|
|
help='Specify the document output path. For example: c:\\docoutput')
|
|
parser.add_option('-a', '--arch', action='store', dest='Arch', choices=gArchMarcoDict.keys(),
|
|
help='Specify the architecture used in preprocess package\'s source. For example: -a IA32_MSFT')
|
|
parser.add_option('-m', '--mode', action='store', dest='DocumentMode', choices=['CHM', 'HTML'],
|
|
help='Specify the document mode from : CHM or HTML')
|
|
parser.add_option('-i', '--includeonly', action='store_true', dest='IncludeOnly',
|
|
help='Only generate document for package\'s public interfaces produced by include folder. ')
|
|
parser.add_option('-c', '--htmlworkshop', dest='HtmlWorkshopPath',
|
|
help='Specify the absolute path for Microsoft HTML Workshop\'s hhc.exe file. For example: C:\\Program Files\\HTML Help Workshop\\hhc.exe')
|
|
(options, args) = parser.parse_args()
|
|
|
|
# validate the options
|
|
errors = []
|
|
if options.WorkspacePath is None:
|
|
errors.append('- Please specify workspace path via option -w!')
|
|
elif not os.path.exists(options.WorkspacePath):
|
|
errors.append("- Invalid workspace path %s! The workspace path should be exist in absolute path!" % options.WorkspacePath)
|
|
|
|
if options.PackagePath is None:
|
|
errors.append('- Please specify package DEC file path via option -p!')
|
|
elif not os.path.exists(options.PackagePath):
|
|
errors.append("- Invalid package's DEC file path %s! The DEC path should be exist in absolute path!" % options.PackagePath)
|
|
|
|
default = "C:\\Program Files\\doxygen\\bin\\doxygen.exe"
|
|
if options.DoxygenPath is None:
|
|
if os.path.exists(default):
|
|
print "Warning: Assume doxygen tool is installed at %s. If not, please specify via -x" % default
|
|
options.DoxygenPath = default
|
|
else:
|
|
errors.append('- Please specify the path of doxygen tool installation via option -x! or install it in default path %s' % default)
|
|
elif not os.path.exists(options.DoxygenPath):
|
|
errors.append("- Invalid doxygen tool path %s! The doxygen tool path should be exist in absolute path!" % options.DoxygenPath)
|
|
|
|
if options.OutputPath is not None:
|
|
if not os.path.exists(options.OutputPath):
|
|
# create output
|
|
try:
|
|
os.makedirs(options.OutputPath)
|
|
except:
|
|
errors.append('- Fail to create the output directory %s' % options.OutputPath)
|
|
else:
|
|
if options.PackagePath is not None and os.path.exists(options.PackagePath):
|
|
dirpath = os.path.dirname(options.PackagePath)
|
|
default = os.path.join (dirpath, "Document")
|
|
print 'Warning: Assume document output at %s. If not, please specify via option -o' % default
|
|
options.OutputPath = default
|
|
if not os.path.exists(default):
|
|
try:
|
|
os.makedirs(default)
|
|
except:
|
|
errors.append('- Fail to create default output directory %s! Please specify document output diretory via option -o' % default)
|
|
else:
|
|
errors.append('- Please specify document output path via option -o!')
|
|
|
|
if options.Arch is None:
|
|
options.Arch = 'ALL'
|
|
print "Warning: Assume arch is \"ALL\". If not, specify via -a"
|
|
|
|
if options.DocumentMode is None:
|
|
options.DocumentMode = "HTML"
|
|
print "Warning: Assume document mode is \"HTML\". If not, specify via -m"
|
|
|
|
if options.IncludeOnly is None:
|
|
options.IncludeOnly = False
|
|
print "Warning: Assume generate package document for all package\'s source including publich interfaces and implementation libraries and modules."
|
|
|
|
if options.DocumentMode.lower() == 'chm':
|
|
default = "C:\\Program Files\\HTML Help Workshop\\hhc.exe"
|
|
if options.HtmlWorkshopPath is None:
|
|
if os.path.exists(default):
|
|
print 'Warning: Assume the installation path of Microsoft HTML Workshop is %s. If not, specify via option -c.' % default
|
|
options.HtmlWorkshopPath = default
|
|
else:
|
|
errors.append('- Please specify the installation path of Microsoft HTML Workshop via option -c!')
|
|
elif not os.path.exists(options.HtmlWorkshopPath):
|
|
errors.append('- The installation path of Microsoft HTML Workshop %s does not exists. ' % options.HtmlWorkshopPath)
|
|
|
|
if len(errors) != 0:
|
|
print '\n'
|
|
parser.error('Fail to start due to following reasons: \n%s' %'\n'.join(errors))
|
|
return (options.WorkspacePath, options.PackagePath, options.DoxygenPath, options.OutputPath,
|
|
options.Arch, options.DocumentMode, options.IncludeOnly, options.HtmlWorkshopPath)
|
|
|
|
def createPackageObject(wsPath, pkgPath):
|
|
try:
|
|
pkgObj = baseobject.Package(None, wsPath)
|
|
pkgObj.Load(pkgPath)
|
|
except:
|
|
logging.getLogger().error ('Fail to create package object!')
|
|
return None
|
|
|
|
return pkgObj
|
|
|
|
def callbackLogMessage(msg, level):
|
|
print msg.strip()
|
|
|
|
def callbackCreateDoxygenProcess(doxPath, configPath):
|
|
if sys.platform == 'win32':
|
|
cmd = '"%s" %s' % (doxPath, configPath)
|
|
else:
|
|
cmd = '%s %s' % (doxPath, configPath)
|
|
print cmd
|
|
subprocess.call(cmd, shell=True)
|
|
|
|
|
|
def DocumentFixup(outPath, arch):
|
|
# find BASE_LIBRARY_JUMP_BUFFER structure reference page
|
|
|
|
print '\n >>> Start fixup document \n'
|
|
|
|
for root, dirs, files in os.walk(outPath):
|
|
for dir in dirs:
|
|
if dir.lower() in ['.svn', '_svn', 'cvs']:
|
|
dirs.remove(dir)
|
|
for file in files:
|
|
if not file.lower().endswith('.html'): continue
|
|
fullpath = os.path.join(outPath, root, file)
|
|
try:
|
|
f = open(fullpath, 'r')
|
|
text = f.read()
|
|
f.close()
|
|
except:
|
|
logging.getLogger().error('\nFail to open file %s\n' % fullpath)
|
|
continue
|
|
if arch.lower() == 'all':
|
|
if text.find('BASE_LIBRARY_JUMP_BUFFER Struct Reference') != -1:
|
|
FixPageBASE_LIBRARY_JUMP_BUFFER(fullpath, text)
|
|
if text.find('MdePkg/Include/Library/BaseLib.h File Reference') != -1:
|
|
FixPageBaseLib(fullpath, text)
|
|
if text.find('IA32_IDT_GATE_DESCRIPTOR Union Reference') != -1:
|
|
FixPageIA32_IDT_GATE_DESCRIPTOR(fullpath, text)
|
|
if text.find('MdePkg/Include/Library/UefiDriverEntryPoint.h File Reference') != -1:
|
|
FixPageUefiDriverEntryPoint(fullpath, text)
|
|
if text.find('MdePkg/Include/Library/UefiApplicationEntryPoint.h File Reference') != -1:
|
|
FixPageUefiApplicationEntryPoint(fullpath, text)
|
|
|
|
print ' >>> Finish all document fixing up! \n'
|
|
|
|
def FixPageBaseLib(path, text):
|
|
print ' >>> Fixup BaseLib file page at file %s \n' % path
|
|
lines = text.split('\n')
|
|
lastBaseJumpIndex = -1
|
|
lastIdtGateDescriptor = -1
|
|
for index in range(len(lines) - 1, -1, -1):
|
|
line = lines[index]
|
|
if line.strip() == '<td class="memname">#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4 </td>':
|
|
lines[index] = '<td class="memname">#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4 [IA32] </td>'
|
|
if line.strip() == '<td class="memname">#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 0x10 </td>':
|
|
lines[index] = '<td class="memname">#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 0x10 [IPF] </td>'
|
|
if line.strip() == '<td class="memname">#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8 </td>':
|
|
lines[index] = '<td class="memname">#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 9 [EBC, x64] </td>'
|
|
if line.find('BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT</a> 4') != -1:
|
|
lines[index] = lines[index].replace('BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT</a> 4',
|
|
'BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT</a> 4 [IA32]')
|
|
if line.find('BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT</a> 0x10') != -1:
|
|
lines[index] = lines[index].replace('BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT</a> 0x10',
|
|
'BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT</a> 0x10 [IPF]')
|
|
if line.find('BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT</a> 8') != -1:
|
|
lines[index] = lines[index].replace('BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT</a> 8',
|
|
'BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT</a> 8 [x64, EBC]')
|
|
if line.find('>BASE_LIBRARY_JUMP_BUFFER</a>') != -1:
|
|
if lastBaseJumpIndex != -1:
|
|
del lines[lastBaseJumpIndex]
|
|
lastBaseJumpIndex = index
|
|
if line.find('>IA32_IDT_GATE_DESCRIPTOR</a></td>') != -1:
|
|
if lastIdtGateDescriptor != -1:
|
|
del lines[lastIdtGateDescriptor]
|
|
lastIdtGateDescriptor = index
|
|
try:
|
|
f = open(path, 'w')
|
|
f.write('\n'.join(lines))
|
|
f.close()
|
|
except:
|
|
logging.getLogger().error(" <<< Fail to fixup file %s\n" % path)
|
|
return
|
|
print " <<< Finish to fixup file %s\n" % path
|
|
|
|
def FixPageIA32_IDT_GATE_DESCRIPTOR(path, text):
|
|
print ' >>> Fixup structure reference IA32_IDT_GATE_DESCRIPTOR at file %s \n' % path
|
|
lines = text.split('\n')
|
|
for index in range(len(lines) - 1, -1, -1):
|
|
line = lines[index].strip()
|
|
if line.find('struct {</td>') != -1 and lines[index - 2].find('>Uint64</a></td>') != -1:
|
|
lines.insert(index, '<tr><td colspan="2"><br><h2>Data Fields For X64</h2></td></tr>')
|
|
if line.find('struct {</td>') != -1 and lines[index - 1].find('Data Fields') != -1:
|
|
lines.insert(index, '<tr><td colspan="2"><br><h2>Data Fields For IA32</h2></td></tr>')
|
|
try:
|
|
f = open(path, 'w')
|
|
f.write('\n'.join(lines))
|
|
f.close()
|
|
except:
|
|
logging.getLogger().error(" <<< Fail to fixup file %s\n" % path)
|
|
return
|
|
print " <<< Finish to fixup file %s\n" % path
|
|
|
|
def FixPageBASE_LIBRARY_JUMP_BUFFER(path, text):
|
|
print ' >>> Fixup structure reference BASE_LIBRARY_JUMP_BUFFER at file %s \n' % path
|
|
lines = text.split('\n')
|
|
bInDetail = True
|
|
bNeedRemove = False
|
|
for index in range(len(lines) - 1, -1, -1):
|
|
line = lines[index]
|
|
if line.find('Detailed Description') != -1:
|
|
bInDetail = False
|
|
if line.startswith('EBC context buffer used by') and lines[index - 1].startswith('x64 context buffer'):
|
|
lines[index] = "IA32/IPF/X64/" + line
|
|
bNeedRemove = True
|
|
if line.startswith("x64 context buffer") or line.startswith('IPF context buffer used by') or \
|
|
line.startswith('IA32 context buffer used by'):
|
|
if bNeedRemove:
|
|
lines.remove(line)
|
|
if line.find('>R0</a>') != -1 and not bInDetail:
|
|
if lines[index - 1] != '<tr><td colspan="2"><br><h2>Data Fields For EBC</h2></td></tr>':
|
|
lines.insert(index, '<tr><td colspan="2"><br><h2>Data Fields For EBC</h2></td></tr>')
|
|
if line.find('>Rbx</a>') != -1 and not bInDetail:
|
|
if lines[index - 1] != '<tr><td colspan="2"><br><h2>Data Fields For X64</h2></td></tr>':
|
|
lines.insert(index, '<tr><td colspan="2"><br><h2>Data Fields For X64</h2></td></tr>')
|
|
if line.find('>F2</a>') != -1 and not bInDetail:
|
|
if lines[index - 1] != '<tr><td colspan="2"><br><h2>Data Fields For IPF</h2></td></tr>':
|
|
lines.insert(index, '<tr><td colspan="2"><br><h2>Data Fields For IPF</h2></td></tr>')
|
|
if line.find('>Ebx</a>') != -1 and not bInDetail:
|
|
if lines[index - 1] != '<tr><td colspan="2"><br><h2>Data Fields For IA32</h2></td></tr>':
|
|
lines.insert(index, '<tr><td colspan="2"><br><h2>Data Fields For IA32</h2></td></tr>')
|
|
try:
|
|
f = open(path, 'w')
|
|
f.write('\n'.join(lines))
|
|
f.close()
|
|
except:
|
|
logging.getLogger().error(" <<< Fail to fixup file %s" % path)
|
|
return
|
|
print " <<< Finish to fixup file %s\n" % path
|
|
|
|
def FixPageUefiDriverEntryPoint(path, text):
|
|
print ' >>> Fixup file reference MdePkg/Include/Library/UefiDriverEntryPoint.h at file %s \n' % path
|
|
lines = text.split('\n')
|
|
bInModuleEntry = False
|
|
bInEfiMain = False
|
|
ModuleEntryDlCount = 0
|
|
ModuleEntryDelStart = 0
|
|
ModuleEntryDelEnd = 0
|
|
EfiMainDlCount = 0
|
|
EfiMainDelStart = 0
|
|
EfiMainDelEnd = 0
|
|
|
|
for index in range(len(lines)):
|
|
line = lines[index].strip()
|
|
if line.find('EFI_STATUS</a> EFIAPI _ModuleEntryPoint </td>') != -1:
|
|
bInModuleEntry = True
|
|
if line.find('EFI_STATUS</a> EFIAPI EfiMain </td>') != -1:
|
|
bInEfiMain = True
|
|
if line.startswith('<p>References <a'):
|
|
if bInModuleEntry:
|
|
ModuleEntryDelEnd = index - 1
|
|
bInModuleEntry = False
|
|
elif bInEfiMain:
|
|
EfiMainDelEnd = index - 1
|
|
bInEfiMain = False
|
|
if bInModuleEntry:
|
|
if line.startswith('</dl>'):
|
|
ModuleEntryDlCount = ModuleEntryDlCount + 1
|
|
if ModuleEntryDlCount == 1:
|
|
ModuleEntryDelStart = index + 1
|
|
if bInEfiMain:
|
|
if line.startswith('</dl>'):
|
|
EfiMainDlCount = EfiMainDlCount + 1
|
|
if EfiMainDlCount == 1:
|
|
EfiMainDelStart = index + 1
|
|
|
|
if EfiMainDelEnd > EfiMainDelStart:
|
|
for index in range(EfiMainDelEnd, EfiMainDelStart, -1):
|
|
del lines[index]
|
|
if ModuleEntryDelEnd > ModuleEntryDelStart:
|
|
for index in range(ModuleEntryDelEnd, ModuleEntryDelStart, -1):
|
|
del lines[index]
|
|
|
|
try:
|
|
f = open(path, 'w')
|
|
f.write('\n'.join(lines))
|
|
f.close()
|
|
except:
|
|
logging.getLogger().error(" <<< Fail to fixup file %s" % path)
|
|
return
|
|
print " <<< Finish to fixup file %s\n" % path
|
|
|
|
|
|
def FixPageUefiApplicationEntryPoint(path, text):
|
|
print ' >>> Fixup file reference MdePkg/Include/Library/UefiApplicationEntryPoint.h at file %s \n' % path
|
|
lines = text.split('\n')
|
|
bInModuleEntry = False
|
|
bInEfiMain = False
|
|
ModuleEntryDlCount = 0
|
|
ModuleEntryDelStart = 0
|
|
ModuleEntryDelEnd = 0
|
|
EfiMainDlCount = 0
|
|
EfiMainDelStart = 0
|
|
EfiMainDelEnd = 0
|
|
|
|
for index in range(len(lines)):
|
|
line = lines[index].strip()
|
|
if line.find('EFI_STATUS</a> EFIAPI _ModuleEntryPoint </td>') != -1:
|
|
bInModuleEntry = True
|
|
if line.find('EFI_STATUS</a> EFIAPI EfiMain </td>') != -1:
|
|
bInEfiMain = True
|
|
if line.startswith('<p>References <a'):
|
|
if bInModuleEntry:
|
|
ModuleEntryDelEnd = index - 1
|
|
bInModuleEntry = False
|
|
elif bInEfiMain:
|
|
EfiMainDelEnd = index - 1
|
|
bInEfiMain = False
|
|
if bInModuleEntry:
|
|
if line.startswith('</dl>'):
|
|
ModuleEntryDlCount = ModuleEntryDlCount + 1
|
|
if ModuleEntryDlCount == 1:
|
|
ModuleEntryDelStart = index + 1
|
|
if bInEfiMain:
|
|
if line.startswith('</dl>'):
|
|
EfiMainDlCount = EfiMainDlCount + 1
|
|
if EfiMainDlCount == 1:
|
|
EfiMainDelStart = index + 1
|
|
|
|
if EfiMainDelEnd > EfiMainDelStart:
|
|
for index in range(EfiMainDelEnd, EfiMainDelStart, -1):
|
|
del lines[index]
|
|
if ModuleEntryDelEnd > ModuleEntryDelStart:
|
|
for index in range(ModuleEntryDelEnd, ModuleEntryDelStart, -1):
|
|
del lines[index]
|
|
|
|
try:
|
|
f = open(path, 'w')
|
|
f.write('\n'.join(lines))
|
|
f.close()
|
|
except:
|
|
logging.getLogger().error(" <<< Fail to fixup file %s" % path)
|
|
return
|
|
print " <<< Finish to fixup file %s\n" % path
|
|
|
|
if __name__ == '__main__':
|
|
wspath, pkgpath, doxpath, outpath, archtag, docmode, isinc, hwpath = parseCmdArgs()
|
|
|
|
# configure logging system
|
|
logfilepath = os.path.join(outpath, 'log.txt')
|
|
logging.basicConfig(format='%(levelname)-8s %(message)s', level=logging.DEBUG)
|
|
|
|
# create package model object firstly
|
|
pkgObj = createPackageObject(wspath, pkgpath)
|
|
if pkgObj is None:
|
|
sys.exit(-1)
|
|
|
|
# create doxygen action model
|
|
arch = None
|
|
tooltag = None
|
|
if archtag.lower() != 'all':
|
|
arch = archtag.split('_')[0]
|
|
tooltag = archtag.split('_')[1]
|
|
else:
|
|
arch = 'all'
|
|
tooltag = 'all'
|
|
|
|
# preprocess package and call doxygen
|
|
try:
|
|
action = doxygengen.PackageDocumentAction(doxpath,
|
|
hwpath,
|
|
outpath,
|
|
pkgObj,
|
|
docmode,
|
|
callbackLogMessage,
|
|
arch,
|
|
tooltag,
|
|
isinc,
|
|
True)
|
|
action.RegisterCallbackDoxygenProcess(callbackCreateDoxygenProcess)
|
|
action.Generate()
|
|
except:
|
|
message = traceback.format_exception(*sys.exc_info())
|
|
logging.getLogger().error('Fail to create doxygen action! \n%s' % ''.join(message))
|
|
sys.exit(-1)
|
|
|
|
DocumentFixup(outpath, arch)
|
|
|
|
# generate CHM is necessary
|
|
if docmode.lower() == 'chm':
|
|
indexpath = os.path.join(outpath, 'html', 'index.hhp')
|
|
if sys.platform == 'win32':
|
|
cmd = '"%s" %s' % (hwpath, indexpath)
|
|
else:
|
|
cmd = '%s %s' % (hwpath, indexpath)
|
|
subprocess.call(cmd)
|
|
print '\nFinish to generate package document! Please open %s for review' % os.path.join(outpath, 'html', 'index.chm')
|
|
else:
|
|
print '\nFinish to generate package document! Please open %s for review' % os.path.join(outpath, 'html', 'index.html')
|