README.md

Tydi-Chisel code examples

This directory contains some Tydi-lang code¹ examples and their corresponding Tydi-Chisel² representations. The tydi-lang-2 compiler³ and tydi-lang-2-chisel transpiler⁴ are used to generate Tydi-Chisel boilerplate code⁵ from a Tydi source code. Subsequently, the behavioral code must be manually added to the generated Tydi-Chisel boilerplate code.

The examples in tydi directory are written in tydi-lang-2 code. For a full syntax description of tydi-lang-2 please refer to the Tydi-lang syntax documentation.

The examples serve as a basis for analyzing the representation methods of the testing frameworks in relation to Tydi-lang and Tydi-Chisel code. Specifically, there are three main characteristics that are of interest for this analysis:

1. Firstly, how the testing frameworks at state-of-the-art represent tydi types and streams.
2. Secondly, how nested tydi groups results in testing frameworks.
3. Finally, how nested streams are treated and what representation is used for them.

The tydi-chisel-examples is organized as follows:

• The tydi subfolder contains the Tydi source code examples.
• The chisel subfolder contains the corresponding Tydi-Chisel code example.

All the examples are related each other, and they have an increasing complexity.

• HelloWorldRgb: A simple example that instantiates two streams of group Rgb. It is one of the simplest examples that can be made. It simply interconnects inputs to outputs.
• PixelConverter: It extends the HelloWorldRgb example by adding more complex data structures. It uses Unions (similar to C unions) and Groups (similar to software structs). It implements a color scale converter from rgb to grayscale and vice versa. Depending on what type is the input stream since can be either rgb or gray it converts its input to the other color-scale. Moreover, it also makes use of tydi-lang templates to define custom and reusable types.
• CLikeStaticArray: It shows how to use advanced tydi-lang features such as the usage of for loops to instantiate fields in groups/unions/streamlets.
• PipelineSimple: A simple streaming pipeline that implements the following simple spark code, in which the input is a stream of integers with timestamps attached ({time: unsigned Integer, value: Integer}):

  // Input stream: {timestamp, value}
  // Output stream: {min_value, max_value, sum_value, avg_value}
  df.filter(col("value") >= 0)
      .agg( 
          min("value").as("min_value"), 
          max("value").as("max_value"), 
          sum("value").as("sum_value"), 
          avg("value").as("avg_value")
          )
      .select("min_value", "max_value", "sum_value", "avg_value")
        

• PipelineNestedGroup: It extends the PipelineSimple by adding a nested group to the input stream ({time: unsigned Integer, value: Integer, date: DateTime}). The DateTime can be encoded as {month: unsigned Integer, day: unsigned Integer, year: unsigned Integer, utc: Integer}. It filters every date that is not in the Amsterdam time zone (UTC+1) and every value that is negative. The respective spark code is the following:

  // Input stream: {timestamp, value, date}
  // Output stream: {min_value, max_value, sum_value, avg_value}
  df.filter(col("value") >= 0 && col("date").utc() >= +1)
      .agg( 
          min("value").as("min_value"), 
          max("value").as("max_value"), 
          sum("value").as("sum_value"), 
          avg("value").as("avg_value")
          )
      .select("min_value", "max_value", "sum_value", "avg_value")

• PipelineNestedStreams: It introduces the concept of nested streams to the PipelineNestedGroup example. Specifically, it associates a string (of undefined length) to the input and output streams. A string can be seen as sequence of chars and in tydi it can be represented by a stream of chars. Since its length is unknown, neither static arrays nor groups can represent it. The respective spark code is the following:

  // Input stream: {timestamp, value, date, string}
  // Output stream: {min_value, max_value, sum_value, avg_value, string}
  df.filter(col("value") >= 0 && col("date").utc() >= +1)
      .agg( 
          min("value").as("min_value"), 
          max("value").as("max_value"), 
          sum("value").as("sum_value"), 
          avg("value").as("avg_value")
          )
      .select("min_value", "max_value", "sum_value", "avg_value", "string")

Note: The examples are used to perform the analysis of the testing frameworks. Results are reported in the results directory.

Each example aims to test the representation of a particular Tydi feature: how it is represented in the testing frameworks by using the Tydi-Chisel library backend.

Example	Target
HelloWorldRgb	Explore the representation of Groups and Streams in testing frameworks.
PixelConverter	Understand how Unions are depicted in testing frameworks.
PipelineSimple	See how multiple tydi modules are represented and how differences in stream types can be deducted in testing frameworks.
PipelineNestedGroup	Analyze the impact of nested tydi groups on testing frameworks.
PipelineNestedStreams	Examine the impact of nested streams on testing frameworks.

References

Footnotes

1. Yongding Tian et al. “Tydi-lang: A Language for Typed Streaming Hardware”. In: Proceedings of the SC ’23 Workshops of The International Conference on High Performance Computing, Network, Storage, and Analysis. Denver CO USA: ACM, Nov. 12, 2023, pp. 521–529. ISBN: 9798400707858. ↩

2. Casper Cromjongh et al. “Tydi-Chisel: Collaborative and Interface-Driven Data-Streaming Accelerators”. In: 2023 IEEE Nordic Circuits and Systems Conference (NorCAS). Aalborg, Denmark: IEEE, Oct. 31, 2023, pp. 1–7. ISBN: 9798350337570. ↩

3. The Tydi-lang-2 compiler. ↩

4. The Tydi-lang-2-Chisel transpiler. ↩

5. A implementation of Tydi interfaces and concepts in Chisel. ↩