# SPDX-License-Identifier: Apache-2.0
#
# Copyright (c) 2023, Nordic Semiconductor ASA

## A pykwalify schema for basic validation of the structure of a
## board metadata YAML file.
##
# The board.yml file is a simple list of key value pairs containing board
# information like: name, vendor, socs, variants.
schema;variant-schema:
  required: false
  type: seq
  sequence:
    - type: map
      mapping:
        name:
          required: true
          type: str
        cpucluster:
          required: false
          type: str
        variants:
          required: false
          include: variant-schema

schema;extend-variant-schema:
  required: false
  type: seq
  sequence:
    - type: map
      mapping:
        name:
          required: true
          type: str
        qualifier:
          required: true
          type: str

schema;board-schema:
  type: map
  mapping:
    name:
      required: false # Note: either name or extend is required, but that is handled in python
      type: str
      desc: Name of the board
    full_name:
      required: false
      type: str
      desc: Full name of the board. Typically set to the commercial name of the board.
    extend:
      required: false # Note: either name or extend is required, but that is handled in python
      type: str
    vendor:
      required: false
      type: str
      desc: SoC family of the SoC on the board.
    revision:
      required: false
      type: map
      mapping:
        format:
          required: true
          type: str
          enum:
            ["major.minor.patch", "letter", "number", "custom"]
        default:
          required: false # This field is required when 'format' != 'custom'
          type: str
        exact:
          required: false
          type: bool
        revisions:
          required: false # This field is required when 'format' != 'custom'
          type: seq
          sequence:
            - type: map
              mapping:
                name:
                  required: true
                  type: str
    socs:
      required: false # Required for name:, but not for extend.
      type: seq
      sequence:
        - type: map
          mapping:
            name:
              required: true
              type: str
            variants:
              include: variant-schema
    variants:
      include: extend-variant-schema

type: map
mapping:
  board:
    include: board-schema
  boards:
    type: seq
    sequence:
      - include: board-schema
  runners:
    type: map
    mapping:
      priority:
        type: int
        desc: |
              Priority of this flash run once configuration. The highest value data will be used
              instead of any with lower priorities. If omitted, will default to 10.
      run_once:
        type: map
        desc: |
              Allows for restricting west flash commands when using sysbuild to run once per given
              grouping of board targets. This is to allow for future image program cycles to not
              erase the flash of a device which has just been programmed by another image.
        mapping:
          regex;(.*):
            type: seq
            desc: |
                  A dictionary of commands which should be limited to running once per invocation
                  of west flash for a given set of flash runners and board targets.
            sequence:
              - type: map
                mapping:
                  run:
                    required: true
                    type: str
                    enum: ['first', 'last']
                    desc: |
                          If first, will run this command once when the first image is flashed, if
                          last, will run this command once when the final image is flashed.
                  runners:
                    required: true
                    type: seq
                    sequence:
                      - type: str
                        desc: |
                              A list of flash runners that this applies to, can use `all` to apply
                              to all runners.
                  groups:
                    required: true
                    type: seq
                    sequence:
                      - type: map
                        desc: |
                              A grouping of board targets which the command should apply to. Can
                              be used multiple times to have multiple groups.
                        mapping:
                          boards:
                            required: true
                            type: seq
                            sequence:
                              - type: str
                                desc: |
                                      A board target to match against in regex. Must be one entry
                                      per board target, a single regex entry will not match two
                                      board targets even if they both match.