aws · rcko-aws · Jul 17, 2025 · Jul 16, 2025
diff --git a/.gitignore b/.gitignore
@@ -24,7 +24,9 @@ waves.shm
 *.order
 *.symvers
 .vscode/
-
+venv
+*_wrapper.c
+fpga_utils.c
 *~
 .\#*
 \#*

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -1,5 +1,14 @@
 # F2 Developer Kit Release Notes
 
+## v2.1.2
+
+* Introduced Python Bindings to the SDK
+* Added [documentation](./sdk/userspace/cython_bindings/README.md) for Python binding usage and setup
+* [Examples](./sdk/userspace/cython_bindings/) demonstrating Python-based FPGA control
+* Added link to instructions for DCV licensing setup. Credit to @morgnza for this update!
+* Added verbiage to DCV setup guide to show where to set virtual display resolution
+* Fix to Bandwidth Calculation
+
 ## v2.1.1
 
 * Added global register offset for the SDE IP. See [CL_SDE software examples](./hdk/cl/examples/cl_sde/software/src/README.md).

diff --git a/developer_resources/Amazon_DCV_Setup_Guide.md b/developer_resources/Amazon_DCV_Setup_Guide.md
@@ -31,10 +31,11 @@ graphical user interface (GUI) to visualize FPGA development in the cloud.
 
 ### Prerequisites
 
-1. [Depenency Installation](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux-prereq.html#linux-prereq-gui)
-    * :warning: DO NOT PERFORM STEP 3! Upgrading may impact the stability of development kit software!
-2. [Protocol Setup](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux-prereq.html#linux-prereq-wayland)
-3. [Driver Installation](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux-prereq.html#linux-prereq-nongpu)
+1. [Instance and IAM Configuration for DCV Licensing](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-license.html#dcv-lic-req)
+2. [Depenency Installation](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux-prereq.html#linux-prereq-gui)
+    - :warning: DO NOT PERFORM STEP 3! Upgrading may impact the stability of development kit software!
+3. [Protocol Setup](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux-prereq.html#linux-prereq-wayland)
+4. [Driver Installation and Setting Virtual Display Resolution](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux-prereq.html#linux-prereq-nongpu)
 
 ### Amazon DCV Server Installation
 

diff --git a/docs-rtd/source/RELEASE-NOTES.rst b/docs-rtd/source/RELEASE-NOTES.rst
@@ -1,6 +1,18 @@
 F2 Developer Kit Release Notes
 ==============================
 
+.. _v212:
+
+v2.1.2
+------
+
+- Introduced Python Bindings to the SDK
+- Added `documentation <./sdk/userspace/cython-bindings/README.html>` for Python binding usage and setup
+- `Examples <https://github.com/aws/aws-fpga/blob/f2/sdk/userspace/cython_bindings>` demonstrating Python-based FPGA control
+- Added link to instructions for DCV licensing setup. Credit to @morgnza for this update!
+- Added verbiage to DCV setup guide to show where to set virtual display resolution
+- Fix to Bandwidth Calculation
+
 .. _v211:
 
 v2.1.1

diff --git a/docs-rtd/source/developer-resources/Amazon-DCV-Setup-Guide.rst b/docs-rtd/source/developer-resources/Amazon-DCV-Setup-Guide.rst
@@ -49,16 +49,17 @@ Installing the Amazon DCV Server on an Amazon EC2 Instance
 Prerequisites
 ~~~~~~~~~~~~~
 
-1. `Depenency
+1. `Instance and IAM Configuration for DCV Licensing <https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-license.html#dcv-lic-req>`__
+2. `Depenency
    Installation <https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux-prereq.html#linux-prereq-gui>`__
 
    - ⚠️ DO NOT PERFORM STEP 3! Upgrading may impact the stability of
      development kit software!
 
-2. `Protocol
+3. `Protocol
    Setup <https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux-prereq.html#linux-prereq-wayland>`__
-3. `Driver
-   Installation <https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux-prereq.html#linux-prereq-nongpu>`__
+4. `Driver
+   Installation and Setting Virtual Display Resolution <https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux-prereq.html#linux-prereq-nongpu>`__
 
 Amazon DCV Server Installation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -151,9 +152,6 @@ Checks <#post-installation-checks>`__ in the ``Password`` box and click
 At this point, you should see your session begin and a virtual desktop
 displayed after a brief delay.
 
-Any popups about not having a license may be safely ignored. This is a
-known issue with DCV.
-
 Now, open a terminal and run the following command:
 ``source /etc/profile.d/default_module.sh``. You're now ready to use
 your GUI-enabled EC2 Instance.

diff --git a/docs-rtd/source/sdk/README.rst b/docs-rtd/source/sdk/README.rst
@@ -74,6 +74,8 @@ Additional SDK Documentation
 
    userspace/fpga_mgmt_examples/README
 
+   userspace/cython-bindings/README
+
    userspace/fpga_mgmt_tools/README
    docs/F2-Software-Performance-Optimization-Guide
    docs/Load-Times

diff --git a/docs-rtd/source/sdk/userspace/cython-bindings/README.rst b/docs-rtd/source/sdk/userspace/cython-bindings/README.rst
@@ -0,0 +1,136 @@
+Python Bindings
+===============
+
+These bindings exist to provide Python interfaces to the FPGA on AWS F2 
+EC2 Instances, allowing developers to control and interact with FPGAs 
+using Python instead of C code directly.
+
+Cython Overview
+---------------
+
+A typical Cython binding setup creates a bridge between Python and C
+code through a specific file structure: the ``.pxd`` file declares the
+external C functions and types (similar to a C header file), while the
+``.pyx`` file implements the actual Python-facing wrappers around these
+C functions, handling type conversions and memory management.
+
+When compiled, Cython transforms the ``.pyx`` file into C code, which is
+then built into a shared object (``.so``) file that Python can import
+directly as a module, allowing Python code to seamlessly call C
+functions while maintaining Python's ease of use but with C's
+performance benefits.
+
+Setup
+-----
+
+How to Build Bindings
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: bash
+
+   git clone https://github.com/aws/aws-fpga.git
+   cd aws-fpga
+   source sdk_setup.sh
+
+This process will generate the necessary ``*_wrapper.c`` files that
+enable Python-to-C communication.
+
+Instructions to run examples
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Navigate to the ``aws-fpga/sdk/userspace/cython_bindings`` directory
+
+.. code:: bash
+
+   sudo python3 fpga_mgmt_example.py
+   sudo python3 fpga_clkgen_example.py
+   sudo python3 fpga_pci_example.py
+
+Troubleshooting
+---------------
+
+- FPGA Unresponsive: Run Python scripts with sudo privileges
+- Library not found: Verify AWS FPGA SDK installation is complete and
+  sourced
+- Invalid slot ID: Verify slot number is valid for instance type
+- AFI load timeout: Check AFI ID and instance permissions, and ensure
+  sufficient time after async FPGA clears and loads
+- Debug: Enable verbose logging by setting logging.INFO in ``utils.py``
+- Supported Python Versions: Bindings can be used by all Python versions
+  supported by Cython
+- How do I find my instance type during runtime: `Instance Meta Data
+  Documentation <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html#instance-metadata-retrieval-examples>`__
+
+FPGA Management Library Functions
+---------------------------------
+
+These are the core functions that provide direct interaction with AWS F2
+FPGA instances. The primary functions include FPGA slot initialization,
+image loading/clearing, status checking, and metric gathering. These
+functions form the API layer between Python applications and the
+low-level FPGA hardware management, allowing developers to control FPGA
+resources without dealing directly with the hardware registers or
+low-level C interfaces.
+
+- ``load_local_image(self, slot_id: int, afi_id: str) -> dict``
+- ``clear_local_image(self, slot_id: int) -> dict``
+- ``describe_local_image(self, slot_id: int, flags: uint32_t) -> dict``
+- ``strerror(error: int) -> str``
+- ``strerror_long(err: int) -> str``
+- ``get_status_name(status: int) -> str``
+- ``get_status(self, slot_id: int) -> dict``
+- ``set_cmd_timeout(self, value: uint32_t) -> None``
+- ``set_cmd_delay_msec(self, value: uint32_t) -> None``
+- ``get_vLED_status(self, slot_id: int) -> uint16_t``
+- ``set_vDIP(self, slot_id: int, value: uint16_t) -> None``
+- ``get_vDIP_status(self, slot_id: int) -> uint16_t``
+- ``clear_local_image_sync(self, slot_id: int, timeout: uint32_t, delay_msec: uint32_t) -> dict``
+- ``load_local_image_flags(self, slot_id: int, afi_id: str, flags: uint32_t) -> dict``
+- ``load_local_image_sync_flags(self, slot_id: int, afi_id: str, flags: uint32_t, timeout: uint32_t, delay_msec: uint32_t) -> dict``
+
+FPGA Clock Generation Library Functions
+---------------------------------------
+
+The Clock Generation Library provide essential clock management
+capabilities for AWS FPGA instances, allowing precise control over clock
+frequencies and configurations. The primary functions include retrieving
+current clock settings, applying predefined clock recipes, and
+dynamically adjusting frequencies across multiple clock domains (A, B,
+C, and HBM). These functions form the API layer between Python
+applications and the low-level clock management system, allowing
+developers to precisely control FPGA clock resources without directly
+manipulating hardware registers. More information on clock generation
+functions are available in the
+`Clock Recipes User Guide <../../../hdk/docs/Clock-Recipes-User-Guide.html>`__
+document.
+
+- ``get_dynamic(self, slot_id: int) -> str``
+- ``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``
+- ``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``
+
+FPGA PCI Library Functions
+--------------------------
+
+The FPGA PCI library provides a comprehensive set of functions for
+managing and interacting with the PCI bus on AWS FPGA instances. The
+library starts with initialization to set up the PCI management
+interface, and ``pci_attach()``/``pci_detach()`` to establish and
+terminate connections to specific PCI Base Address Registers (BARs).
+These functions form the basis for accessing PCI-mapped hardware
+resources.
+
+- ``pci_attach(self, slot_id: int, pf_id: int, bar_id: int, flags: uint32_t) -> pci_bar_handle_t``
+- ``pci_detach(self, handle: pci_bar_handle_t) -> None``
+- ``pci_poke(self, handle: pci_bar_handle_t, offset: uint64_t, value: uint32_t) -> None``
+- ``pci_poke8(self, handle: pci_bar_handle_t, offset: uint64_t, value: uint8_t) -> None``
+- ``pci_poke64(self, handle: pci_bar_handle_t, offset: uint64_t, value: uint64_t) -> None``
+- ``pci_write_burst(self, handle: pci_bar_handle_t, offset: uint64_t, data: List[int], dword_len: uint64_t) -> None``
+- ``pci_peek(self, handle: pci_bar_handle_t, offset: uint64_t) -> uint32_t``
+- ``pci_peek8(self, handle: pci_bar_handle_t, offset: uint64_t) -> uint8_t``
+- ``pci_peek64(self, handle: pci_bar_handle_t, offset: uint64_t) -> uint64_t``
+- ``pci_get_slot_spec(self, slot_id: int) -> fpga_slot_spec``
+- ``pci_get_all_slot_specs(self, size: int) -> List[fpga_slot_spec]``
+- ``pci_get_resource_map(self, slot_id: int, pf_id: int) -> fpga_pci_resource_map``
+- ``pci_rescan_slot_app_pfs(self, slot_id: int) -> None``
+- ``pci_get_address(self, handle: pci_bar_handle_t, offset: uint64_t, dword_len: uint64_t) -> uintptr_t``
+- ``pci_memset(self, handle: pci_bar_handle_t, offset: uint64_t, value: uint32_t, dword_len: uint64_t) -> None``