PARIS Recovery Framework

This document provides an overview of the PARIS recovery framework, its code structure, and key concepts.

Introduction

PARIS is a tool used for recovering and deploying ChromeOS devices. It is a plan-based system, where each plan is a series of actions that are executed in a specific order. Each action can have conditions that determine whether it should be run, and dependencies on other actions.

Code Structure

The main components of the PARIS framework are located in the go.chromium.org/infra/cros/recovery directory. Here are some of the key subdirectories:

• config: This directory contains the configuration for the recovery plans. The config_cros_deploy.go file defines the crosDeployPlan, which is the main plan for deploying ChromeOS devices.
• internal/execs: This directory contains the executable functions that are run by the actions in the recovery plans. The execs.go file defines the Register function, which is used to register new exec functions. The dut/attributes_execs.go file contains execs related to DUT attributes, such as checking the DUT's pool.
• tlw: This directory contains the top-level wrapper for the recovery framework. It defines the data structures that are used to represent DUTs and other resources.

Key Concepts

• Plans: A plan is a series of actions that are executed in a specific order. The crosDeployPlan in config/config_cros_deploy.go is an example of a plan.
• Actions: An action is a single step in a plan. Each action has a name, a documentation string, an exec function, and a list of conditions and dependencies.
• Execs: An exec is a function that is run by an action. Execs are registered with the framework using the execs.Register function.
• Conditions: A condition is a check that is performed before an action is run. If the condition fails, the action is skipped. Conditions are themselves actions that are expected to return an error if the condition is not met.

How to Add a New Check

Based on what we've learned, here is a step-by-step guide on how to add a new check to the PARIS framework:

1. Identify the correct exec function to use. If an existing exec function meets your needs, you can use it directly. If not, you will need to create a new one. In our case, we were able to use the existing dut_not_in_pool exec.
2. Create a new action that uses the exec function. This is done in the deployActions function in config/config_cros_deploy.go. The new action should have a descriptive name, a documentation string, the name of the exec function to use, and any necessary arguments.
3. Add the new action as a condition to the action that you want to control. In our case, we added the Is not in mp_firmware_testing pool action as a condition to the Verify boot in recovery mode action.
4. Run make trees to regenerate the configuration tree. This will ensure that your changes are picked up by the framework.
5. Run make test to run the test suite. This will ensure that your changes haven't introduced any regressions.