Integration with RaspberryPi OS (Debian Bookworm 2025.05.13)

.gitignore

@@ -0,0 +1,26 @@
+# Build artifacts
+*.ko
+*.o
+*.mod
+*.mod.c
+.*.cmd
+modules.order
+Module.symvers
+.tmp_versions/
+
+# Device tree compiled files
+*.dtbo
+
+# Temporary files
+.lgd-nfy*
+*~
+*.swp
+*.swo
+
+# Editor files
+.vscode/
+.idea/
+
+# Backup files
+*.backup
+*.bak

Makefile

@@ -1,4 +1,26 @@
 #
 # Makefile for the kernel nfc device drivers.
+# Building I2C version only for aarch64
 #
-obj-y				+= nfc/
+
+KDIR := /lib/modules/$(shell uname -r)/build
+PWD := $(shell pwd)
+
+all: modules
+
+modules:
+	$(MAKE) -C $(KDIR) M=$(PWD) modules
+
+clean:
+	$(MAKE) -C $(KDIR) M=$(PWD) clean
+
+install:
+	$(MAKE) -C $(KDIR) M=$(PWD) modules_install
+
+# Module configuration
+obj-m += nxpnfc_i2c.o
+nxpnfc_i2c-objs := nfc/common.o nfc/i2c_drv.o
+
+# Enable I2C configuration
+ccflags-y += -DCONFIG_NXP_NFC_I2C=1
+ccflags-y += -Infc/

PN7160_SETUP_GUIDE.md

@@ -0,0 +1,248 @@
+# PN7160 NFC Setup Documentation
+
+## Overview
+This document describes the complete setup for the NXP PN7160 NFC controller on Raspberry Pi CM4 with automatic kernel module loading.
+
+## Hardware Configuration
+
+### I2C Connection (Default: I2C1)
+- **SDA**: GPIO2 (Pin 3)
+- **SCL**: GPIO3 (Pin 5)
+- **VCC**: 3.3V (Pin 1 or 17)
+- **GND**: Ground (Pin 6, 9, 14, 20, 25, 30, 34, or 39)
+
+### GPIO Pins Used
+- **IRQ (Interrupt)**: GPIO23 (Pin 16) 
+- **VEN (Voltage Enable)**: GPIO24 (Pin 18)
+- **FW_DWL (Firmware Download)**: GPIO25 (Pin 22) - Optional
+
+### I2C Address
+- **Default**: 0x28 (40 decimal)
+
+## Files Created/Modified
+
+### Device Tree Overlay
+- **Source**: `/home/alex/nxpnfc/pn7160-overlay.dts`
+- **Compiled**: `/boot/firmware/overlays/pn7160-overlay.dtbo`
+
+### Kernel Module
+- **Source**: `/home/alex/nxpnfc/nfc/`
+- **Built**: `/home/alex/nxpnfc/nxpnfc_i2c.ko`
+- **Installed**: `/lib/modules/6.12.47+rpt-rpi-v8/updates/nxpnfc_i2c.ko.xz`
+
+### Configuration Files Modified
+- **`/boot/firmware/config.txt`**: Added overlay and enabled I2C
+- **`/etc/modules`**: Added auto-loading of nxpnfc_i2c module
+
+## Build Process
+
+### Building the Kernel Module
+```bash
+cd /home/alex/nxpnfc
+make clean
+make
+```
+
+### Compiling Device Tree Overlay
+```bash
+dtc -@ -I dts -O dtb -o pn7160-overlay.dtbo pn7160-overlay.dts
+```
+
+### Installation
+```bash
+# Install kernel module
+sudo make install
+sudo depmod -a
+
+# Install device tree overlay
+sudo cp pn7160-overlay.dtbo /boot/firmware/overlays/
+
+# Add to auto-load modules
+echo "nxpnfc_i2c" | sudo tee -a /etc/modules
+
+# Set up device permissions for user access
+echo 'KERNEL=="nxpnfc", MODE="0666", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/99-nxpnfc.rules
+sudo udevadm control --reload-rules
+```
+
+## Configuration Details
+
+### config.txt Additions
+```
+dtparam=i2c_arm=on
+dtoverlay=pn7160-overlay
+```
+
+### Important Device Tree Properties
+The overlay uses specific NXP property names (critical for proper operation):
+- `nxp,nxpnfc-irq` - IRQ GPIO pin
+- `nxp,nxpnfc-ven` - VEN GPIO pin  
+- `nxp,nxpnfc-fw-dwnld` - Firmware download GPIO pin
+
+### Overlay Parameters (Optional Customization)
+You can customize GPIO pins by using parameters:
+```
+dtoverlay=pn7160-overlay,irq_pin=23,ven_pin=24,fw_dnld_pin=25,i2c_address=0x28
+```
+
+### Successful Probe Messages
+When working correctly, you should see these kernel messages:
+```
+nfc_parse_dt: irq 536
+nfc_parse_dt: 536, 537, 535
+nfc_i2c_dev_probe: requesting IRQ 55
+nfc_i2c_dev_probe: probing nfc i2c successfully
+```
+
+## Testing and Verification
+
+### After Reboot, Check:
+
+1. **I2C Bus Detection**:
+   ```bash
+   i2cdetect -l
+   i2cdetect -y 1
+   ```
+
+2. **Module Loading**:
+   ```bash
+   lsmod | grep nxpnfc
+   ```
+
+3. **Device Detection**:
+   ```bash
+   ls -la /dev/nxpnfc*
+   # Should show: crw-rw-rw- 1 root root 239, 0 <date> /dev/nxpnfc
+   ```
+
+4. **Kernel Messages**:
+   ```bash
+   dmesg | grep -i nfc
+   ```
+
+5. **Device Tree Info**:
+   ```bash
+   ls /proc/device-tree/soc/i2c@7e804000/
+   ```
+
+6. **Verify Working Setup**:
+   ```bash
+   # Should show UU at address 0x28
+   i2cdetect -y 1
+
+   # Should show pn7160-overlay
+   sudo dtoverlay -l
+
+   # Should show character device
+   ls -la /dev/nxpnfc*
+
+   # Should show successful probe messages
+   dmesg | grep "probing nfc i2c successfully"
+   ```
+
+## Troubleshooting
+
+### Common Issues:
+
+1. **No /dev/nxpnfc device**:
+   - Check hardware connections
+   - Verify I2C address with `i2cdetect -y 1` (should show "UU" at 0x28)
+   - Check GPIO pin connections
+   - Verify overlay is loaded: `sudo dtoverlay -l`
+
+2. **Module not loading**:
+   - Check `dmesg` for errors
+   - Verify module is in `/lib/modules/$(uname -r)/updates/`
+   - Try manual loading: `sudo modprobe nxpnfc_i2c`
+
+3. **GPIO parsing errors (irq gpio invalid -2)**:
+   - This indicates incorrect device tree property names
+   - Ensure overlay uses `nxp,nxpnfc-irq` (not `irq-gpio`)
+   - Recompile and reinstall overlay if modified
+
+4. **I2C communication errors**:
+   - Verify pull-up resistors on SDA/SCL (usually 4.7kΩ)
+   - Check power supply (3.3V)
+   - Verify ground connections
+   - Ensure I2C is enabled: `dtparam=i2c_arm=on`
+
+5. **Overlay not loading at boot**:
+   - Check `/boot/firmware/config.txt` for `dtoverlay=pn7160-overlay`
+   - Verify overlay file exists: `/boot/firmware/overlays/pn7160-overlay.dtbo`
+   - Check for syntax errors in config.txt
+
+6. **Permission denied accessing /dev/nxpnfc**:
+   - Verify udev rules: `cat /etc/udev/rules.d/99-nxpnfc.rules`
+   - Check device permissions: `ls -la /dev/nxpnfc`
+   - Should show mode 0666 (crw-rw-rw-)
+   - Reload udev rules: `sudo udevadm control --reload-rules`
+   - Replug device or reboot if needed
+
+### Manual Commands:
+
+```bash
+# Reload module manually
+sudo rmmod nxpnfc_i2c
+sudo modprobe nxpnfc_i2c
+
+# Check overlay loading
+sudo dtoverlay -l
+
+# Load overlay manually (for testing)
+sudo dtoverlay pn7160-overlay
+
+# Remove overlay manually (for testing)
+sudo dtoverlay -r pn7160-overlay
+
+# Scan I2C bus (should show "UU" at 0x28 when working)
+i2cdetect -y 1
+
+# Check device tree properties
+ls /proc/device-tree/soc/i2c@7e804000/pn7160@28/
+
+# Check GPIO usage
+sudo cat /sys/kernel/debug/gpio
+```
+
+## Hardware Setup Checklist
+
+- [ ] PN7160 connected to 3.3V power
+- [ ] Ground connections secure
+- [ ] SDA connected to GPIO2
+- [ ] SCL connected to GPIO3
+- [ ] IRQ connected to GPIO23
+- [ ] VEN connected to GPIO24
+- [ ] FW_DWL connected to GPIO25 (if used)
+- [ ] Pull-up resistors on I2C lines (if not on board)
+
+## Next Steps
+
+1. **Reboot the system** for all changes to take effect
+2. **Connect PN7160 hardware** according to the pin configuration
+3. **Test NFC functionality** using appropriate user-space libraries
+4. **Develop applications** using the `/dev/nxpnfc` character device
+
+## User Space Applications
+
+Popular NFC libraries that work with this setup:
+- **libnfc**: Open-source NFC library
+- **NXP NFC Stack**: Official NXP software
+- **Custom applications**: Direct character device access
+
+## Notes
+
+- The device tree overlay supports parameter customization for different GPIO configurations
+- The kernel module is built for kernel version 6.12.47+rpt-rpi-v8 (aarch64 architecture)
+- Code has been updated for newer kernel API compatibility (class_create, I2C driver signatures)
+- All configuration persists across reboots
+- Backup of original config.txt saved as `/boot/firmware/config.txt.backup`
+- GPIO numbers in Linux are offset: GPIO24 = linux gpio-536 (512+24)
+- The module creates `/dev/nxpnfc` character device with major number 236
+
+## Architecture Requirements
+
+- **Platform**: Raspberry Pi CM4 (or compatible aarch64 Raspberry Pi)
+- **Kernel**: 6.12.x series (tested on 6.12.47+rpt-rpi-v8)
+- **Architecture**: ARM aarch64
+- **I2C**: Hardware I2C1 bus (GPIO2/GPIO3)
+- **Compiler**: GCC 12.2.0 (or compatible)