feat: add registers extraction task for PAC generation

[ozongzi]

Summary

Adds a new registers extraction task that uses Gemini to extract a complete peripheral register map from a microcontroller datasheet, outputting structured JSON suitable for generating Rust PAC (Peripheral Access Crate) code via svd2rust or chiptool.

datasheet extract registers STM32F407.pdf -f

Output Format

The output JSON models peripherals, registers, fields, and enumerated values — matching the data model used by svd2rust and embassy's chiptool:

{
  "part_details": { "part_number": "STM32F407VG", ... },
  "peripherals": [
    {
      "name": "SPI1",
      "base_address": "0x40013000",
      "registers": [
        {
          "name": "CR1",
          "offset": "0x00",
          "access": "read-write",
          "fields": [
            { "name": "SPE", "bit_offset": 6, "bit_width": 1, ... }
          ]
        }
      ]
    }
  ]
}

Motivation

Existing PAC generation relies on SVD files provided by chip vendors, which are often inaccurate, incomplete, or nonexistent (especially for domestic Chinese MCUs like GD32, WCH, etc.). This task enables generating PAC data directly from datasheets, with the output validated against existing stm32-rs / stm32-metapac data.

Build Note

mupdf-sys currently fails to compile on macOS 26.x (Xcode 17, clang 17) due to a fdopen macro conflict in bundled zlib. This is an existing issue unrelated to this PR. Consider pdfium-render as a cross-platform alternative.

[Copilot]

Pull request overview

Adds a new registers extraction task intended to produce a structured peripheral/register/field JSON output that can be used for Rust PAC generation workflows (e.g., svd2rust / chiptool).

Changes:

• Added a new ExtractTask::Registers CLI task wired to a new prompt spec.
• Introduced a new registers extraction prompt (prompts/extract-registers.md) with detailed anti-hallucination and output requirements.
• Added a JSON schema for the registers output shape in src/prompts.rs.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
src/prompts.rs	Adds PROMPT_REGISTERS and a new registers() prompt spec + JSON schema.
src/extract.rs	Adds the Registers task variant and routes it to prompts::registers().
prompts/extract-registers.md	New LLM prompt describing how to extract register maps and the expected JSON output.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The markdown tables in this prompt use || at the start of the header/separator rows (e.g. || Field | Requirement |), which renders as an extra empty column and can reduce clarity for the model. Update these to standard | Field | Requirement | / | --- | --- | formatting.

[Copilot]

In the field extraction section, the allowed access values list doesn't include read-writeOnce, but later the prompt instructs using read-writeOnce for write-1-to-clear flags. This is internally inconsistent; include read-writeOnce in the field access options (or clarify that it is only allowed at the register level).

[Copilot]

The prompt specifies an explicit error JSON shape when no register map is found, but the responseJsonSchema here only allows {part_details, peripherals}. With schema enforcement, the model can't return the documented error object and may be forced to fabricate data to satisfy the schema. Consider updating the schema to oneOf the success shape vs an {error, part_number, pages_searched} shape (or remove the error-response instruction from the prompt).

[Copilot]

The schema currently does not require several fields that the prompt marks as mandatory (e.g., part_details.datasheet_revision/description, register access/size/reset_value, field enumerated_values). If the JSON schema is meant to enforce output completeness, these should be added to the relevant required lists (and enumerated_values should be required with type: array, even if empty).

[Copilot]

Unlike the other prompt specs, this schema is parsed from a raw JSON string and uses expect(...), which would panic at runtime if edited incorrectly. For consistency and safer refactors, consider expressing this with json!({...}) (or at least .context(...) + ?) to avoid panics and keep the style consistent across prompt specs.

Suggested change

	}"#).expect("registers schema is valid JSON");
	}"#).unwrap_or_else(|e| panic!("registers schema JSON is invalid: {e}"));

[akiselev]

Have you tested this with microcontroller reference manuals? Any idea how it performs?

I'm hesitant to add this as an explicit extraction because LLMs have a hard time with exhaustiveness in these cases and this would be even less reliable than extractions can be.

Let me test this out with a project im working on

[ozongzi]

Can I modify the upstream crate to pdfium-render? Otherwise my Mac won't compile.

I plan to integrate svd2rust / chiptool to implement a complete datasheet -> PAC toolchain, but I'm not sure if I should implement it in this PR (maybe this change is too big, I should create a new crate instead).