> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Register lookup

> Resolve SVD peripheral registers and bit fields on the connected target before reading or changing live memory-mapped register state in a session.

Use `register_lookup` to answer what a register means. Use GDB to answer what value the target holds. Keeping those steps separate prevents a reset value from being reported as a live measurement.

## Load SVD data

Embedder loads SVD-derived device data for the project's selected platform. It checks the local `.embedder/svd-cache` first, then fetches project SVD data when the platform provides it.

The register tool is available only when at least one valid device is loaded. Refresh the project metadata if `register_lookup` reports:

```text theme={"system"}
No SVD data loaded. The project does not have an SVD file, or it could not be parsed.
```

When several devices are loaded, results include a device tag. State which MCU or core you intend to inspect.

## Browse a peripheral

Ask for a peripheral name to list its registers:

```text theme={"system"}
Look up the RCC peripheral and show each register address and access type.
```

The result includes:

* Peripheral base address
* Register address, width, and access type
* Register and field descriptions when present
* Bit ranges when you request fields

Peripheral and register names are matched case-insensitively. If an exact name fails, Embedder can suggest a close SVD name.

## Inspect one register

Give both the peripheral and register:

```text theme={"system"}
Look up RCC CR with fields. Return its absolute address, reset value, access
type, and every enumerated field value in the loaded SVD.
```

An SVD register can define these access rules:

* `read-only`
* `write-only`
* `read-write`
* `writeOnce`
* `read-writeOnce`

Do not write a register until you have checked its register-level and field-level access information. A read-modify-write can be unsafe on write-one-to-clear or side-effect fields even when the containing register is marked read-write; rely on the device reference when the SVD lacks that detail.

## Search by purpose

Use a free-text query when you do not know the peripheral name:

```text theme={"system"}
Search the loaded SVDs for "baud rate" and show fields for the closest matches.
```

Search matches register names and descriptions, then falls back to fuzzy matching. It returns at most 50 results. When five or fewer registers match, the result includes detailed fields unless you disable them.

Repeat the lookup with an exact peripheral and register before you read hardware.

## Read the live value

<Steps>
  <Step title="Resolve the definition">
    Look up the register in the SVD and record the device, absolute address, width, access type, and field layout.
  </Step>

  <Step title="Preserve the target when needed">
    Ask for an attach-only GDB session if programming or reset would destroy the state you are investigating.
  </Step>

  <Step title="Read the value">
    Use a structured GDB expression or a raw memory read with the SVD width.
  </Step>

  <Step title="Decode supported fields">
    Apply only the masks, shifts, enum values, and access semantics present in the selected SVD or device reference.
  </Step>
</Steps>

```text theme={"system"}
Look up the target's reset-cause register in the loaded SVD. Attach without
programming, read its live value once, and decode the asserted fields. Do not
clear the register.
```

Reading a peripheral register can have side effects on some MCUs. If the reference marks a register read-to-clear, ask before reading it or use a captured copy maintained by firmware.

## Compare several cores or devices

When a project loads more than one SVD, the same peripheral name may exist in several address spaces. Ask for the device explicitly:

```text theme={"system"}
Search every loaded SVD for IPC status, then use only the device entry that
matches core 0.
```

Do not combine a base address from one SVD with fields from another.

## Check register accesses in code

When SVD data is loaded, file-write validation can inspect changed C, Rust, and Python register accesses. It reports:

* A write to a read-only register
* A read from a write-only register
* An unknown peripheral or register
* A literal address that does not map to a known register

These diagnostics check SVD consistency. They do not prove that an access is synchronized, clocked, or safe for the current power state.

## Fix lookup problems

<AccordionGroup>
  <Accordion title="No SVD is loaded">
    Confirm the project platform and MCU selection. Reopen or refresh the project so Embedder can load its cached or remote SVD data.
  </Accordion>

  <Accordion title="The peripheral name is not found">
    Search by function or accept the fuzzy suggestion, then verify the suggested peripheral against the selected device.
  </Accordion>

  <Accordion title="The address disagrees with the datasheet">
    Check the SVD device name and silicon revision. Stop before reading or writing when the selected SVD does not match the target.
  </Accordion>

  <Accordion title="The reset value differs from hardware">
    Reset values describe the SVD's reset state. Clock, boot ROM, firmware, and debugger actions may have changed the live register before you read it.
  </Accordion>

  <Accordion title="A field is missing">
    Do not invent a mask. Use the device reference or another authoritative SVD for the exact target revision.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="GDB debugging" icon="bug" href="/debug-mode/gdb">
    Read the live register after you resolve its definition.
  </Card>

  <Card title="Combined workflows" icon="diagram-project" href="/debug-mode/combined-workflows">
    Compare register evidence with logs and waveforms.
  </Card>
</CardGroup>