Getting Started¶

Prerequisites¶

Tool	Version	Purpose
GCC	≥ 9.0	C11 compiler with atomics support
Make	≥ 4.0	Build system
Linux kernel	≥ 5.4	Full feature support (epoll, timerfd, SocketCAN, GPIO chardev)
git	≥ 2.25	Version control

Optional (for testing)¶

Tool	Purpose
`socat`	Virtual UART pairs for serial testing
`can-utils`	SocketCAN utilities (`candump`, `cansend`)
`i2c-tools`	I2C bus scan and probe
`valgrind`	Memory leak detection
`perf`	Performance profiling
`mkdocs`	Documentation preview

Clone & Build¶

# Clone the repository
git clone https://github.com/GauravAgarwalGarg/Protocols.git
cd Protocols

# Build a specific module
make -C src/network/raw_socket
make -C src/network/epoll_reactor
make -C src/embedded/uart
make -C src/embedded/spi
make -C src/embedded/i2c
make -C src/embedded/can
make -C src/embedded/gpio
make -C src/concurrency/ring_buffer
make -C src/concurrency/spsc_queue
make -C src/concurrency/memory_pool
make -C src/industrial/modbus

# Build all (if top-level Makefile exists)
make all

Project Structure¶

Protocols/
├── src/
│   ├── network/
│   │   ├── raw_socket/       # AF_PACKET Layer-2 access
│   │   ├── epoll_reactor/    # Event loop + timers
│   │   ├── zero_copy/        # (planned) io_uring, splice
│   │   └── dpdk/             # (planned) Userspace NIC
│   ├── embedded/
│   │   ├── uart/             # RS-232/485 serial
│   │   ├── spi/              # SPI master (spidev)
│   │   ├── i2c/              # I2C bus (i2c-dev)
│   │   ├── can/              # CAN/FD (SocketCAN)
│   │   └── gpio/             # GPIO chardev
│   ├── concurrency/
│   │   ├── ring_buffer/      # SPSC lock-free ring
│   │   ├── spsc_queue/       # Zero-copy claim/publish
│   │   └── memory_pool/      # CAS-based freelist
│   ├── transport/
│   │   ├── tcp_stack/        # (planned) Userspace TCP
│   │   ├── udp_multicast/    # (planned) Multicast groups
│   │   └── quic/             # (planned) QUIC 0-RTT
│   ├── industrial/
│   │   ├── modbus/           # Modbus RTU/TCP
│   │   ├── ethercat/         # (planned) EtherCAT master
│   │   └── profinet/         # (planned) PROFINET RT
│   └── aerospace/
│       ├── arinc429/         # ARINC 429 databus
│       ├── arinc615a/        # ARINC 615A data loading
│       ├── arinc664/         # AFDX (Avionics Full-Duplex)
│       ├── arinc653/         # (planned) ARINC 653 partitioning
│       └── arinc665/         # (planned) ARINC 665 load format
├── tests/                    # Test programs
├── docs/                     # MkDocs documentation
└── README.md

Running Tests¶

Virtual UART¶

# Create a virtual serial pair
socat -d -d pty,raw,echo=0 pty,raw,echo=0 &
# Use the reported /dev/pts/N paths in your test

Virtual CAN¶

# Create virtual CAN interface
sudo modprobe vcan
sudo ip link add dev vcan0 type vcan
sudo ip link set up vcan0

# Monitor CAN traffic
candump vcan0 &

# Run CAN test
./build/can_demo

Network (Raw Socket)¶

# Grant capability (avoids running as root)
sudo setcap cap_net_raw+ep ./build/raw_socket_demo

# Or create a network namespace for isolation
sudo ip netns add test_ns
sudo ip link add veth0 type veth peer name veth1
sudo ip link set veth1 netns test_ns
sudo ip link set up veth0
sudo ip netns exec test_ns ip link set up veth1

Documentation¶

# Install MkDocs with Material theme
pip install mkdocs mkdocs-material

# Serve documentation locally
mkdocs serve

# Build static site
mkdocs build

Development Workflow¶

Pick a module Check the module status table for planned items
Read the contract Every module must satisfy the Module Contract
Follow the standards See Coding Standards
Implement header-first Write the .h file with full API documentation before .c
Write a demo Every module includes a self-contained demo in its .c file
Test without hardware Use virtual interfaces (vcan, socat PTY, veth) for CI
Submit PR One module per PR, with passing tests

Submitting Changes¶

# Create a feature branch
git checkout -b feature/my-new-module

# Make your changes
# ... edit files ...

# Commit with descriptive message
git add src/category/my_module/
git commit -m "Add my_module: brief description of what it does"

# Push and create PR
git push -u origin feature/my-new-module

Troubleshooting¶

Common Issues

Permission denied on raw socket:

sudo setcap cap_net_raw+ep ./build/raw_socket_demo

Cannot open /dev/ttyUSB0:

sudo usermod -aG dialout $USER
# Log out and back in

No /dev/spidev*:

sudo modprobe spidev
# Check device tree overlay is enabled

VCAN interface not found:

sudo modprobe vcan
sudo ip link add dev vcan0 type vcan
sudo ip link set up vcan0