electronics/bs_explorer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fpga: load registry from yaml at runtime, not compile-time

Browse Source 
- registry moves from the array in fpga.c to fpga_registry.yaml at the
  repo root, parsed via libyaml (pkg-config yaml-0.1); adding a part is
  now a YAML edit, no rebuild
- looked up CWD-relative (like bsdl_files/), overridable with
  $BS_FPGA_REGISTRY, loaded lazily once; public API unchanged
- fpga_list shows the source file (fpga_registry_source())
- add microsemi_igloo2/smartfusion2 and lattice_machxo2/3 families,
  ready for the non-Xilinx targets
- docs updated: CLAUDE.md, README, tutorial "add a target" walkthrough

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Foué
2026-05-24 10:19:53 +02:00
parent 27836d63bb
commit 3579c5efb0
8 changed files with 409 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
modules/fpga/CMakeLists.txt
View File

@@ -5,3 +5,10 @@ file(GLOB_RECURSE ALL_SOURCES "*.c")
include_directories(${CMAKE_CURRENT_SOURCE_DIR}/..)
add_library(fpga ${ALL_SOURCES})
# The registry is parsed from YAML at runtime via libyaml (the canonical
# C YAML parser). Found through pkg-config; PUBLIC so the executable that
# links fpga picks up the dependency transitively.
find_package(PkgConfig REQUIRED)
pkg_check_modules(YAML REQUIRED IMPORTED_TARGET yaml-0.1)
target_link_libraries(fpga PUBLIC PkgConfig::YAML)

293
modules/fpga/fpga.c
View File

@@ -1,70 +1,249 @@
#include <stddef.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <yaml.h>
#include "fpga.h"
static const fpga_target fpga_registry[] = {
/* Xilinx Kintex UltraScale+ XCKU15P
* IDCODE_REGISTER and INSTRUCTION_OPCODE values come from
* bsdl_files/xcku15p_ffve1517.bsd
* IR length 6 bits, version nibble (bits 31:28) ignored. */
{
.name = "Xilinx Kintex UltraScale+ XCKU15P",
.idcode = 0x04A56093,
.idcode_mask = 0x0FFFFFFF,
.family = FPGA_FAMILY_XILINX_USP,
.bsdl_filename = "xcku15p_ffve1517.bsd",
.ir_length = 6,
.ir_cfg_in = 0x05,
.ir_user1 = 0x02,
.ir_jprogram = 0x0B,
.ir_jstart = 0x0C,
.ir_jshutdown = 0x0D,
.ir_isc_disable = 0x16,
.proxy_bitstream = NULL, /* TODO Phase 2.5: bscan_spi_xcku15p.bit */
.caveats = FPGA_CAVEAT_CCLK_VIA_STARTUP,
},
/* Xilinx Kintex UltraScale XCKU040 (KCU105 eval board)
* IDCODE_REGISTER and INSTRUCTION_OPCODE values come from
* bsdl_files/xcku040_ffva1156.bsd
* IR length 6 bits, version nibble (bits 31:28) ignored. */
{
.name = "Xilinx Kintex UltraScale XCKU040",
.idcode = 0x03822093,
.idcode_mask = 0x0FFFFFFF,
.family = FPGA_FAMILY_XILINX_US,
.bsdl_filename = "xcku040_ffva1156.bsd",
.ir_length = 6,
.ir_cfg_in = 0x05,
.ir_user1 = 0x02,
.ir_jprogram = 0x0B,
.ir_jstart = 0x0C,
.ir_jshutdown = 0x0D,
.ir_isc_disable = 0x16,
.proxy_bitstream = "bscan_spi_xcku040.bit",
.caveats = FPGA_CAVEAT_CCLK_VIA_STARTUP,
},
};
/*
* FPGA registry loaded at runtime from a YAML file (no longer a
* compile-time array). Lookup order for the file:
* 1. $BS_FPGA_REGISTRY (if set and non-empty)
* 2. "fpga_registry.yaml" relative to the current directory
* — the same CWD-relative convention as bsdl_files/ and bscan_proxies/,
* so run bs_explorer from the repository root.
*
* Loaded lazily on first access and cached for the process lifetime.
* The schema is one flat mapping per entry; see fpga_registry.yaml.
*/
#define FPGA_REGISTRY_LEN ((int)(sizeof(fpga_registry) / sizeof(fpga_registry[0])))
#define DEFAULT_REGISTRY_FILE "fpga_registry.yaml"
static fpga_target *g_registry = NULL;
static int g_count = 0;
static int g_loaded = 0; /* load attempted (success or not) */
static char g_source[1024] = "";
/* ---- small helpers ----------------------------------------------- */
static char *xstrdup(const char *s)
{
char *p;
size_t n;
if (!s) return NULL;
n = strlen(s) + 1;
p = (char *)malloc(n);
if (p) memcpy(p, s, n);
return p;
}
static fpga_family parse_family(const char *s)
{
if (!s) return FPGA_FAMILY_UNKNOWN;
if (!strcmp(s, "xilinx_7")) return FPGA_FAMILY_XILINX_7;
if (!strcmp(s, "xilinx_us")) return FPGA_FAMILY_XILINX_US;
if (!strcmp(s, "xilinx_usp")) return FPGA_FAMILY_XILINX_USP;
if (!strcmp(s, "microsemi_igloo2")) return FPGA_FAMILY_MICROSEMI_IGLOO2;
if (!strcmp(s, "microsemi_smartfusion2")) return FPGA_FAMILY_MICROSEMI_SMARTFUSION2;
if (!strcmp(s, "lattice_machxo2")) return FPGA_FAMILY_LATTICE_MACHXO2;
if (!strcmp(s, "lattice_machxo3")) return FPGA_FAMILY_LATTICE_MACHXO3;
fprintf(stderr, "fpga: unknown family '%s'\n", s);
return FPGA_FAMILY_UNKNOWN;
}
static unsigned int parse_caveats(const char *s)
{
unsigned int flags = 0;
char buf[256];
char *tok;
if (!s) return 0;
strncpy(buf, s, sizeof(buf) - 1);
buf[sizeof(buf) - 1] = '\0';
for (tok = strtok(buf, " ,|"); tok; tok = strtok(NULL, " ,|")) {
if (!strcmp(tok, "cclk_via_startup"))
flags |= FPGA_CAVEAT_CCLK_VIA_STARTUP;
else
fprintf(stderr, "fpga: unknown caveat '%s'\n", tok);
}
return flags;
}
/* Apply one "key: value" pair (both scalars) to the entry being built. */
static void set_field(fpga_target *t, const char *key, const char *val)
{
if (!strcmp(key, "name")) { free((void *)t->name); t->name = xstrdup(val); }
else if (!strcmp(key, "idcode")) t->idcode = strtoul(val, NULL, 0);
else if (!strcmp(key, "idcode_mask")) t->idcode_mask = strtoul(val, NULL, 0);
else if (!strcmp(key, "family")) t->family = parse_family(val);
else if (!strcmp(key, "bsdl")) { free((void *)t->bsdl_filename); t->bsdl_filename = xstrdup(val); }
else if (!strcmp(key, "ir_length")) t->ir_length = (int)strtol(val, NULL, 0);
else if (!strcmp(key, "ir_cfg_in")) t->ir_cfg_in = (unsigned int)strtoul(val, NULL, 0);
else if (!strcmp(key, "ir_user1")) t->ir_user1 = (unsigned int)strtoul(val, NULL, 0);
else if (!strcmp(key, "ir_jprogram")) t->ir_jprogram = (unsigned int)strtoul(val, NULL, 0);
else if (!strcmp(key, "ir_jstart")) t->ir_jstart = (unsigned int)strtoul(val, NULL, 0);
else if (!strcmp(key, "ir_jshutdown")) t->ir_jshutdown = (unsigned int)strtoul(val, NULL, 0);
else if (!strcmp(key, "ir_isc_disable")) t->ir_isc_disable = (unsigned int)strtoul(val, NULL, 0);
else if (!strcmp(key, "proxy_bitstream")) { free((void *)t->proxy_bitstream); t->proxy_bitstream = xstrdup(val); }
else if (!strcmp(key, "caveats")) t->caveats = parse_caveats(val);
else fprintf(stderr, "fpga: unknown key '%s'\n", key);
}
static int commit_entry(const fpga_target *cur)
{
fpga_target *tmp = (fpga_target *)realloc(g_registry,
(g_count + 1) * sizeof(*g_registry));
if (!tmp) {
fprintf(stderr, "fpga: out of memory loading registry\n");
return -1;
}
g_registry = tmp;
g_registry[g_count++] = *cur;
return 0;
}
/* Walk the YAML event stream. The document is a mapping with a single
* "fpgas" key holding a sequence of flat (scalar-only) mappings. */
static int load_registry(const char *path)
{
FILE *f;
yaml_parser_t parser;
yaml_event_t ev;
int done = 0;
int rc = 0;
int in_fpgas = 0; /* inside the fpgas: sequence */
int in_item = 0; /* inside one entry mapping */
int expect_fpgas_seq = 0; /* last top-level key was "fpgas" */
char *pending_key = NULL;
fpga_target cur;
f = fopen(path, "rb");
if (!f) return -1;
if (!yaml_parser_initialize(&parser)) { fclose(f); return -1; }
yaml_parser_set_input_file(&parser, f);
while (!done) {
if (!yaml_parser_parse(&parser, &ev)) {
fprintf(stderr, "fpga: YAML parse error in %s: %s (line %lu)\n",
path, parser.problem ? parser.problem : "?",
(unsigned long)parser.problem_mark.line + 1);
rc = -1;
break;
}
switch (ev.type) {
case YAML_SCALAR_EVENT: {
const char *v = (const char *)ev.data.scalar.value;
if (!in_fpgas) {
if (!strcmp(v, "fpgas"))
expect_fpgas_seq = 1;
} else if (in_item) {
if (!pending_key) {
pending_key = xstrdup(v);
} else {
set_field(&cur, pending_key, v);
free(pending_key);
pending_key = NULL;
}
}
break;
}
case YAML_SEQUENCE_START_EVENT:
if (expect_fpgas_seq && !in_fpgas) {
in_fpgas = 1;
expect_fpgas_seq = 0;
}
break;
case YAML_SEQUENCE_END_EVENT:
if (in_fpgas && !in_item)
in_fpgas = 0; /* end of the fpgas list */
break;
case YAML_MAPPING_START_EVENT:
if (in_fpgas && !in_item) {
memset(&cur, 0, sizeof(cur));
cur.idcode_mask = 0xFFFFFFFFUL; /* safe default: exact match */
in_item = 1;
}
break;
case YAML_MAPPING_END_EVENT:
if (in_item) {
in_item = 0;
free(pending_key);
pending_key = NULL;
if (commit_entry(&cur) != 0) {
rc = -1;
yaml_event_delete(&ev);
done = 1;
continue;
}
}
break;
case YAML_STREAM_END_EVENT:
done = 1;
break;
default:
break;
}
yaml_event_delete(&ev);
}
free(pending_key);
yaml_parser_delete(&parser);
fclose(f);
return rc;
}
static void ensure_loaded(void)
{
const char *path;
if (g_loaded) return;
g_loaded = 1;
path = getenv("BS_FPGA_REGISTRY");
if (!path || !*path) path = DEFAULT_REGISTRY_FILE;
load_registry(path); /* fills g_registry/g_count; warns on its own errors */
if (g_count > 0) {
strncpy(g_source, path, sizeof(g_source) - 1);
g_source[sizeof(g_source) - 1] = '\0';
} else {
fprintf(stderr,
"fpga: no targets loaded from '%s' "
"(set BS_FPGA_REGISTRY, or run from the directory containing it)\n",
path);
}
}
/* ---- public API -------------------------------------------------- */
int fpga_get_target_count(void)
{
return FPGA_REGISTRY_LEN;
ensure_loaded();
return g_count;
}
const fpga_target *fpga_get_target_by_index(int index)
{
if (index < 0 || index >= FPGA_REGISTRY_LEN) {
ensure_loaded();
if (index < 0 || index >= g_count) {
return NULL;
}
return &fpga_registry[index];
return &g_registry[index];
}
const fpga_target *fpga_lookup_by_idcode(unsigned long idcode)
{
int i;
for (i = 0; i < FPGA_REGISTRY_LEN; i++) {
const fpga_target *t = &fpga_registry[i];
ensure_loaded();
for (i = 0; i < g_count; i++) {
const fpga_target *t = &g_registry[i];
if ((idcode & t->idcode_mask) == (t->idcode & t->idcode_mask)) {
return t;
}
@@ -75,10 +254,20 @@ const fpga_target *fpga_lookup_by_idcode(unsigned long idcode)
const char *fpga_family_name(fpga_family f)
{
switch (f) {
case FPGA_FAMILY_XILINX_7: return "Xilinx 7-Series";
case FPGA_FAMILY_XILINX_US: return "Xilinx UltraScale";
case FPGA_FAMILY_XILINX_USP: return "Xilinx UltraScale+";
case FPGA_FAMILY_XILINX_7: return "Xilinx 7-Series";
case FPGA_FAMILY_XILINX_US: return "Xilinx UltraScale";
case FPGA_FAMILY_XILINX_USP: return "Xilinx UltraScale+";
case FPGA_FAMILY_MICROSEMI_IGLOO2: return "Microsemi IGLOO2";
case FPGA_FAMILY_MICROSEMI_SMARTFUSION2: return "Microsemi SmartFusion2";
case FPGA_FAMILY_LATTICE_MACHXO2: return "Lattice MachXO2";
case FPGA_FAMILY_LATTICE_MACHXO3: return "Lattice MachXO3";
case FPGA_FAMILY_UNKNOWN:
default: return "Unknown";
default: return "Unknown";
}
}
const char *fpga_registry_source(void)
{
ensure_loaded();
return g_source[0] ? g_source : NULL;
}

17
modules/fpga/fpga.h
View File

@@ -11,8 +11,10 @@
* - path to the BSCAN proxy bitstream
* - per-target caveats (known hardware gotchas)
*
* Adding an FPGA = one entry in fpga_registry[] + its .bsd in
* bsdl_files/ + (optionally) its proxy .bit in bscan_proxies/.
* The registry is loaded at runtime from a YAML file (no longer a
* compile-time array). Adding an FPGA = one entry in the YAML +
* its .bsd in bsdl_files/ + (optionally) its proxy .bit in
* bscan_proxies/. See fpga_registry.yaml for the format.
*/
#include "jtag_core/jtag_core.h"
@@ -22,6 +24,10 @@ typedef enum {
FPGA_FAMILY_XILINX_7,
FPGA_FAMILY_XILINX_US,
FPGA_FAMILY_XILINX_USP,
FPGA_FAMILY_MICROSEMI_IGLOO2,
FPGA_FAMILY_MICROSEMI_SMARTFUSION2,
FPGA_FAMILY_LATTICE_MACHXO2,
FPGA_FAMILY_LATTICE_MACHXO3,
} fpga_family;
/* Caveat flags: known hardware gotchas for a part. */
@@ -48,10 +54,15 @@ typedef struct {
unsigned int caveats; /* FPGA_CAVEAT_* flags */
} fpga_target;
/* Registry access */
/* Registry access. The YAML file is loaded lazily on first call to any
* of these, and cached for the process lifetime. */
int fpga_get_target_count(void);
const fpga_target * fpga_get_target_by_index(int index);
const fpga_target * fpga_lookup_by_idcode(unsigned long idcode);
const char * fpga_family_name(fpga_family f);
/* Path the registry was loaded from, or NULL if nothing loaded
* (file missing / parse error). For diagnostics. */
const char * fpga_registry_source(void);
#endif

7
modules/script/script.c
View File

@@ -2779,17 +2779,20 @@ static int cmd_get_pins_list(script_ctx *ctx, char *line)
const char *cmd_fpga_list_help[] = {
"",
"Lists the FPGA targets known to this build (registry in modules/fpga/).",
"Lists the FPGA targets in the registry (loaded from fpga_registry.yaml).",
""};
static int cmd_fpga_list(script_ctx *ctx, char *line)
{
int i, n;
const fpga_target *t;
const char *src;
(void)line;
n = fpga_get_target_count();
ctx->script_printf(ctx, MSG_INFO_0, "%d FPGA target(s) registered:\n", n);
src = fpga_registry_source();
ctx->script_printf(ctx, MSG_INFO_0, "%d FPGA target(s) registered (from %s):\n",
n, src ? src : "<no registry loaded>");
for (i = 0; i < n; i++) {
t = fpga_get_target_by_index(i);
ctx->script_printf(ctx, MSG_NONE,