Adding_target.md

Adding Your Own Design

💡 A guide to add your own target.

Adding your own target

The Planter supports the tests on the software (e.g. BMv2) and hardware (e.g. Tofino) switch target with the following options:

• software target:

  └── compile: generate P4 code for compilation

  └── software: generate P4 code for compilation and generate simple test scripts for accuracy results under software environment

• hardware target:

  └── compile: generate P4 code for compilation

  └── software: generate P4 code for compilation and generate simple test scripts for accuracy results under software environment

  └── hardware: generate P4 code for compilation and generate simple test scripts for accuracy results under hardware environment

Software target

Test environment (model_test folder & utils folder)

Software target like the BMv2 has the emulated software environment. To support the tests on the software target, the test environment need to be added to the model_test folder and the corresponding building packages need to be added to the utils folder.

For example, BMv2 entails a software environment to compile the P4 code into a JSON representation to be consumed by the software switch. The switch usually runs in a topology simulated with the Mininet tool. In this case, the whole environment (BMv2, p4c, Mininet) to compile the code, simulate the network topology and run the code can be put under the model_test folder.

The run_model.py file

The main function of the run_model.py code is to load the P4 code (generated by Planter under the /P4/ folder) to the test environment. This is implemented by generating a bash file to 1) copy the P4 code to the test environment, 2) run the compilation.

file_names function

This function reads the working directory of P4 file and the test environment.

• The overview of file_names(*) function

  def file_names(Planter_config):
      return work_root, model_test_root, file_name, test_file_name

• The input of file_names(*) function

  Planter_config # dict 
                 # P4 generator's configs - Planter_config['p4 config']
                 # loaded from json file in the main function

• The output of file_names(*) function

  work_root # working directory of Planter
  model_test_root # software target test environment
  file_name # P4 file name defined in the format: model_usecase_dataset
  test_file_name # test file name in the format: test_switch_model_TargetDevice_TargetType

add_make_run_model function

This function generates the bash script to copy the P4 code from /P4/ to the test environment for compiling and running. The commands generated in the script need to adapt to the test environment and follow the compiling and running steps of the software target.

• The overview of add_make_run_model(*) function

  def add_make_run_model(fname, config):
      with open(fname, 'w') as command:
          command.write("#!/bin/bash\n")
      ...

• The input of add_make_run_model(*) function

  fname # str
        # File name of the bash script to be generated in this function 
        # Defined as '/src/scripts/make_run_model.sh'
  
  config # dict 
         # P4 generator's configs - Planter_config['p4 config']
         # loaded from json file in the main function

The test_model.py file

This file provides a test script to run the simple test with the test data on the software target.

write_common_test_classification function

This function generates a Python file to create the simple test packets with the Planter header to carry the test data. The packets are input to the target switch. After the switch gives a classification result to the packets, a classification report will summarize the classification accuracy. This applies to the models like DT/RF for classification tasks.

• The overview of write_common_test_classification(*) function

  def write_common_test_classification(fname, Planter_config):
      with open(fname, 'a') as test:
          test.write("import json\n")
  		  ...

• The input of write_common_test_classification(*) function

  fname # str
        # File name of the test Python script to be generated in this function 
        # Defined as '/src/test/test_switch_model_targetName_targetType.py'
  
  Planter_config # dict 
         # P4 generator's configs - Planter_config['p4 config']
         # loaded from json file in the main function

write_common_test_dimension_reduction function

Similar to write_common_test_classification function, this function write_common_test_dimension_reduction also generates a python file to create the simple test packets with the Planter header to carry the test data. The difference is that this test script is created for models (e.g. PCA/AE) doing the dimension reduction tasks. After the switch gives an analysis result to the packets, the comparison will be presented in Pearsons correlation value.

generate_test_file function

This function calls the write_common_test_classification/write_common_test_dimension_reduction to generate the test script.

• The overview of generate_test_file(*) function

  def generate_test_file(config_file):
      ...
      # select the test script to generate
      if Planter_config['test config']['type of test'] == 'dimension_reduction':
          write_common_test_dimension_reduction(test_file,Planter_config)
      elif Planter_config['test config']['type of test'] == 'classification':
          write_common_test_classification(test_file,Planter_config)
      return test_file

• The input of generate_test_file(*) function

  config_file # dict 
              # P4 generator's configs - Planter_config['p4 config']
              # loaded from json file in the main function

Hardware target

Test environment

Different from the software target with the software test environment, the hardware target requires compiling and testing on the hardware device. For targets like the Tofino switch, the software development environment (SDE) is provided for program testing and debugging. In this case, to enable Planter to support your own hardware target, the SDE environment information needs to be added to the following functions to generate the scripts for running and testing. The hardware implementation and tests are based on the hardware device. The functions defined in run_model.py and test_model.py files are similar to the descriptions above. Due to the NDA, we don’t list the details here.