btm-resource-manager 1.3.3

Resource manager for CLI tools

Board Config and Resource Manager

Board Config

The board config describes all hardware connected to the CI machine.

Example:

"max32655_board_2" : {
    "desc"         : "marked sn #2, for per test,",
    "target"       : "MAX32655",
    "board"        : "EvKit_V1",
    "rev"          : "PCB-00177-B-0",
    "group"        : "APP",
    "dap_sn"       : "04090000ceeb82b000000000000000000000000097969906",
    "console_port" : "/dev/serial/by-id/usb-FTDI_FT230X_Basic_UART_D309ZDEP-if00-port0",
    "hci_port"     : "/dev/serial/by-id/usb-FTDI_FT230X_Basic_UART_DT03OH8D-if00-port0",
    "ocdports"     : {
        "gdb"    : "3552",
        "tcl"    : "4552",
        "telnet" : "6552"
    },
}

Required Fields if programmable with openocd

• Target : Chip target as found in openocd target
• dap_sn : Serial number of dap programmer

Optional fields

• All fields are optional if they do not require the field. For example, a spectrum anaylzer does not need a board field. This can be left null in that case.

• ocdports : Ports to flash on. If not specified the resource_manager will generate ports for you.

Value usage

Any value can be queried using the resource manager for use in workflows, actions, and test scripts.

Resource Manager

The resource manager is a CLI and python library tool which can be used both in other python scripts and from the command line. It's primary functions are

• Lock/Unlcock hardware resources
• Query resource information
• Monitor resources

CLI usage

usage: resource_manager.py [-h] [--timeout TIMEOUT] [-u [UNLOCK ...]] [--unlock-all] [-l [LOCK ...]] [--owner OWNER] [--list-usage] [-g GET_VALUE] [-go GET_OWNER]

    Lock/Unlock Hardware resources
    Query resource information
    Monitor resources
    

options:
  -h, --help            show this help message and exit
  --timeout TIMEOUT, -t TIMEOUT
                        Timeout before returning in seconds
  -u [UNLOCK ...], --unlock [UNLOCK ...]
                        Name of board to unlock per boards_config.json
  --unlock-all          Unlock all resources in lock directory
  -l [LOCK ...], --lock [LOCK ...]
                        Name of board to lock per boards_config.json
  --owner OWNER         Name of user locking or unlocking
  --list-usage          Display basic usage stats of the boardsincluding if they are locked and when they were locked
  -g GET_VALUE, --get-value GET_VALUE
                        Get value for resource in config (ex: max32655_board1.dap_sn)
  -go GET_OWNER, --get-owner GET_OWNER
                        Get owner of resource if locked

Locking

• Boards can be locked using the -l or --lock option. Example: resource_manager.py -l board1 board2
• If wanted, ownership can optionally be applied using the --owner flag. Example: resource_manager.py -l board1 --owner Eve. The owner will be stored along with the lock information.

Unlocking

• Boards can be locked using the -u or --unlock option. Example: resource_manager.py -u board1 board2
• If locked with an owner, the owner is required to unlock the board. Example: resource_manager.py -u board1 --owner Eve
• The --unlock-all flag is a master unlock and requires no ownership. It should only be used at the command line directly and manually if a deadlock should occur, or resources were not properly cleaned up.

Querying usage

• Any value of the board config can be queried using the -g flag
• If your query does not resolve to a single value you will get a printout of the the json

Input

resource_manager -g max32655_board2.ocdport.gdb

Output

3552

Usage

The --list-usage flag can be used to print the a usage table

╒════════════════════════╤══════════╤═════════╤═════════════════════╤═════════╕
│ NAME                   │ IN-USE   │ GROUP   │ START               │ OWNER   │
╞════════════════════════╪══════════╪═════════╪═════════════════════╪═════════╡
│ max32570_board0        │ False    │         │                     │         │
├────────────────────────┼──────────┼─────────┼─────────────────────┼─────────┤
│ max32655_e2            │ False    │ APP     │                     │         │
├────────────────────────┼──────────┼─────────┼─────────────────────┼─────────┤
│ max32665_1             │ False    │ APP     │                     │         │
├────────────────────────┼──────────┼─────────┼─────────────────────┼─────────┤
│ max32690_1             │ True     │ APP     │ 25/04/2024 10:37:46 │   Eve   │
╘════════════════════════╧══════════╧═════════╧═════════════════════╧═════════╛

The usage table lists the following:

• Name: Resource Name
• In-Use: If the board is currently locked
• Group: (APP/RFPHY/OTHER)
• Start: When the board was locked
• Owner: Who owns the board (Empty if no ownership was applied)

OpenOCD Utils

Along with the Resource manager CLI, there are a few cli tools installed as well which help with flashing, erasing, reseting and debugging ad MAX32 target.

• ocdreset : reset target
• ocderase : erase target flash
• ocdflash : flash target with program
• ocdopen : open an ocd session to connect to via GDB

Minimal Resource Manager Setup for Local Use

Install the resource manager

Linux:

cd Resource_Share
chmod +x install.sh
./install.sh

Windows:

cd Resource_Share
install.bat

As this is a python library you must have python 3.8 or higher installed to use it.

Verify the installation by running resource_manager -v in the terminal

Create a Locks Directory

Linux:

mdkir ~/resource_locks

Windows:

mkdir C:\resource_locks

Create a Config Directory and board_config.json

Linux:

mdkir ~/resource_configs
cd ~/resource_configs
touch board_config.json

Windows:

mkdir C:\resource_configs
cd resource_configs
copy /b board_config.json +,,

Inside board_config.json, create an entry like the one shown in Board Config

Set environment variables to point to files

Replace MAXIM_PATH with the location of your MaximSDK installation. If you have a place where OpenOCD is then use that instead. Linux:

echo export OPENOCD_PATH="~/<MAXIM_PATH>/Tools/OpenOCD/scripts" >> ~/.bashrc
echo export CI_BOARD_CONFIG="~/resource_configs/board_config.json" >> ~/.bashrc
echo export RESOURCE_LOCK_DIR="~/resource_locks" >> ~/.bashrc

Windows:

setx OPENOCD_PATH "C:\<MAXIM_PATH>\Tool\OpenOCD\scripts"
setx CI_BOARD_CONFIG "C:\resource_configs\board_config.json"
setx RESOURCE_LOCK_DIR "C:\resource_locks"

Start a new terminal and test your configuration by typing resource_manager -lu. You should see an output similar to this

Verify your board config

Run ocdreset <resource-name> on a board you entered into the board_config.json