|
| 1 | +Python Bindings |
| 2 | +=============== |
| 3 | + |
| 4 | +These bindings exist to provide Python interfaces to the FPGA on AWS F2 |
| 5 | +EC2 Instances, allowing developers to control and interact with FPGAs |
| 6 | +using Python instead of C code directly. |
| 7 | + |
| 8 | +Cython Overview |
| 9 | +--------------- |
| 10 | + |
| 11 | +A typical Cython binding setup creates a bridge between Python and C |
| 12 | +code through a specific file structure: the ``.pxd`` file declares the |
| 13 | +external C functions and types (similar to a C header file), while the |
| 14 | +``.pyx`` file implements the actual Python-facing wrappers around these |
| 15 | +C functions, handling type conversions and memory management. |
| 16 | + |
| 17 | +When compiled, Cython transforms the ``.pyx`` file into C code, which is |
| 18 | +then built into a shared object (``.so``) file that Python can import |
| 19 | +directly as a module, allowing Python code to seamlessly call C |
| 20 | +functions while maintaining Python's ease of use but with C's |
| 21 | +performance benefits. |
| 22 | + |
| 23 | +Setup |
| 24 | +----- |
| 25 | + |
| 26 | +How to Build Bindings |
| 27 | +~~~~~~~~~~~~~~~~~~~~~ |
| 28 | + |
| 29 | +.. code:: bash |
| 30 | +
|
| 31 | + git clone https://github.com/aws/aws-fpga.git |
| 32 | + cd aws-fpga |
| 33 | + source sdk_setup.sh |
| 34 | +
|
| 35 | +This process will generate the necessary ``*_wrapper.c`` files that |
| 36 | +enable Python-to-C communication. |
| 37 | + |
| 38 | +Instructions to run examples |
| 39 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 40 | + |
| 41 | +Navigate to the ``aws-fpga/sdk/userspace/cython_bindings`` directory |
| 42 | + |
| 43 | +.. code:: bash |
| 44 | +
|
| 45 | + sudo python3 fpga_mgmt_example.py |
| 46 | + sudo python3 fpga_clkgen_example.py |
| 47 | + sudo python3 fpga_pci_example.py |
| 48 | +
|
| 49 | +Troubleshooting |
| 50 | +--------------- |
| 51 | + |
| 52 | +- FPGA Unresponsive: Run Python scripts with sudo privileges |
| 53 | +- Library not found: Verify AWS FPGA SDK installation is complete and |
| 54 | + sourced |
| 55 | +- Invalid slot ID: Verify slot number is valid for instance type |
| 56 | +- AFI load timeout: Check AFI ID and instance permissions, and ensure |
| 57 | + sufficient time after async FPGA clears and loads |
| 58 | +- Debug: Enable verbose logging by setting logging.INFO in ``utils.py`` |
| 59 | +- Supported Python Versions: Bindings can be used by all Python versions |
| 60 | + supported by Cython |
| 61 | +- How do I find my instance type during runtime: `Instance Meta Data |
| 62 | + Documentation <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html#instance-metadata-retrieval-examples>`__ |
| 63 | + |
| 64 | +FPGA Management Library Functions |
| 65 | +--------------------------------- |
| 66 | + |
| 67 | +These are the core functions that provide direct interaction with AWS F2 |
| 68 | +FPGA instances. The primary functions include FPGA slot initialization, |
| 69 | +image loading/clearing, status checking, and metric gathering. These |
| 70 | +functions form the API layer between Python applications and the |
| 71 | +low-level FPGA hardware management, allowing developers to control FPGA |
| 72 | +resources without dealing directly with the hardware registers or |
| 73 | +low-level C interfaces. |
| 74 | + |
| 75 | +- ``load_local_image(self, slot_id: int, afi_id: str) -> dict`` |
| 76 | +- ``clear_local_image(self, slot_id: int) -> dict`` |
| 77 | +- ``describe_local_image(self, slot_id: int, flags: uint32_t) -> dict`` |
| 78 | +- ``strerror(error: int) -> str`` |
| 79 | +- ``strerror_long(err: int) -> str`` |
| 80 | +- ``get_status_name(status: int) -> str`` |
| 81 | +- ``get_status(self, slot_id: int) -> dict`` |
| 82 | +- ``set_cmd_timeout(self, value: uint32_t) -> None`` |
| 83 | +- ``set_cmd_delay_msec(self, value: uint32_t) -> None`` |
| 84 | +- ``get_vLED_status(self, slot_id: int) -> uint16_t`` |
| 85 | +- ``set_vDIP(self, slot_id: int, value: uint16_t) -> None`` |
| 86 | +- ``get_vDIP_status(self, slot_id: int) -> uint16_t`` |
| 87 | +- ``clear_local_image_sync(self, slot_id: int, timeout: uint32_t, delay_msec: uint32_t) -> dict`` |
| 88 | +- ``load_local_image_flags(self, slot_id: int, afi_id: str, flags: uint32_t) -> dict`` |
| 89 | +- ``load_local_image_sync_flags(self, slot_id: int, afi_id: str, flags: uint32_t, timeout: uint32_t, delay_msec: uint32_t) -> dict`` |
| 90 | + |
| 91 | +FPGA Clock Generation Library Functions |
| 92 | +--------------------------------------- |
| 93 | + |
| 94 | +The Clock Generation Library provide essential clock management |
| 95 | +capabilities for AWS FPGA instances, allowing precise control over clock |
| 96 | +frequencies and configurations. The primary functions include retrieving |
| 97 | +current clock settings, applying predefined clock recipes, and |
| 98 | +dynamically adjusting frequencies across multiple clock domains (A, B, |
| 99 | +C, and HBM). These functions form the API layer between Python |
| 100 | +applications and the low-level clock management system, allowing |
| 101 | +developers to precisely control FPGA clock resources without directly |
| 102 | +manipulating hardware registers. More information on clock generation |
| 103 | +functions are available in the |
| 104 | +`Clock Recipes User Guide <../../../hdk/docs/Clock-Recipes-User-Guide.html>`__ |
| 105 | +document. |
| 106 | + |
| 107 | +- ``get_dynamic(self, slot_id: int) -> str`` |
| 108 | +- ``set_recipe(self, slot_id: int, clk_a_recipe: uint32_t, clk_b_recipe: uint32_t, clk_c_recipe: uint32_t, clk_hbm_recipe: uint32_t, reset: uint32_t) -> None`` |
| 109 | +- ``set_dynamic(self, slot_id: int, clk_a_freq: uint32_t, clk_b_freq: uint32_t, clk_c_freq: uint32_t, clk_hbm_freq: uint32_t, reset: uint32_t) -> None`` |
| 110 | + |
| 111 | +FPGA PCI Library Functions |
| 112 | +-------------------------- |
| 113 | + |
| 114 | +The FPGA PCI library provides a comprehensive set of functions for |
| 115 | +managing and interacting with the PCI bus on AWS FPGA instances. The |
| 116 | +library starts with initialization to set up the PCI management |
| 117 | +interface, and ``pci_attach()``/``pci_detach()`` to establish and |
| 118 | +terminate connections to specific PCI Base Address Registers (BARs). |
| 119 | +These functions form the basis for accessing PCI-mapped hardware |
| 120 | +resources. |
| 121 | + |
| 122 | +- ``pci_attach(self, slot_id: int, pf_id: int, bar_id: int, flags: uint32_t) -> pci_bar_handle_t`` |
| 123 | +- ``pci_detach(self, handle: pci_bar_handle_t) -> None`` |
| 124 | +- ``pci_poke(self, handle: pci_bar_handle_t, offset: uint64_t, value: uint32_t) -> None`` |
| 125 | +- ``pci_poke8(self, handle: pci_bar_handle_t, offset: uint64_t, value: uint8_t) -> None`` |
| 126 | +- ``pci_poke64(self, handle: pci_bar_handle_t, offset: uint64_t, value: uint64_t) -> None`` |
| 127 | +- ``pci_write_burst(self, handle: pci_bar_handle_t, offset: uint64_t, data: List[int], dword_len: uint64_t) -> None`` |
| 128 | +- ``pci_peek(self, handle: pci_bar_handle_t, offset: uint64_t) -> uint32_t`` |
| 129 | +- ``pci_peek8(self, handle: pci_bar_handle_t, offset: uint64_t) -> uint8_t`` |
| 130 | +- ``pci_peek64(self, handle: pci_bar_handle_t, offset: uint64_t) -> uint64_t`` |
| 131 | +- ``pci_get_slot_spec(self, slot_id: int) -> fpga_slot_spec`` |
| 132 | +- ``pci_get_all_slot_specs(self, size: int) -> List[fpga_slot_spec]`` |
| 133 | +- ``pci_get_resource_map(self, slot_id: int, pf_id: int) -> fpga_pci_resource_map`` |
| 134 | +- ``pci_rescan_slot_app_pfs(self, slot_id: int) -> None`` |
| 135 | +- ``pci_get_address(self, handle: pci_bar_handle_t, offset: uint64_t, dword_len: uint64_t) -> uintptr_t`` |
| 136 | +- ``pci_memset(self, handle: pci_bar_handle_t, offset: uint64_t, value: uint32_t, dword_len: uint64_t) -> None`` |
0 commit comments