diff --git a/.gitignore b/.gitignore index d12bc21c..5f34a4ca 100644 --- a/.gitignore +++ b/.gitignore @@ -40,11 +40,14 @@ cpuid_tool/x32 cpuid_tool/x64 *.vcxproj.user build -docs +/docs .vscode raw.txt report.txt *__pycache__ +python/docs/_build +python/docs/doctrees +python/docs/html python/dist python/src/libcpuid/_libcpuid_cffi.* python/src/libcpuid/libcpuid.h diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 00000000..61e9458d --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,29 @@ +# Read the Docs configuration file + +version: 2 + +build: + os: ubuntu-22.04 + tools: + python: latest + apt_packages: + - autoconf + - libtool + - automake + jobs: + pre_install: + - libtoolize + - autoreconf --install + - mkdir ./install + - ./configure --prefix=`pwd`/install + - make + - make install + - pip install cffi + - python ./python/ffi_build_rtd.py ./libcpuid/libcpuid.h ./install + +sphinx: + configuration: python/docs/conf.py + +python: + install: + - requirements: python/docs/requirements.txt diff --git a/Readme.md b/Readme.md index d2f931c6..343e20cb 100644 --- a/Readme.md +++ b/Readme.md @@ -171,6 +171,13 @@ When no options are present, the program behaves as if it was invoked with cpuid_tool "--save=raw.txt --outfile=report.txt --report --verbose" ``` +### Python bindings + +The libcpuid library features Python bindings, which can be installed as a library +using `python -m pip install libcpuid`. Visit the +[documentation at Read the Docs](https://libcpuid.readthedocs.io/en/latest/index.html#) +to see how the library is used. + ## Contributing Refer to the [dedicated page](CONTRIBUTING.md). diff --git a/python/README.md b/python/README.md new file mode 100644 index 00000000..779d4183 --- /dev/null +++ b/python/README.md @@ -0,0 +1,8 @@ +# libcpuid + +libcpuid is a package that provides Python bindings to +the C library of the same name. Its main feature is +CPU identification for the x86 and ARM architectures. + +Visit the [documentation at Read the Docs](https://libcpuid.readthedocs.io/en/latest/index.html#) +to see how the library is used. diff --git a/python/docs/api/clock.rst b/python/docs/api/clock.rst new file mode 100644 index 00000000..939c1485 --- /dev/null +++ b/python/docs/api/clock.rst @@ -0,0 +1,6 @@ +Clock and frequency computation +=============================== + +.. automodule:: libcpuid.clock + :members: + :undoc-members: diff --git a/python/docs/api/enums.rst b/python/docs/api/enums.rst new file mode 100644 index 00000000..bb74ebae --- /dev/null +++ b/python/docs/api/enums.rst @@ -0,0 +1,6 @@ +Enumeration classes +=================== + +.. automodule:: libcpuid.enums + :members: + :undoc-members: diff --git a/python/docs/api/errors.rst b/python/docs/api/errors.rst new file mode 100644 index 00000000..c16d0599 --- /dev/null +++ b/python/docs/api/errors.rst @@ -0,0 +1,5 @@ +Library exceptions +================== + +.. automodule:: libcpuid.errors + :members: diff --git a/python/docs/api/info.rst b/python/docs/api/info.rst new file mode 100644 index 00000000..65ca6341 --- /dev/null +++ b/python/docs/api/info.rst @@ -0,0 +1,22 @@ +Basic CPU information +===================== + +.. autoclass:: libcpuid.info.CPUInfo + :members: + :exclude-members: from_c + +.. autoclass:: libcpuid.info.X86Info + :members: + +.. autoclass:: libcpuid.info.ARMInfo + :members: + +.. autoclass:: libcpuid.sgx.SGX + :members: + +.. autoclass:: libcpuid.sgx.EPC + :members: + +.. autoclass:: libcpuid.info.SystemInfo + :members: + :exclude-members: from_c diff --git a/python/docs/api/libcpuid.rst b/python/docs/api/libcpuid.rst new file mode 100644 index 00000000..ed7a9a5a --- /dev/null +++ b/python/docs/api/libcpuid.rst @@ -0,0 +1,5 @@ +Top-level library functionality +=============================== + +.. automodule:: libcpuid + :members: diff --git a/python/docs/api/msr.rst b/python/docs/api/msr.rst new file mode 100644 index 00000000..702e3f47 --- /dev/null +++ b/python/docs/api/msr.rst @@ -0,0 +1,6 @@ +Model-specific registers +======================== + +.. automodule:: libcpuid.msr + :members: + :undoc-members: diff --git a/python/docs/api/raw.rst b/python/docs/api/raw.rst new file mode 100644 index 00000000..158a64a8 --- /dev/null +++ b/python/docs/api/raw.rst @@ -0,0 +1,10 @@ +Raw CPU data +============ + +.. autoclass:: libcpuid.raw.CPURawData + :members: + :exclude-members: c_cpu_raw_data + +.. autoclass:: libcpuid.raw.CPURawDataArray + :members: + :exclude-members: c_cpu_raw_data_array \ No newline at end of file diff --git a/python/docs/conf.py b/python/docs/conf.py new file mode 100644 index 00000000..7956e61b --- /dev/null +++ b/python/docs/conf.py @@ -0,0 +1,35 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +import os +import sys + +sys.path.insert(0, os.path.abspath("../src")) + +project = "libcpuid" +copyright = "2024, Pavol Žáčik" +author = "Pavol Žáčik" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.doctest", + "sphinx_rtd_theme", +] + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +language = "en" + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "sphinx_rtd_theme" +autodoc_member_order = "bysource" diff --git a/python/docs/index.rst b/python/docs/index.rst new file mode 100644 index 00000000..69d3c464 --- /dev/null +++ b/python/docs/index.rst @@ -0,0 +1,51 @@ +Welcome to libcpuid's documentation! +==================================== + +**libcpuid** provides a Python interface +to the libcpuid C library. + +.. code-block:: python + + import sys + import libcpuid + from libcpuid.errors import LibcpuidError + from libcpuid.info import CPUInfo + from libcpuid.enums import CPUFeature, CPUVendor + + # print the version of the libcpuid library + print(libcpuid.version()) + + # print the number of CPU cores + print(libcpuid.get_total_cpus()) + + # check if the cpuid instruction is available + if not libcpuid.cpuid_present(): + print("CPUInfo instruction is not available") + sys.exit(1) + + try: + # identify the current CPU and print some + # information about it + cpu_info = CPUInfo.from_current_cpu() + print(cpu_info.vendor) + print(cpu_info.architecture) + print(CPUFeature.FPU in cpu_info.features) + + # print the list of all Intel CPU code names + print(libcpuid.get_cpu_list(CPUVendor.INTEL)) + except LibcpuidError as err: + print(err.message) + sys.exit(1) + + +.. toctree:: + :maxdepth: 2 + + Home + api/libcpuid + api/info + api/msr + api/enums + api/raw + api/clock + api/errors diff --git a/python/docs/requirements.txt b/python/docs/requirements.txt new file mode 100644 index 00000000..6c5d5d44 --- /dev/null +++ b/python/docs/requirements.txt @@ -0,0 +1 @@ +sphinx-rtd-theme diff --git a/python/ffi_build_rtd.py b/python/ffi_build_rtd.py new file mode 100644 index 00000000..10b88359 --- /dev/null +++ b/python/ffi_build_rtd.py @@ -0,0 +1,26 @@ +""" +Script for compiling the C FFI for the live documentation. +""" + +import subprocess +import sys +import os +from cffi import FFI + +if __name__ == "__main__": + header = sys.argv[1] + install_dir = sys.argv[2] + library_dir = os.path.join(os.getcwd(), install_dir, "lib") + ffibuilder = FFI() + ffibuilder.cdef( + subprocess.check_output(["gcc", "-U __GNUC__", "-E", header]).decode() + ) + ffibuilder.set_source( + "python.src.libcpuid._libcpuid_cffi", + "#include ", + libraries=["cpuid"], + library_dirs=[library_dir], + include_dirs=[os.path.join(install_dir, "include", "libcpuid")], + extra_link_args=[f"-Wl,-rpath={library_dir}"], + ) + ffibuilder.compile(verbose=True)