mirror of
https://github.com/acidanthera/audk.git
synced 2025-04-08 17:05:09 +02:00
1ccc4d895d
This reverts commit 6693f359b3c213513c5096a06c6f67244a44dc52.. 678f85131238622e576705117e299d81cff755c9. Python3 migration is the fundamental change. It requires every developer to install Python3. Before this migration, the well communication and wide verification must be done. But now, most people is not aware of this change, and not try it. So, Python3 migration is reverted and be moved to edk2-staging Python3 branch for the edk2 user evaluation. Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Liming Gao <liming.gao@intel.com>
431 lines
21 KiB
Python
431 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.
|
|
#
|
|
|
|
from __future__ import print_function
|
|
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'))
|