From d759b35a718bbbd7782d66c51d6379936a824c61 Mon Sep 17 00:00:00 2001
From: stefanrueger <stefan.rueger@urclocks.com>
Date: Thu, 23 Oct 2025 15:00:48 +0200
Subject: [PATCH] Document pickit5 -P port use

---
 src/avrdude.1        |  9 ++++++++-
 src/doc/avrdude.texi | 12 ++++++++++--
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/src/avrdude.1 b/src/avrdude.1
index f39223c1..cd98507c 100644
--- a/src/avrdude.1
+++ b/src/avrdude.1
@@ -690,11 +690,18 @@ numbers, multiple devices can be distinguished by their location in the
 USB hierarchy using -P usb:<bus>:<device>.
 .Pp
 For USBasp, multiple devices can also be also distinguished using -P
-usb:<bus>:<device> or using the serial number -P usb:<serial>. For
+usb:<bus>:<device> or using the serial number -P usb:<serialno>. For
 examples, see the respective
 .Em Troubleshooting
 entry in the detailed pdf documentation.
 .Pp
+The -c pickit5 programmer allows overriding the product ID with a
+hexadecimal number <pid> using -P usb::<pid> and the vendor and product
+IDs with hexadecimal numbers <vid> and <pid> using -P usb:<vid>:<pid>. The
+form -P usb:<serialno> requests AVRDUDE select the PICkit5 programmer with
+a serial number that ends in <serialno> (and with vid/pid from the
+configuration files).
+.Pp
 For the XBee programmer the target MCU is to be programmed wirelessly over a
 ZigBee mesh using the XBeeBoot bootloader.  The ZigBee 64-bit address for the
 target MCU's own XBee device must be supplied as a 16-character hexadecimal
diff --git a/src/doc/avrdude.texi b/src/doc/avrdude.texi
index 9fcc5670..ca8954ce 100644
--- a/src/doc/avrdude.texi
+++ b/src/doc/avrdude.texi
@@ -872,10 +872,18 @@ USB hierarchy using @code{-P usb:@var{bus}:@var{device}}.
 
 For USBasp, multiple devices can also be also distinguished using @code{-P
 usb:@var{bus}:@var{device}} or using the serial number @code{-P
-usb:@var{serial}}. The USBasp serial number is matched from the end, so
+usb:@var{serialno}}. The USBasp serial number is matched from the end, so
 only the unique least significant bytes are needed. For examples, see the
 respective entry in @ref{Troubleshooting}.
 
+The @code{-c pickit5} programmer allows overriding the product ID with a
+hexadecimal number @var{pid} using @code{-P usb::@var{pid}} and the vendor
+and product IDs with hexadecimal numbers @var{vid} and @var{pid} using
+@code{-P usb:@var{vid}:@var{pid}}. The form @code{-P usb:@var{serialno}}
+requests AVRDUDE select the PICkit5 programmer with a serial number that
+ends in @var{serialno} (and with @var{vid}/@var{pid} from the
+configuration files).
+
 For the XBee programmer the target MCU is to be programmed wirelessly
 over a ZigBee mesh using the XBeeBoot bootloader.  The ZigBee 64-bit
 address for the target MCU's own XBee device must be supplied as a
@@ -5375,7 +5383,7 @@ in bash with single quotes.
 
 For USBasp the same @code{-P usb:@var{bus}:@var{device}} as with USBtiny selects
 the right device. Alternatively, USBasp can select the device via its
-serial number using @code{-P usb:@var{serial}}.
+serial number using @code{-P usb:@var{serialno}}.
 
 Note that @code{avrdude -v -P usb:xyz} will print out suitable programmers
 on the bus assuming xyz does not match any device.