docs/150991: [patch] Install upgtfw using pkg_add as advised in upgt(4) fails

[Anil Gulati]

>Number:         150991
>Category:       docs
>Synopsis:       [patch] Install upgtfw using pkg_add as advised in upgt(4) fails
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Mon Sep 27 12:00:16 UTC 2010
>Closed-Date:
>Last-Modified:
>Originator:     Anil Gulati
>Release:        FreeBSD 8.1 CURRENT
>Organization:
Anil Gulati
>Environment:
FreeBSD engine.local 8.1-BETA1 FreeBSD 8.1-BETA1 #0: Thu Aug 26 22:45:23 EST 2010     root at engine.local:/usr/obj/usr/src/sys/VESAKERN  i386

>Description:
Loading kernel module upgt requires upgtfw firmware is installed, but upgt(4) man page advises this can be done with pkg_add, but it fails.

Attempting to install the firware obtained from the address given in the man page (and other versions from elsewhere) fails using pkg_add.

The man page appears to be incorrect:

# kldload if_upgt
KLD if_upgt.ko: depends on upgtfw_fw - not available or version mismatch
kldload: can't load if_upgt: No such file or directory

# man 4 upgt
..
This driver requires the upgtfw firmware to be installed before it will work.
A package of the firmware which can be installed via pkg_add(1) is available:
http://weongyo.org/project/upgt/upgt-firmware-2.13.1.0.tar.gz
..

# pkg_add upgt-firmware-2.13.1.0.tar.gz
tar: +CONTENTS: Not found in archive
tar: Error exit delayed from previous errors.
pkg_add: tar extract of /usr/home/anil/upgt-firmware-2.13.1.0.tar.gz failed!
pkg_add: unable to extract table of contents file from '/usr/home/anil/upgt-firmware-2.13.1.0.tar.gz' - not a package?

>How-To-Repeat:
Download the firmware zipped tar from the upgt(4) man page and attempt to pkg_add:

# pkg_add upgt-firmware-2.13.1.0.tar.gz
tar: +CONTENTS: Not found in archive
tar: Error exit delayed from previous errors.
pkg_add: tar extract of /usr/home/anil/upgt-firmware-2.13.1.0.tar.gz failed!
pkg_add: unable to extract table of contents file from '/usr/home/anil/upgt-firmware-2.13.1.0.tar.gz' - not a package?

>Fix:
A normal build DOES work to install the firmware:

# mkdir /usr/src/sys/modules/usb/upgtfw
# cd /usr/src/sys/modules/usb/upgtfw
# cp ~/upgt-firmware-2.13.1.0.tar.gz . # get the upgtfw package from wherever it was
# tar -xf upgt-firmware-2.13.1.0.tar.gz
# rm upgt-firmware-2.13.1.0.tar.gz
# mv upgt-firmware-2.13.1.0/* .
# rmdir upgt-firmware-2.13.1.0
# make
# kldload if_upgt
# kldstat
  if_upgt.ko
  upgtfw.ko

Wireless adapter dependent on the upgt driver started working after this, proving build worked.
Forum thread where this was worked out: http://www.daemonforums.org/showthread.php?t=5108

To fix this I have included a patch for the man page /usr/src/share/man/man4/upgt.4


Patch attached with submission follows:

--- /usr/src/share/man/man4/upgt.4.orig	2009-08-03 18:13:06.000000000 +1000
+++ /usr/src/share/man/man4/upgt.4	2010-09-25 15:53:46.000000000 +1000
@@ -144,7 +144,8 @@
 The firmware files are not publicly available.
 A package of the firmware which can be installed via
 .Xr pkg_add 1
-is available:
+is available
+(or unpack in /usr/src/sys/modules/usb/upgtfw and run 'make' and 'make install'):
 .Bd -literal -offset indent
 http://weongyo.org/project/upgt/upgt-firmware-2.13.1.0.tar.gz
 .Ed


>Release-Note:
>Audit-Trail:
>Unformatted: