The NXP UM11126 manual for the LPC55S6x spans 1,063 pages, while the STM32H743 reference manual reaches 3,355. Finding the I2C register map means searching through hundreds of pages written for documentation, not firmware work. Embedd's parser connects those two worlds, and the source material is less orderly than it first appears.
This is a practical account of our parsing work: what we built, where it failed, and how we addressed those failures. The pipeline does not process every document perfectly. We will show where it performs well, where it has trouble, and why.
What a PDF structure really contains
A PDF consists of content streams plus a cross-reference table. Page streams contain drawing instructions for text positions, fonts, paths, and images, but no meaning-based hierarchy. "Offset" in a register-table header and "Offset" in a footnote look the same there: a font resource, a location, and a text string.
Technical datasheets are often produced with FrameMaker, InDesign, or DITA publishing systems. These can create tagged PDFs with structure trees for documents, sections, paragraphs, tables, rows, and cells. When that tagging is correct, we can follow the tree and locate tables with high confidence. NXP UM11126 is well tagged, so it is comparatively simple to parse.
Many embedded datasheets are not tagged properly. Older ST reference manuals, Renesas RA-family datasheets up to around 2021, and nearly all Microchip PIC32 datasheets are untagged or have incorrect table boundaries. We use position-based table detection for those files.
Finding registers from page layout
Across most MCU datasheets, register tables share a visual pattern: hexadecimal offsets on the left, register names next, several bit-field columns, and descriptions on the right. Rows commonly alternate between a bit-layout row, with 31 through 0 and field names or "Reserved," and a description row containing access information and explanatory text.
Our position-based detector runs in two stages. First, it groups text by vertical position to rebuild rows. Next, it searches for likely register tables: at least four columns, a first column whose values parse as hexadecimal with a regular stride such as 0x00, 0x04, 0x08, or similar, and a column containing bit-field-style names, meaning all-caps, underscore-separated values from 2 to 16 characters.
The method performs well on familiar layouts, but vendors may reorder columns, put the offset elsewhere, or use decimal register addresses. Nordic Semiconductor's nRF52840 Product Specification places the address offset after the register name. We test several possible column orders and score them by how consistently the address-like column progresses in a linear stride.
Rebuilding tables across pages
Tables spanning pages are among the pipeline's most difficult cases. A viewer may show repeated column headers at the top of page two, add "(Continued)," or provide no continuation marker. The position-based detector therefore sees two similar tables on neighboring pages instead of one.
We look for three signs of a split table. First, the final address on one page is not an obvious endpoint, such as a round number followed by a gap to another peripheral block. Second, the next page begins with an address one stride beyond that final row. Third, both candidates share the same column count and widths within a tolerance.
All three signals cause an automatic merge. With two, we mark the result as a candidate and store a confidence level in the internal register model. Below the threshold, the generated driver adds a comment saying that the boundary register came from a split table and needs checking against the datasheet.
Interpreting unclear bitfield descriptions
The hardest cases are often semantic rather than structural. Take "Reserved, do not write 1 to these bits." Is the field read-only, or is it write-zero? ARM Cortex-M defines both behaviors, and they affect read-modify-write operations differently. "Do not write 1" points toward write-zero, while "Reserved" by itself generally points toward read-only. Datasheet wording varies.
Our semantic layer matches descriptions against a vocabulary of phrases collected from hundreds of register descriptions. Each phrase maps to probabilities for the possible access modes. "Reserved, must be written as 0" maps to WZ with high confidence. "Reserved" alone maps to RO with moderate confidence. "Should be zero for normal operation" maps to WZ and RO differently depending on whether the surrounding register controls something or reports status.
Below the confidence threshold, the generated driver uses a conservative default: read-modify-write with a zero mask for the unclear fields. Existing values are preserved rather than forcing either interpretation. This can still be incorrect, so a firmware engineer can change the behavior after confirming the access mode in the silicon documentation.
Overlapping bit definitions
Some datasheets assign the same bit positions to two fields. Usually, a later revision added a replacement without removing the earlier definition, or a renamed field appears under both names. The parser records this as a conflict in its internal register model.
For an overlap, we place a warning in the output header and generate accessor macros for both field names, with both pointing to the shared positions. The init function chooses the first definition encountered, normally the newer one according to table order, and adds a build-time diagnostic comment about the conflict. We found this in three Renesas RA datasheets and two Microchip SAM70 peripherals. In each case, the surrounding datasheet text revealed the correct answer, but finding it required semantic reading rather than table scanning.
Scanned and image-only PDFs
A small share of uploaded files are image-only PDFs, either scans of paper documents or exports that rasterize every page. They have no text for extraction. We identify them during ingest and return an error instead of parsing them. Embedd does not run OCR on scanned datasheets because firmware-accurate register maps demand more precision than general-purpose OCR can reliably deliver. An incorrect bitfield is worse than no bitfield.
This remains a real limitation: Embedd cannot process a scanned datasheet today. For most chips in active production from NXP, ST, TI, Nordic, Renesas, and Microchip, searchable PDFs are available from the vendor. If a chip only has a scan, request a searchable copy or use Embedd's manual register entry interface to enter the register model directly.
The parser's output
Parsing produces an internal JSON register model containing the peripheral name, base address, registers with offsets and widths, and each register's fields with positions, widths, access modes, reset values, and descriptions. Code generation takes this model as its input.
Every field receives a confidence score, and the model records notes for decisions made by the extractor. When confidence falls below the verification threshold, those notes appear as comments in the generated header. The engineer gets a focused checklist for datasheet review instead of having to inspect the entire output from the beginning.
