peripherals-from-datasheet

Name: peripherals-from-datasheet
Author: mohitmishra786

141stars19forks

How to install peripherals-from-datasheet?

mohitmishra786/low-level-dev-skills/peripherals-from-datasheet

$npx -y skills add mohitmishra786/low-level-dev-skills --skill peripherals-from-datasheet

Installs into the current project.

Summary

Peripheral driver methodology skill from MCU reference manuals. Use when reading register maps, timing diagrams, and writing drivers from vendor documentation. Activates on queries about reference manual, register map, peripheral init sequence, or datasheet-driven driver design.

Files · 1

View on GitHub

SKILL.md

1	# Peripherals from Datasheet
2
3	## Purpose
4
5	Guide agents through a repeatable methodology for writing peripheral drivers from MCU reference manuals: locating register maps, interpreting bit definitions, following init sequences, respecting timing constraints, and producing maintainable register-level code. Pair with `skills/baremetal/datasheet-and-refmanual-reading` for doc-navigation methodology (kept as separate skills).
6
7	## When to Use
8
9	- Starting a driver without vendor HAL
10	- Porting a peripheral between MCU families
11	- Verifying HAL behavior against the reference manual
12	- Debugging a peripheral that "should work" per examples
13
14	## Workflow
15
16	### 1. Reference manual navigation
17
18	```
19	Typical RM structure
20	├── Memory map (peripheral base addresses)
21	├── Peripheral chapter (UART, SPI, GPIO, ...)
22	│ ├── Functional description
23	│ ├── Register map (table of offsets)
24	│ ├── Register bit definitions
25	│ └── Timing / electrical notes
26	└── Electrical characteristics (clock limits, setup/hold)
27	```
28
29	Start with the programming model section before copying register writes.
30
31	### 2. Extract register map
32
33	```c
34	/* From RM — USART base 0x40004400 */
35	typedef struct {
36	volatile uint32_t SR; /* 0x00 status */
37	volatile uint32_t DR; /* 0x04 data */
38	volatile uint32_t BRR; /* 0x08 baud */
39	volatile uint32_t CR1; /* 0x0C control */
40	/* ... */
41	} USART_TypeDef;
42
43	#define USART2 ((USART_TypeDef *)0x40004400UL)
44	```
45
46	Verify offset column matches struct layout (padding for reserved words).
47
48	### 3. Init sequence checklist
49
50	```
51	Peripheral bring-up order
52	├── 1. Enable bus clock (RCC/APB/AHB register)
53	├── 2. Reset peripheral (if RM requires)
54	├── 3. Configure pins (GPIO alternate function)
55	├── 4. Configure peripheral registers (mode, baud, etc.)
56	├── 5. Enable peripheral (UE, TE, RE bits)
57	├── 6. Enable NVIC IRQ (if interrupt-driven)
58	└── 7. Verify status flags before first transaction
59	```
60
61	Bad — enable UART before clock:
62
63	```c
64	USART2->CR1 \|= USART_CR1_UE; /* USART clock still off — no effect */
65	```
66
67	### 4. Bit definition discipline
68
69	```c
70	/* From RM: CR1 M[1:0], PCE, PS, TE, RE, UE */
71	#define USART_CR1_UE (1U << 13)
72	#define USART_CR1_TE (1U << 3)
73	#define USART_CR1_RE (1U << 2)
74	```
75
76	Document RM section number in comment for audit trail.
77
78	### 5. Timing and busy-wait
79
80	```c
81	/* RM: poll BUSY flag until reset complete */
82	while (RCC->CR & RCC_CR_PLLRDY == 0)
83	;
84	```
85
86	Respect startup times (oscillator settle, PLL lock) from electrical characteristics chapter.
87
88	### 6. Good vs bad driver structure
89
90	Good — layered, RM-referenced:
91
92	```c
93	void usart2_init(uint32_t baud) {
94	rcc_enable_usart2();
95	gpio_config_usart2_pins();
96	usart2_set_baud(baud);
97	USART2->CR1 = USART_CR1_TE \| USART_CR1_RE \| USART_CR1_UE;
98	}
99	```
100
101	Bad — magic numbers, no clock enable:
102
103	```c
104	(uint32_t)0x4000440C = 0x2000; /* what peripheral? which bit? */
105	```
106
107	### 7. Agent usage examples
108
109	```
110	/peripherals-from-datasheet Walk me through USART init from STM32 RM
111	/peripherals-from-datasheet What sections of the ref manual matter for SPI timing?
112	```
113
114	## Common Problems
115
116	\| Symptom \| Cause \| Fix \|
117	\|---------\|-------\|-----\|
118	\| Peripheral dead \| Clock not enabled \| RCC/APB enable bit first \|
119	\| Wrong baud rate \| PCLK assumption wrong \| Recompute using actual clock tree \|
120	\| GPIO AF wrong \| MUX value from wrong table \| Cross-check pinout + AF table \|
121	\| IRQ stuck \| Status flag clear sequence wrong \| RM "clearing flags" subsection \|
122	\| Silent data corruption \| Endian or width mismatch \| Match register access size \|
123
124	## Related Skills
125
126	- `skills/baremetal/datasheet-and-refmanual-reading` — fast RM navigation
127	- `skills/baremetal/mmio-and-bit-manipulation` — register access patterns
128	- `skills/baremetal/gpio-baremetal` — pin mux before peripheral enable
129	- `skills/embedded/linker-scripts` — memory map alignment

People who liked this also viewed

6 picks

Type

peripherals-from-datasheet

141stars19forks

View on GitHub

How to install peripherals-from-datasheet?

mohitmishra786/low-level-dev-skills/peripherals-from-datasheet

$npx -y skills add mohitmishra786/low-level-dev-skills --skill peripherals-from-datasheet

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Peripherals from Datasheet
2
3	## Purpose
4
5	Guide agents through a repeatable methodology for writing peripheral drivers from MCU reference manuals: locating register maps, interpreting bit definitions, following init sequences, respecting timing constraints, and producing maintainable register-level code. Pair with `skills/baremetal/datasheet-and-refmanual-reading` for doc-navigation methodology (kept as separate skills).
6
7	## When to Use
8
9	- Starting a driver without vendor HAL
10	- Porting a peripheral between MCU families
11	- Verifying HAL behavior against the reference manual
12	- Debugging a peripheral that "should work" per examples
13
14	## Workflow
15
16	### 1. Reference manual navigation
17
18	```
19	Typical RM structure
20	├── Memory map (peripheral base addresses)
21	├── Peripheral chapter (UART, SPI, GPIO, ...)
22	│ ├── Functional description
23	│ ├── Register map (table of offsets)
24	│ ├── Register bit definitions
25	│ └── Timing / electrical notes
26	└── Electrical characteristics (clock limits, setup/hold)
27	```
28
29	Start with the programming model section before copying register writes.
30
31	### 2. Extract register map
32
33	```c
34	/* From RM — USART base 0x40004400 */
35	typedef struct {
36	volatile uint32_t SR; /* 0x00 status */
37	volatile uint32_t DR; /* 0x04 data */
38	volatile uint32_t BRR; /* 0x08 baud */
39	volatile uint32_t CR1; /* 0x0C control */
40	/* ... */
41	} USART_TypeDef;
42
43	#define USART2 ((USART_TypeDef *)0x40004400UL)
44	```
45
46	Verify offset column matches struct layout (padding for reserved words).
47
48	### 3. Init sequence checklist
49
50	```
51	Peripheral bring-up order
52	├── 1. Enable bus clock (RCC/APB/AHB register)
53	├── 2. Reset peripheral (if RM requires)
54	├── 3. Configure pins (GPIO alternate function)
55	├── 4. Configure peripheral registers (mode, baud, etc.)
56	├── 5. Enable peripheral (UE, TE, RE bits)
57	├── 6. Enable NVIC IRQ (if interrupt-driven)
58	└── 7. Verify status flags before first transaction
59	```
60
61	Bad — enable UART before clock:
62
63	```c
64	USART2->CR1 \|= USART_CR1_UE; /* USART clock still off — no effect */
65	```
66
67	### 4. Bit definition discipline
68
69	```c
70	/* From RM: CR1 M[1:0], PCE, PS, TE, RE, UE */
71	#define USART_CR1_UE (1U << 13)
72	#define USART_CR1_TE (1U << 3)
73	#define USART_CR1_RE (1U << 2)
74	```
75
76	Document RM section number in comment for audit trail.
77
78	### 5. Timing and busy-wait
79
80	```c
81	/* RM: poll BUSY flag until reset complete */
82	while (RCC->CR & RCC_CR_PLLRDY == 0)
83	;
84	```
85
86	Respect startup times (oscillator settle, PLL lock) from electrical characteristics chapter.
87
88	### 6. Good vs bad driver structure
89
90	Good — layered, RM-referenced:
91
92	```c
93	void usart2_init(uint32_t baud) {
94	rcc_enable_usart2();
95	gpio_config_usart2_pins();
96	usart2_set_baud(baud);
97	USART2->CR1 = USART_CR1_TE \| USART_CR1_RE \| USART_CR1_UE;
98	}
99	```
100
101	Bad — magic numbers, no clock enable:
102
103	```c
104	(uint32_t)0x4000440C = 0x2000; /* what peripheral? which bit? */
105	```
106
107	### 7. Agent usage examples
108
109	```
110	/peripherals-from-datasheet Walk me through USART init from STM32 RM
111	/peripherals-from-datasheet What sections of the ref manual matter for SPI timing?
112	```
113
114	## Common Problems
115
116	\| Symptom \| Cause \| Fix \|
117	\|---------\|-------\|-----\|
118	\| Peripheral dead \| Clock not enabled \| RCC/APB enable bit first \|
119	\| Wrong baud rate \| PCLK assumption wrong \| Recompute using actual clock tree \|
120	\| GPIO AF wrong \| MUX value from wrong table \| Cross-check pinout + AF table \|
121	\| IRQ stuck \| Status flag clear sequence wrong \| RM "clearing flags" subsection \|
122	\| Silent data corruption \| Endian or width mismatch \| Match register access size \|
123
124	## Related Skills
125
126	- `skills/baremetal/datasheet-and-refmanual-reading` — fast RM navigation
127	- `skills/baremetal/mmio-and-bit-manipulation` — register access patterns
128	- `skills/baremetal/gpio-baremetal` — pin mux before peripheral enable
129	- `skills/embedded/linker-scripts` — memory map alignment

People who liked this also viewed

6 picks

Type