Skip to content

Commit

Permalink
Revert "Update section-1 and section-3 examples (#1179)"
Browse files Browse the repository at this point in the history
This reverts commit 0e4fc7c.
  • Loading branch information
jackl-xilinx authored Apr 8, 2024
1 parent 0e4fc7c commit 069f59b
Show file tree
Hide file tree
Showing 10 changed files with 22 additions and 770 deletions.
17 changes: 8 additions & 9 deletions programming_guide/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,23 +13,22 @@
MLIR-AIE is an MLIR-based representation for AI Engine design. It provides a foundation from which complex and performant AI Engine designs can be defined and is supported by simulation and hardware impelemenation infrastructure. To better understand how AI Engine designs are defined at the MLIR level, it is recommended that you spend some time going through the [MLIR tutorial](../tutorials/) material. However, this programming guide is intended to lead you through a higher level abstraction (python) of the underlying MLIR-AIE framework and provide design examples and programming tips to allow users to build designs directly. Keep in mind also that MLIR-AIE is a foundational layer in a AI Engine software development framework and while this guide provides a programmer's view for using AI Engines, it also serves as a lower layer for higher abstraction MLIR layers such as [MLIR-AIR](https://github.com/Xilinx/mlir-air).

## Outline
<details><summary><a href="./section-1">Section 1 - Basic AI Engine building blocks</a></summary>
<details><summary><a href="./section-1">Section 1 - Basic AI Engine building blocks (tiles and buffers)</a></summary>

* Introduce AI Engine building blocks with references to Tutorial material
* Give example of python binded MLIR source for defining tiles
* Give example of python binded MLIR source for defining tiles and buffers
</details>
<details><summary><a href="./section-2">Section 2 - Data Movement (Object FIFOs)</a></summary>
<details><summary><a href="./section-2">Section 2- My First Program</a></summary>

* Introduce example of first simple program (Bias Add)
* Illustrate how built-in simulation of single core design
</details>
<details><summary><a href="./section-3">Section 3 - Data Movement (Object FIFOs)</a></summary>

* Introduce topic of objectfifos and how they abstract connections between objects in the AIE array
* Point to more detailed objectfifo material in Tutorial
* Introduce key objectfifo connection patterns (link/ broadcast, join/ distribute)
</details>
<details><summary><a href="./section-3">Section 3 - My First Program</a></summary>

* Introduce example of first simple program (Bias Add)
* Illustrate how built-in simulation of single core design
* Illustrate how to run designs on Ryzen AI enabled hardware
</details>
<details><summary><a href="./section-4">Section 4 - Vector programming & Peformance Measurement</a></summary>

* Discuss topic of vector programming at the kernel level
Expand Down
28 changes: 0 additions & 28 deletions programming_guide/quick_reference.md

This file was deleted.

18 changes: 0 additions & 18 deletions programming_guide/section-1/Makefile

This file was deleted.

42 changes: 14 additions & 28 deletions programming_guide/section-1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,54 +8,40 @@
//
//===----------------------------------------------------------------------===//-->

# <ins>Section 1 - Basic AI Engine building blocks</ins>
# <ins>Section 1 - Basic AI Engine building blocks (tiles and buffers)</ins>

When we program for AI Engines, our MLIR-AIE framework serves as the entry point to declare and configure the structural building blocks that make up an array of AI Engines. Details for these building blocks, along with the general architecture of AI Engines are described in the [MLIR tutorials](../tutorials). Read through the synopsis first before continuing here.
When we program for AI Engines, our MLIR-AIE framework serves as the entry point to declare and configure the structural building blocks of the entire AI Engine array. Details for these building blocks, along with the general architecture of AI Engines are breifly described in the top page of [MLIR tutorials](../tutorials) materials. Read through that synopsis first before continuing here.

In this programming guide, we will be utilizing the python bindings for MLIR-AIE components to describe our design at the tile level of granularity. Later on, when we focus on kernel programming, we will explore vector programming in C/C++. But let's first look at a basic python source file (named [aie2.py](./aie2.py)) for an MLIR-AIE design.

At the top of this python source, we include modules that define the mlir-aie dialect and the mlir ctx wrapper which encapsulates the definition of our AI Engine enabled device (e.g. xcvc1902) and its associated structural building blocks.
In this programming guide, we will be utilizing the python bindings of MLIR-AIE components to describe our system and the tile level. Later on, when we focus in on kernel programming, we will programming in C/C++. Let's first look at a basic python source file for a MLIR-AIE design.

```
from aie.dialects.aie import * # primary mlir-aie dialect definitions
from aie.extras.context import mlir_mod_ctx # mlir ctx wrapper
```
Then we declare a structural design function that expands into mlir code when called because it contains the ctx wrapper. This wrapper, defined in the `mlir_mod_ctx()` module, contains custom python bindings definitions that leverage python to simplify some of the more detailed mlir block definitions.
```
# AI Engine structural design function
# My program definition
def mlir_aie_design():
# ctx wrapper - to convert python to mlir
# ctx wrapper - needed to convert python to mlir
with mlir_mod_ctx() as ctx:
```
Within our ctx wrapper, we finally get down to declaring our AI Engine device via `@device(AIEDevice.xcvc1902)` and the blocks within the device. Inside the `def device_body():` , we instantiate our AI Engine blocks, which in this first example is simply the AI Engine tiles. The arguments for the tile delcaration are the tile coordinates (column, row) and we assign it a variable tile name in our python program.

> **NOTE:** The actual tile coordinates run on the device may deviate from the ones declared here. In Ryzen AI, for example, these coordinates tend to be relative corodinates as the runtime scheduler may assign it to a different available column.
```
# Dvice declaration - here using aie2 device xcvc1902
# device declaration - here using aie2 device xcvc1902
@device(AIEDevice.xcvc1902)
def device_body():
# Tile declarations
ComputeTile = tile(1, 3)
ComputeTile = tile(2, 3)
ComputeTile = tile(2, 4)
```
Once we are done declaring our blocks (and connections), we print the ctx wrapped design python defined design is converted to mlir and printed to stdout. Then we finish our python code by calling the strucgtural design function.
```
ComputeTile = tile(1, 4)
# Buffer declarations
ComputeBuffer = buffer(ComputeTile, (8,), T.i32(), name = "a14")
# print the mlir conversion
print(ctx.module)
# Call my program
mlir_aie_design()
```

## <u>Exercises</u>
1. To run our python program, we simply call `python aie2.py` which converts our python structural design into mlir source code. This works from the command line if our design environment already contains the mlir-aie python binded dialect module. We included this in the [Makefile](./Makefile) so go ahead and run `make`. Then take a look at the generated mlir source under `build/aie.mlir`.

2. Run `make clean` to remove the generated files. Then add a type-o to the python source such as misspelling `tile` to `tilex` and then run `make` again. What messages do you see? <img src="../../tutorials/images/answer1.jpg" title="There is python error because tilex is not recognized." height=25>
* Introduce AI Engine building blocks with references to Tutorial material
* Give example of python binded MLIR source for defining tiles and buffers

3. Run `make clean` again. Now change the error by renaming `tilex` back to `tile` but change the coordinates to (-1,3) which is an inavlid location. Run `make` again. What messages do you see now? <img src="../../tutorials/images/answer1.jpg" title="No error is generated." height=25>

4. No error is generated but our code is invalid. Take a look at the generated mlir code under `build/aie.mlir`. You'll notice that the generaed mlir syntax is incorrect and running our mlir-aie tools on this mlir source will generate an error. We do, however, have some additional python structural syntax checks that can be enabled if change the `print(ctx.module)` to `print(ctx.module.operation.verify())`. Make this change and run `make` again. What message do you see now? <img src="../../tutorials/images/answer1.jpg" title="It now says column value fails to satisfy the constraint because the minimum value is 0" height=25>

31 changes: 0 additions & 31 deletions programming_guide/section-1/aie2.py

This file was deleted.

69 changes: 0 additions & 69 deletions programming_guide/section-3/CMakeLists.txt

This file was deleted.

40 changes: 0 additions & 40 deletions programming_guide/section-3/Makefile

This file was deleted.

69 changes: 0 additions & 69 deletions programming_guide/section-3/aie2.py

This file was deleted.

Loading

0 comments on commit 069f59b

Please sign in to comment.