# lcgamboa/picsim architecture

> Architecture diagram of the GitHub repository lcgamboa/picsim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lcgamboa/picsim
- Repository: https://github.com/lcgamboa/picsim

## Overview

PICsim is a C library and standalone simulator for PIC microcontrollers. Its principal workflow is to select/configure a supported device, load firmware, execute instructions while advancing family-specific peripherals, and expose simulated pins and serial communication to a host. The graph preserves the documented hardware capabilities and separates core execution, device models, peripherals, and external I/O. Many peripheral modules are indexed but not excerpted, so their internal call wiring is not asserted.

Main entry points: [`src/periferic18.c`](https://github.com/lcgamboa/picsim/blob/master/src/periferic18.c) (PIC18 peripherals), [`include/picsim.h`](https://github.com/lcgamboa/picsim/blob/master/include/picsim.h) (PIC state and API), [`src/periferic16.c`](https://github.com/lcgamboa/picsim/blob/master/src/periferic16.c) (PIC16 peripherals), [`src/common/serial.c`](https://github.com/lcgamboa/picsim/blob/master/src/common/serial.c) (USART emulation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Simulation core"]
  node_engine["PIC execution<br/>[p16fxxx.c]"]
  node_enhanced["Enhanced execution<br/>[p16fxxxe.c]"]
  node_pic18exec["PIC18 execution<br/>[p18fxxx.c]"]
  node_state["PIC state and API<br/>[picsim.h]"]
  node_hex["HEX firmware<br/>[hexfile.c]"]
end

subgraph group_devices["PIC device models"]
  node_devices16["PIC16 models"]
  node_device18["PIC18 models<br/>[PIC18F67J94.c]"]
end

subgraph group_peripherals["Hardware peripherals"]
  node_p16family["PIC16 peripherals<br/>[periferic16.c]"]
  node_p16efamily["Enhanced peripherals<br/>[periferic16e.c]"]
  node_p18family["PIC18 peripherals<br/>[periferic18.c]"]
  node_adc["ADC conversion<br/>[p16_adc.c]"]
  node_eeprom["EEPROM<br/>[p16_eeprom.c]"]
  node_timers["Timers and watchdog<br/>[p18_tmr1.c]"]
  node_interrupts["Interrupt handling<br/>[p18_interrupt.c]"]
  node_mssp["MSSP and CCP<br/>[p18_mssp.c]"]
  node_pps["Pin routing<br/>[p16e_pps_out.c]"]
end

subgraph group_io["Host I/O"]
  node_serial["USART emulation<br/>[serial.c]"]
  node_bitbang["Bit-banged UART<br/>[bitbang_uart.c]"]
end

node_host(("Embedding host"))
node_ports(("Serial device"))

node_host -.->|"uses API"| node_state
node_host -.->|"loads firmware"| node_hex
node_state -.->|"selects model"| node_devices16
node_state -.->|"selects model"| node_device18
node_devices16 -.->|"configures execution"| node_engine
node_device18 -.->|"configures execution"| node_pic18exec
node_engine -.->|"advances peripherals"| node_p16family
node_enhanced -.->|"advances peripherals"| node_p16efamily
node_pic18exec -.->|"advances peripherals"| node_p18family
node_p16family -.->|"dispatches"| node_adc
node_p16family -.->|"dispatches"| node_eeprom
node_p18family -.->|"dispatches"| node_timers
node_p18family -.->|"dispatches"| node_interrupts
node_p18family -.->|"dispatches"| node_mssp
node_p16efamily -.->|"dispatches"| node_pps
node_serial -->|"sends bytes"| node_bitbang
node_serial -->|"reads and writes"| node_ports

click node_engine "https://github.com/lcgamboa/picsim/blob/master/src/p16fxxx.c"
click node_enhanced "https://github.com/lcgamboa/picsim/blob/master/src/p16fxxxe.c"
click node_pic18exec "https://github.com/lcgamboa/picsim/blob/master/src/p18fxxx.c"
click node_state "https://github.com/lcgamboa/picsim/blob/master/include/picsim.h"
click node_hex "https://github.com/lcgamboa/picsim/blob/master/src/hexfile.c"
click node_devices16 "https://github.com/lcgamboa/picsim/tree/master/src/pics"
click node_device18 "https://github.com/lcgamboa/picsim/blob/master/src/pics/PIC18F67J94.c"
click node_p16family "https://github.com/lcgamboa/picsim/blob/master/src/periferic16.c"
click node_p16efamily "https://github.com/lcgamboa/picsim/blob/master/src/periferic16e.c"
click node_p18family "https://github.com/lcgamboa/picsim/blob/master/src/periferic18.c"
click node_adc "https://github.com/lcgamboa/picsim/blob/master/src/p16/p16_adc.c"
click node_eeprom "https://github.com/lcgamboa/picsim/blob/master/src/p16/p16_eeprom.c"
click node_timers "https://github.com/lcgamboa/picsim/blob/master/src/p18/p18_tmr1.c"
click node_interrupts "https://github.com/lcgamboa/picsim/blob/master/src/p18/p18_interrupt.c"
click node_mssp "https://github.com/lcgamboa/picsim/blob/master/src/p18/p18_mssp.c"
click node_pps "https://github.com/lcgamboa/picsim/blob/master/src/p16e/p16e_pps_out.c"
click node_serial "https://github.com/lcgamboa/picsim/blob/master/src/common/serial.c"
click node_bitbang "https://github.com/lcgamboa/picsim/blob/master/src/common/bitbang_uart.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_engine,node_enhanced,node_pic18exec,node_state,node_hex toneBlue
class node_devices16,node_device18 toneAmber
class node_p16family,node_p16efamily,node_p18family,node_adc,node_eeprom,node_timers,node_interrupts,node_mssp,node_pps toneMint
class node_serial,node_bitbang toneRose
class node_host,node_ports toneIndigo
```

## Components

### Simulation core

- [PIC execution](https://github.com/lcgamboa/picsim/blob/master/src/p16fxxx.c): `src/p16fxxx.c`
- [Enhanced execution](https://github.com/lcgamboa/picsim/blob/master/src/p16fxxxe.c): `src/p16fxxxe.c`
- [PIC18 execution](https://github.com/lcgamboa/picsim/blob/master/src/p18fxxx.c): `src/p18fxxx.c`
- [PIC state and API](https://github.com/lcgamboa/picsim/blob/master/include/picsim.h): `include/picsim.h`
- [HEX firmware](https://github.com/lcgamboa/picsim/blob/master/src/hexfile.c): `src/hexfile.c`

### PIC device models

- [PIC16 models](https://github.com/lcgamboa/picsim/tree/master/src/pics): `src/pics`
- [PIC18 models](https://github.com/lcgamboa/picsim/blob/master/src/pics/PIC18F67J94.c): `src/pics/PIC18F67J94.c`

### Hardware peripherals

- [PIC16 peripherals](https://github.com/lcgamboa/picsim/blob/master/src/periferic16.c): `src/periferic16.c`
- [Enhanced peripherals](https://github.com/lcgamboa/picsim/blob/master/src/periferic16e.c): `src/periferic16e.c`
- [PIC18 peripherals](https://github.com/lcgamboa/picsim/blob/master/src/periferic18.c): `src/periferic18.c`
- [ADC conversion](https://github.com/lcgamboa/picsim/blob/master/src/p16/p16_adc.c): `src/p16/p16_adc.c`
- [EEPROM](https://github.com/lcgamboa/picsim/blob/master/src/p16/p16_eeprom.c): `src/p16/p16_eeprom.c`
- [Timers and watchdog](https://github.com/lcgamboa/picsim/blob/master/src/p18/p18_tmr1.c): `src/p18/p18_tmr1.c`
- [Interrupt handling](https://github.com/lcgamboa/picsim/blob/master/src/p18/p18_interrupt.c): `src/p18/p18_interrupt.c`
- [MSSP and CCP](https://github.com/lcgamboa/picsim/blob/master/src/p18/p18_mssp.c): `src/p18/p18_mssp.c`
- [Pin routing](https://github.com/lcgamboa/picsim/blob/master/src/p16e/p16e_pps_out.c): `src/p16e/p16e_pps_out.c`

### Host I/O

- [USART emulation](https://github.com/lcgamboa/picsim/blob/master/src/common/serial.c): `src/common/serial.c`
- [Bit-banged UART](https://github.com/lcgamboa/picsim/blob/master/src/common/bitbang_uart.c): `src/common/bitbang_uart.c`

### Other components

- **Embedding host**
- **Serial device**

## Connections

- Embedding host → PIC state and API: uses API (evidence: `README.md`)
- Embedding host → HEX firmware: loads firmware (evidence: `README.md`)
- PIC state and API → PIC16 models: selects model (evidence: `include/picsim.h`)
- PIC state and API → PIC18 models: selects model (evidence: `include/picsim.h`)
- PIC16 models → PIC execution: configures execution (evidence: `src/pics/PIC16F18855.c`)
- PIC18 models → PIC18 execution: configures execution (evidence: `src/pics/PIC18F67J94.c`)
- PIC execution → PIC16 peripherals: advances peripherals
- Enhanced execution → Enhanced peripherals: advances peripherals
- PIC18 execution → PIC18 peripherals: advances peripherals
- PIC16 peripherals → ADC conversion: dispatches
- PIC16 peripherals → EEPROM: dispatches
- PIC18 peripherals → Timers and watchdog: dispatches
- PIC18 peripherals → Interrupt handling: dispatches
- PIC18 peripherals → MSSP and CCP: dispatches
- Enhanced peripherals → Pin routing: dispatches
- USART emulation → Bit-banged UART: sends bytes (evidence: `src/common/serial.c`)
- USART emulation → Serial device: reads and writes (evidence: `src/common/serial.c`)
