Mirrors/avrdude
1
0
Fork 0
mirror of https://github.com/avrdudes/avrdude.git synced 2026-10-02 16:09:00 +03:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation for USB permissions

Browse Source
This commit is contained in:
Stefan Rueger
2024-08-07 15:52:30 +01:00
parent 9a750de07f
commit 41af587da8
2 changed files with 104 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
src/developer_opts.c
View File

@@ -1586,9 +1586,20 @@ void dev_output_pgm_defs(char *pgmidcp) {
}
if(udev && ui) {
dev_info("# 1. Put Linux udev rules into, eg, /etc/udev/rules.d/55-avrdude.rules\n");
dev_info("# 2. Unplug the device and plug it in again\n");
dev_info("# 3. Enjoy user access to the USB programmer\n");
int all = str_eq(pgmidcp, "*");
const char *var = all? "": str_asciiname((char *) str_ccprintf("-%s", pgmidcp));
dev_info("1. Examine the suggested udev rule%s below; to install run:\n\n", str_plural(ui + udr[0].ishid));
dev_info("%s -c \"%s/u\" | tail -n +%d | sudo tee /etc/udev/rules.d/55-%s%s.rules\n",
progname, pgmidcp, all? 9: 11, progname, var);
dev_info("sudo chmod 0644 /etc/udev/rules.d/55-%s%s.rules\n\n", progname, var);
dev_info("2. Unplug any AVRDUDE USB programmers and plug them in again\n");
dev_info("3. Enjoy user access to the USB programmer(s)\n\n");
if(!all)
dev_info("Note: To install all udev rules known to AVRDUDE follow: %s -c \"*/u\" | more\n\n",
progname);
dev_info("# Generated from avrdude -c \"%s/u\"\n", pgmidcp);
if(ui > 3)
dev_info("\nACTION!=\"add|change\", GOTO=\"avrdude_end\"\n");
qsort(udr, ui, sizeof *udr, udev_cmp);
char *prev_head = mmt_strdup("<none>");
for(Dev_udev *u = udr; u-udr < ui; u++) {
@@ -1615,5 +1626,7 @@ void dev_output_pgm_defs(char *pgmidcp) {
"ATTRS{idProduct}==\"%04x\", MODE=\"0660\", TAG+=\"uaccess\"\n", u->vid, u->pid);
}
mmt_free(prev_head);
if(ui > 3)
dev_info("\nLABEL=\"avrdude_end\"\n");
}
}

122
src/doc/avrdude.texi
View File

@@ -4287,7 +4287,7 @@ Other combinations should not show after exit.
* Unix Installation::
* Unix Configuration Files::
* Unix Port Names::
* Linux Udev Rules::
* Unix USB Permissions::
* Unix Documentation::
@end menu
@@ -4385,7 +4385,7 @@ to system. The above example is specific to RedHat.
@cindex Unix configuration files
@noindent
When AVRDUDE is build using the default @option{--prefix} configure
When AVRDUDE is built using the default @option{--prefix} configure
option, the default configuration file for a Unix system is located at
@code{/usr/local/etc/avrdude.conf}. This can be overridden by using the
@option{-C} command line option. Additionally, the user's home directory
@@ -4422,7 +4422,7 @@ configuration file will be always be @code{/etc/avrdude.conf}.
@c
@c Node
@c
@node Unix Port Names, Linux Udev Rules, Unix Configuration Files, Unix
@node Unix Port Names, Unix USB Permissions, Unix Configuration Files, Unix
@subsection Unix Port Names
@cindex Unix port names
@@ -4462,32 +4462,78 @@ access.
@c
@c Node
@c
@node Linux Udev Rules, Unix Port Names, Unix Documentation, Unix
@subsection Linux Udev Rules
@cindex Linux udev rules
@node Unix USB Permissions, Unix Port Names, Unix Documentation, Unix
@subsection Unix USB Permissions
@cindex Unix USB permissions
@cindex udev rules
In most cases the kernel driver initializes a plug-and-play device to be
owned by user @code{root} and group @code{root} with only r/w permission
for the user @code{root} rendering the device inaccessible to regular
users. Whilst users can run AVRDUDE sessions as root this is definitely
@emph{not good practice}. Giving USB plug-and-play devices the correct
permissions is much better. USB AVR programmers are normally identified by
a two-byte hexadecimal vendor ID and a two-byte hexadecimal product id.
Both are typically used to identify the device that needs new permissions.
@menu
* FreeBSD USB Permissions::
* Linux USB Permissions::
@end menu
@c
@c Node
@c
@node FreeBSD USB Permissions, Linux USB Permissions, Unix USB Permissions, Unix USB Permissions
@subsubsection FreeBSD USB Permissions
@cindex FreeBSD configuration files
In FreeBSD a so-called @code{devd} config files in
@code{/usr/local/etc/devd} serve to modify permissions of plugged-in USB
devices. Here is an example how Atmel's JTAGICE3 programmer (product ID
0x2110 or 0x2140) by Atmel (vendor ID 0x0eb) can be given appropriate
permissions using a file @code{jtagice3.conf}:
@smallexample
@cartouche
notify 100 @{
match "system" "USB";
match "subsystem" "DEVICE";
match "type" "ATTACH";
match "vendor" "0x03eb";
match "product" "(0x2110|0x2140)";
action "chmod 660 /dev/$cdev";
action "chgrp yourgroup /dev/$cdev";
@};
@end cartouche
@end smallexample
@noindent @code{yourgroup} would be a group that the user(s) should be
member of who wish to have access to the programmer.
@c
@c Node
@c
@node Linux USB Permissions, , FreeBSD USB Permissions, Unix USB Permissions
@subsubsection Linux USB Permissions
@cindex Linux configuration files
Linux has a special userspace @code{/dev} device manager called udev that
deals with, amongst other things, plug-and-play USB devices. In most cases
the kernel driver initializes a plug-and-play device to be owned by user
@code{root} and group @code{root} with only r/w permission for the user
@code{root} rendering the device inaccessible to regular users. Whilst
users can run AVRDUDE sessions as root this is definitely @emph{not} good
practice.
deals with, amongst other things, plug-and-play USB devices. It is
recommended to specify so-called udev rules to define access permissions
for these devices instead. These rules typically reside in a file with the
name @var{nn}@code{-}@var{descriptive-name}@code{.rules} in the directory
@code{/etc/udev/rules.d}. Here, @var{nn} is a two-digit number that
determines the lexical order in which the udev rule files are processed.
Rules processed later can overwrite earlier rules, but it not recommended
to put user-generated rules higher than 60, as some of the actions they
require are processed by higher-level system rules.
It is recommended to specify so-called udev rules to define access
permissions for these devices instead. These rules typically reside in a
file with the name @var{nn}@code{-}@var{descriptive-name}@code{.rules} in
the directory @code{/etc/udev/rules.d}. Here, @var{nn} is a two-digit
number that determines the lexical order in which the udev rule files are
processed. Rules processed later can overwrite earlier rules, but it not
recommended to put user-generated rules higher than 60, as some of the
actions they require are processed by higher-level system rules.
USB AVR programmers are normally identified by a two-byte hexadecimal
vendor ID and a two-byte hexadecimal product id. Here a typical udev rule
for allowing an ordinary user access to the plugged-in AVRISP mkII
programmer (product ID 0x2104) by Atmel (vendor ID 0x0eb):
Here a typical udev rule for allowing an ordinary user access to the
plugged-in AVRISP mkII programmer (product ID 0x2104) by Atmel (vendor ID
0x0eb):
@smallexample
@cartouche
@@ -4498,8 +4544,8 @@ SUBSYSTEM=="usb", ATTRS@{idVendor@}=="03eb", ATTRS@{idProduct@}=="2104", \
@end cartouche
@end smallexample
This furnishes the corresponding device node with @code{0660} access
permissions: this means r/w for the user @code{root} and any user
@noindent This furnishes the corresponding device node with @code{0660}
access permissions: this means r/w for the user @code{root} and any user
belonging to the group of the device, which the device driver might assign
to a different group than the default @code{root}. The key of the rule is
the attached @code{TAG} named @code{uaccess}, which has the effect that
@@ -4516,9 +4562,19 @@ above suggested udev rule for the named programmer. Wildcards are allowed:
$ avrdude -c jtag\*/u
# 1. Put Linux udev rules into, eg, /etc/udev/rules.d/55-avrdude.rules
# 2. Unplug the device and plug it in again
# 3. Enjoy user access to the USB programmer
1. Examine the suggested udev rules below; to install run:
avrdude -c "jtag*/u" | tail -n +11 | sudo tee /etc/udev/rules.d/55-avrdude-jtagX.rules
sudo chmod 0644 /etc/udev/rules.d/55-avrdude-jtagX.rules
2. Unplug any AVRDUDE USB programmers and plug them in again
3. Enjoy user access to the USB programmer(s)
Note: To install all udev rules known to AVRDUDE follow: avrdude -c "*/u" | more
# Generated from avrdude -c "jtag*/u"
ACTION!="add|change", GOTO="avrdude_end"
# jtag2dw, jtag2fast, jtag2, jtag2isp, jtag2pdi, jtag2slow, jtagmkII, jtag2avr32
SUBSYSTEM=="usb", ATTRS@{idVendor@}=="03eb", ATTRS@{idProduct@}=="2103", \
@@ -4529,7 +4585,6 @@ SUBSYSTEM=="usb", ATTRS@{idVendor@}=="03eb", ATTRS@{idProduct@}=="2110", \
MODE="0660", TAG+="uaccess"
KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS@{idVendor@}=="03eb", \
ATTRS@{idProduct@}=="2110", MODE="0660", TAG+="uaccess"
SUBSYSTEM=="usb", ATTRS@{idVendor@}=="03eb", ATTRS@{idProduct@}=="2140", \
MODE="0660", TAG+="uaccess"
KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS@{idVendor@}=="03eb", \
@@ -4542,9 +4597,8 @@ SUBSYSTEM=="usb", ATTRS@{idVendor@}=="0403", ATTRS@{idProduct@}=="cff8", \
@end cartouche
@end smallexample
Again, each rule must be written as one line: breaking up rules into two
lines was only done to fit AVRDUDE's output to the boxed display.
@noindent Again, each rule must be written as one line: breaking up rules
into two lines was only done to fit AVRDUDE's output to the boxed display.
USB devices in HID mode require a second rule dealing with the
@code{hidraw} subsystem as seen above.