Error Handling Conventions #

Quick reference for error signaling patterns used across the Bus Pirate firmware.

Command-Level Error Signaling #

Set system_config.error = true to signal failure to the command dispatcher. This controls command chaining operators (;, ||, &&). Always return immediately after setting the error flag.

system_config.error = true;
return;

SERR_* Codes — Bytecode Pipeline Errors #

Defined in src/bytecode.h. Attached to result->error inside syntax write/read handlers.

enum SYNTAX_ERRORS {
    SERR_NONE = 0,
    SERR_DEBUG,
    SERR_INFO,
    SERR_WARN,
    SERR_ERROR
};

Usage in a syntax handler:

void dummy1_write(struct _bytecode* result, struct _bytecode* next) {
    if (result->out_data == 0xff) {
        result->error = SERR_ERROR;
        result->error_message = err;
        return;
    }
    result->data_message = message;
}

bp_cmd_status_t — Parsing Errors #

Defined in src/lib/bp_args/bp_cmd.h. Returned by bp_cmd_positional(), bp_cmd_flag(), and bp_cmd_prompt().

typedef enum {
    BP_CMD_OK = 0,
    BP_CMD_MISSING,
    BP_CMD_INVALID,
    BP_CMD_EXIT,
} bp_cmd_status_t;

FRESULT — FatFS Error Codes #

From FatFS library (src/fatfs/ff.h). Common codes:

Use storage_file_error(res) (declared in src/pirate/storage.h) to print a human-readable error message.

Error Handling Patterns #

Command handler:

void mycmd_handler(struct command_result* res) {
    if (bp_cmd_help_check(&mycmd_def, res->help_flag)) return;

    uint32_t value;
    bp_cmd_status_t st = bp_cmd_flag(&mycmd_def, 'v', &value);
    if (st == BP_CMD_INVALID) {
        system_config.error = true;
        return;
    }
    // ...
}

Mode setup:

uint32_t mymode_setup(void) {
    bp_cmd_status_t st = bp_cmd_flag(&mymode_setup_def, 's', &mode_config.speed);
    if (st == BP_CMD_INVALID) return 0;  // 0 = setup failed
    // ...
    return 1;  // 1 = setup succeeded
}

When to Return vs Continue #

Related Documentation #

• syntax_bytecode_guide.md — SERR codes in pipeline
• bp_cmd_parsing_api.md — bp_cmd_status_t details
• system_config_reference.md — system_config.error
• storage_guide.md — FRESULT codes
• Source: src/bytecode.h, src/lib/bp_args/bp_cmd.h, src/system_config.h