siwisdk framework for siwi gsm modules

Initial commit

Signed-off-by: Ajay Bhargav <[email protected]>

Author: ajaybhargav

.gitattributes

@@ -0,0 +1 @@
+*.bat eol=crlf

.gitignore

@@ -0,0 +1,5 @@
+docs/_build
+docs/xml
+docs/inc
+__pycache__/
+.vscode/

README.md

@@ -0,0 +1,3 @@
+# SIWISDK
+
+Software development kit for SIWI GSM modules

docs/Doxyfile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/Makefile

@@ -0,0 +1,265 @@
+#file modified from esp-idf extension
+import os
+import os.path
+import re
+import subprocess
+#from util import copy_if_modified
+
+ALL_KINDS = [
+    ("function", "Functions"),
+    ("union", "Unions"),
+    ("struct", "Structures"),
+    ("define", "Macros"),
+    ("typedef", "Type Definitions"),
+    ("enum", "Enumerations")
+]
+"""list of items that will be generated for a single API file
+"""
+
+def setup(app):
+	app.connect('builder-inited', run_doxygen)
+	return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '1.0'}
+
+def run_doxygen(app):
+	print("Running doxygen with Doxyfile")
+	# note: run Doxygen in the build directory, so the xml & xml_in files end up in there
+	subprocess.check_call(["doxygen", "Doxyfile"])
+	# Generate 'api_name.inc' files from the Doxygen XML files
+	convert_api_xml_to_inc(app, "Doxyfile")
+
+def convert_api_xml_to_inc(app, doxyfile):
+    """ Generate header_file.inc files
+    with API reference made of doxygen directives
+    for each header file
+    specified in the 'INPUT' statement of the Doxyfile.
+    """
+
+    xml_directory_path = "xml"
+    inc_directory_path = "inc"
+
+    if not os.path.isdir(xml_directory_path):
+        raise RuntimeError("Directory {} does not exist!".format(xml_directory_path))
+
+    if not os.path.exists(inc_directory_path):
+        os.makedirs(inc_directory_path)
+
+    header_paths = get_doxyfile_input_paths(app, doxyfile)
+    print("Generating 'api_name.inc' files with Doxygen directives")
+    for header_file_path in header_paths:
+        api_name = get_api_name(header_file_path)
+        inc_file_path = inc_directory_path + "/" + api_name + ".inc"
+        rst_output = generate_directives(header_file_path, xml_directory_path)
+
+        previous_rst_output = ''
+        if os.path.isfile(inc_file_path):
+            with open(inc_file_path, "r", encoding='utf-8') as inc_file_old:
+                previous_rst_output = inc_file_old.read()
+
+        if previous_rst_output != rst_output:
+            with open(inc_file_path, "w", encoding='utf-8') as inc_file:
+                inc_file.write(rst_output)
+
+
+def get_doxyfile_input_paths(app, doxyfile_path):
+    """Get contents of Doxyfile's INPUT statement.
+
+    Returns:
+        Contents of Doxyfile's INPUT.
+
+    """
+    if not os.path.isfile(doxyfile_path):
+        raise RuntimeError("Doxyfile '{}' does not exist!".format(doxyfile_path))
+
+    print("Getting Doxyfile's INPUT")
+
+    with open(doxyfile_path, "r", encoding='utf-8') as input_file:
+        line = input_file.readline()
+        # read contents of Doxyfile until 'INPUT' statement
+        while line:
+            if line.find("INPUT") == 0:
+                break
+            line = input_file.readline()
+
+        doxyfile_INPUT = []
+        line = input_file.readline()
+        # skip input_file contents until end of 'INPUT' statement
+        while line:
+            if line.isspace():
+                # we have reached the end of 'INPUT' statement
+                break
+            # process only lines that are not comments
+            if line.find("#") == -1:
+                # extract header file path inside components folder
+                m = re.search("include/(.*\.h)", line)  # noqa: W605 - regular expression
+                header_file_path = m.group(0)
+
+                doxyfile_INPUT.append(header_file_path)
+
+            # proceed reading next line
+            line = input_file.readline()
+
+    return doxyfile_INPUT
+
+
+def get_api_name(header_file_path):
+    """Get name of API from header file path.
+
+    Args:
+        header_file_path: path to the header file.
+
+    Returns:
+        The name of API.
+
+    """
+    api_name = ""
+    regex = r".*/(.*)\.h"
+    m = re.search(regex, header_file_path)
+    if m:
+        api_name = m.group(1)
+
+    return api_name
+
+
+def generate_directives(header_file_path, xml_directory_path):
+    """Generate API reference with Doxygen directives for a header file.
+
+    Args:
+        header_file_path: a path to the header file with API.
+
+    Returns:
+        Doxygen directives for the header file.
+
+    """
+
+    api_name = get_api_name(header_file_path)
+
+    # in XLT file name each "_" in the api name is expanded by Doxygen to "__"
+    xlt_api_name = api_name.replace("_", "__")
+    xml_file_path = "%s/%s_8h.xml" % (xml_directory_path, xlt_api_name)
+
+    rst_output = ""
+    rst_output = ".. File automatically generated by 'gen-dxd.py'\n"
+    rst_output += "\n"
+    rst_output += get_rst_header("Header File")
+    rst_output += "* :header_src_file:`" + header_file_path + "`\n"
+    rst_output += "\n"
+
+    try:
+        import xml.etree.cElementTree as ET
+    except ImportError:
+        import xml.etree.ElementTree as ET
+
+    tree = ET.ElementTree(file=xml_file_path)
+    for kind, label in ALL_KINDS:
+        rst_output += get_directives(tree, kind)
+
+    return rst_output
+
+
+def get_rst_header(header_name):
+    """Get rst formatted code with a header.
+
+    Args:
+        header_name: name of header.
+
+    Returns:
+        Formatted rst code with the header.
+
+    """
+
+    rst_output = ""
+    rst_output += header_name + "\n"
+    rst_output += "^" * len(header_name) + "\n"
+    rst_output += "\n"
+
+    return rst_output
+
+
+def select_unions(innerclass_list):
+    """Select unions from innerclass list.
+
+    Args:
+        innerclass_list: raw list with unions and structures
+                         extracted from Dogygen's xml file.
+
+    Returns:
+        Doxygen directives with unions selected from the list.
+
+    """
+
+    rst_output = ""
+    for line in innerclass_list.splitlines():
+        # union is denoted by "union" at the beginning of line
+        if line.find("union") == 0:
+            union_id, union_name = re.split(r"\t+", line)
+            rst_output += ".. doxygenunion:: "
+            rst_output += union_name
+            rst_output += "\n"
+
+    return rst_output
+
+
+def select_structs(innerclass_list):
+    """Select structures from innerclass list.
+
+    Args:
+        innerclass_list: raw list with unions and structures
+                         extracted from Dogygen's xml file.
+
+    Returns:
+        Doxygen directives with structures selected from the list.
+        Note: some structures are excluded as described on code below.
+
+    """
+
+    rst_output = ""
+    for line in innerclass_list.splitlines():
+        # structure is denoted by "struct" at the beginning of line
+        if line.find("struct") == 0:
+            # skip structures that are part of union
+            # they are documented by 'doxygenunion' directive
+            if line.find("::") > 0:
+                continue
+            struct_id, struct_name = re.split(r"\t+", line)
+            rst_output += ".. doxygenstruct:: "
+            rst_output += struct_name
+            rst_output += "\n"
+            rst_output += "    :members:\n"
+            rst_output += "\n"
+
+    return rst_output
+
+
+def get_directives(tree, kind):
+    """Get directives for specific 'kind'.
+
+    Args:
+        tree: the ElementTree 'tree' of XML by Doxygen
+        kind: name of API "kind" to be generated
+
+    Returns:
+        Doxygen directives for selected 'kind'.
+        Note: the header with "kind" name is included.
+
+    """
+
+    rst_output = ""
+    if kind in ["union", "struct"]:
+        innerclass_list = ""
+        for elem in tree.iterfind('compounddef/innerclass'):
+            innerclass_list += elem.attrib["refid"] + "\t" + elem.text + "\n"
+        if kind == "union":
+            rst_output += select_unions(innerclass_list)
+        else:
+            rst_output += select_structs(innerclass_list)
+    else:
+        for elem in tree.iterfind(
+                'compounddef/sectiondef/memberdef[@kind="%s"]' % kind):
+            name = elem.find('name')
+            rst_output += ".. doxygen%s:: " % kind
+            rst_output += name.text + "\n"
+    if rst_output:
+        all_kinds_dict = dict(ALL_KINDS)
+        rst_output = get_rst_header(all_kinds_dict[kind]) + rst_output + "\n"
+
+    return rst_output

docs/_ext/gen_include.py

@@ -0,0 +1,34 @@
+#based on https://protips.readthedocs.io/link-roles.html
+#some part taken from esp-idf extension link-roles.py
+
+import os
+import subprocess
+from docutils import nodes
+
+def get_github_rev():
+    try:
+        path = subprocess.check_output(['git', 'rev-parse', '--short', 'HEAD']).strip().decode('utf-8')
+        try:
+            tag = subprocess.check_output(['git', 'describe', '--exact-match']).strip().decode('utf-8')
+        except subprocess.CalledProcessError:
+            tag = None
+        print('Git commit ID: ', path)
+        if tag:
+            print('Git tag: ', tag)
+            return tag
+    except subprocess.CalledProcessError:
+        path = "test"
+    return path
+
+def setup(app):
+    app.add_role('github', autolink('https://github.com/%s'))
+    app.add_role('header_src_file', autolink('https://github.com/ajaybhargav/siwisdk/blob/%s/%s'))
+    return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '1.0'}
+
+def autolink(pattern):
+    def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+        rev = get_github_rev()
+        url = pattern % (rev,text,)
+        node = nodes.reference(rawtext, text, refuri=url, **options)
+        return [node], []
+    return role

docs/_ext/link_roles.py

@@ -0,0 +1,2 @@
+AES Encryption API
+==================