Xscope FileIO
=============
This library allows a program on the xCore to access binary files on the host machine
via xscope.
Features:
#. Read and write binary files on the host machine from the xCore.
#. “wb” or “rb” file access mode only
#. 6-8MBytes/s Device to Host speed (compared to 2kBytes/s for standard fielio).
#. Up to 1MBytes/s Host to Device speed.
Installation
************
Xscope fileio module consist of two parts:
#. A python module: launches the device application and simultaneously launches the host application to communicate xscope data to/from.
#. A host application: an executable that runs on the host machine and communicates with the device application.
To install the xscope fileio python module, simply run:
.. code-block:: console
pip install .
For Linux and Mac, the host application is installed alongside the python module.
For Windows, you will have to build the host application yourself.
For more information for building the host app in windows see
`host/README <./host/README.rst>`_.
Host side API
-------------
The host-side interface is written in Python. To run an xcore binary with access to
xscope fileIO,
use:
.. code-block:: python
import xscope_fileio
.. code-block:: python
xscope_fileio.run_on_target(adapter_id, firmware_xe, use_xsim=False)
This can be combined with xtagctl e.g.:
.. code-block:: python
with xtagctl.acquire("XCORE-AI-EXPLORER") as adapter_id:
xscope_fileio.run_on_target(adapter_id, device_xe)
Device side API
---------------
Source and header files for device code are found in the ``xscope_fileio`` directory.
The device side application requires a multi-tile main since it uses the xscope_host_data(xscope_chan); service
to communicate with the host, which requires this. See examples for XC and C applications for how to do this.
You will also need a copy of ``config.xscope`` in your firmware directory. This
enables xscope in the tools and sets up the xscope probes used by fileio for communicating with the host app. You
can find a copy in ``xscope_fileio/config.xscope xscope_fileio/config.xscope.txt`` which you should rename to ``config.xscope``.
.. note::
Note currently missing from fileio api: ``fprintf`` , ``fscanf``
System Architecture
-------------------
The ``run_on_target`` function calls ``xrun --xscope-port`` with the binary and specified target adapter,
and simultaneously launches a host application to communicate xscope data to/from
the xrun process via sockets. The host application responds to ``xscope_fileio`` API calls
in the firmware code, reading/writing to the host file system.
The call to ``run_on_target`` returns when the firmware exits.
.. image:: doc/imgs/arch.png
:alt: System Architecture
Raw data
{
"_id": null,
"home_page": "https://github.com/xmos/xscope_fileio",
"name": "xscope-fileio",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "XMOS",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/04/f9/2fe0a7c3b01979d697a55c6a06c24536d9dd70d34cfc9267d5a8acab4dfd/xscope_fileio-1.3.0.tar.gz",
"platform": null,
"description": "Xscope FileIO\n=============\n\nThis library allows a program on the xCore to access binary files on the host machine\nvia xscope. \n\nFeatures:\n\n#. Read and write binary files on the host machine from the xCore.\n#. \u201cwb\u201d or \u201crb\u201d file access mode only\n#. 6-8MBytes/s Device to Host speed (compared to 2kBytes/s for standard fielio).\n#. Up to 1MBytes/s Host to Device speed.\n\nInstallation\n************\n\nXscope fileio module consist of two parts: \n\n#. A python module: launches the device application and simultaneously launches the host application to communicate xscope data to/from.\n#. A host application: an executable that runs on the host machine and communicates with the device application.\n\nTo install the xscope fileio python module, simply run:\n\n.. code-block:: console\n \n pip install .\n\nFor Linux and Mac, the host application is installed alongside the python module. \nFor Windows, you will have to build the host application yourself. \nFor more information for building the host app in windows see \n`host/README <./host/README.rst>`_.\n\n\nHost side API\n-------------\n\nThe host-side interface is written in Python. To run an xcore binary with access to\nxscope fileIO,\nuse:\n\n.. code-block:: python\n\n import xscope_fileio\n\n.. code-block:: python\n\n xscope_fileio.run_on_target(adapter_id, firmware_xe, use_xsim=False)\n\nThis can be combined with xtagctl e.g.:\n\n.. code-block:: python\n\n with xtagctl.acquire(\"XCORE-AI-EXPLORER\") as adapter_id:\n xscope_fileio.run_on_target(adapter_id, device_xe)\n\n\nDevice side API\n---------------\n\nSource and header files for device code are found in the ``xscope_fileio`` directory.\n\nThe device side application requires a multi-tile main since it uses the xscope_host_data(xscope_chan); service\nto communicate with the host, which requires this. See examples for XC and C applications for how to do this.\n\nYou will also need a copy of ``config.xscope`` in your firmware directory. This\nenables xscope in the tools and sets up the xscope probes used by fileio for communicating with the host app. You\ncan find a copy in ``xscope_fileio/config.xscope xscope_fileio/config.xscope.txt`` which you should rename to ``config.xscope``.\n\n.. note::\n\n Note currently missing from fileio api: ``fprintf`` , ``fscanf``\n\nSystem Architecture\n-------------------\n\nThe ``run_on_target`` function calls ``xrun --xscope-port`` with the binary and specified target adapter,\nand simultaneously launches a host application to communicate xscope data to/from\nthe xrun process via sockets. The host application responds to ``xscope_fileio`` API calls\nin the firmware code, reading/writing to the host file system.\n\nThe call to ``run_on_target`` returns when the firmware exits.\n\n.. image:: doc/imgs/arch.png\n :alt: System Architecture\n",
"bugtrack_url": null,
"license": "LICENSE.rst",
"summary": "Python module for managing files using xscope",
"version": "1.3.0",
"project_urls": {
"Homepage": "https://github.com/xmos/xscope_fileio"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1223422af5eee961632706541983f1d986a0b52698d6ae4f45b0e1954972adb1",
"md5": "5bc8f510c9d1285814b0f24db38eb336",
"sha256": "c7bbaaf3e9e2e03b93fcd4b8825e87ce3c7f45f7f7c9049d6cc1bb0d4bd4355e"
},
"downloads": -1,
"filename": "xscope_fileio-1.3.0-cp310-cp310-manylinux_2_35_x86_64.whl",
"has_sig": false,
"md5_digest": "5bc8f510c9d1285814b0f24db38eb336",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": "<3.12,>=3.10",
"size": 24216,
"upload_time": "2024-11-21T16:14:51",
"upload_time_iso_8601": "2024-11-21T16:14:51.578572Z",
"url": "https://files.pythonhosted.org/packages/12/23/422af5eee961632706541983f1d986a0b52698d6ae4f45b0e1954972adb1/xscope_fileio-1.3.0-cp310-cp310-manylinux_2_35_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8d1527e1927b9944525f06c047f354ce5978a239236c866ab6943ec7a85a767e",
"md5": "ff09c04268d017c1b3cf6d21486195d3",
"sha256": "e333c8154485787203c9f0cba2e760f71dc0033262acfd82bf7fc29ca0bc82fe"
},
"downloads": -1,
"filename": "xscope_fileio-1.3.0-cp310-cp310-win_amd64.whl",
"has_sig": false,
"md5_digest": "ff09c04268d017c1b3cf6d21486195d3",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": "<3.12,>=3.10",
"size": 25180,
"upload_time": "2024-11-21T15:34:31",
"upload_time_iso_8601": "2024-11-21T15:34:31.908244Z",
"url": "https://files.pythonhosted.org/packages/8d/15/27e1927b9944525f06c047f354ce5978a239236c866ab6943ec7a85a767e/xscope_fileio-1.3.0-cp310-cp310-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "04f92fe0a7c3b01979d697a55c6a06c24536d9dd70d34cfc9267d5a8acab4dfd",
"md5": "e685bbffb7ecbf6d0a0db9dac2d7c693",
"sha256": "19ffdd8a22eac0158c8c02666557db2ea98a9737c575f99b526513931315bf37"
},
"downloads": -1,
"filename": "xscope_fileio-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "e685bbffb7ecbf6d0a0db9dac2d7c693",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.10",
"size": 23030,
"upload_time": "2024-11-21T15:34:34",
"upload_time_iso_8601": "2024-11-21T15:34:34.105563Z",
"url": "https://files.pythonhosted.org/packages/04/f9/2fe0a7c3b01979d697a55c6a06c24536d9dd70d34cfc9267d5a8acab4dfd/xscope_fileio-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-21 15:34:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xmos",
"github_project": "xscope_fileio",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "xscope-fileio"
}
JSON
