Hardware Detection & Diagnostics for New FreeBSD Users & PCs

L

little_blue_daemon

Well, turns out if you hit "enter" while in the title section of a post you're writing, it'll post it immediately! Good to know. My bad. This might not be completed by the time it's reviewed. Actually, it definitely won't be.

Contents​
  1. Background​
  2. Prerequisites​
  3. The First Boot​
  4. Hardware Identification​
  5. The Test Installation​
  6. Hardware Testing​

Background​

I decided to make a simple, repeatable checklist procedure for checking hardware compatibility and driver requirements before installing FreeBSD. The FreeBSD handbook doesn't have a comprehensive "detect and test hardware and drivers" section as far as I've noticed. There is this section in the "Installation" chapter here...

To review the boot messages, including the hardware device probe, press the upper- or lower-case S and then Enter to access a shell. At the shell prompt, type more /var/run/dmesg.boot and use the space bar to scroll through the messages. When finished, type exit to return to the welcome menu.
Click to expand...

... And it's true that you can figure out what hardware the system is made of from that alone, but I think that's a little opaque.

When I searched for "hardware diagnostics" and "detection" in the forums, I found this thread discussing a non-existent port of a Linux hardware probe tool when I searched the forum, without getting much useful info. There's also a recent hw-probe tool for FreeBSD, but it's a third-party thing and not included with the installer images. I found a thread about that too. Someone made an excellent point about "trust" and running large Perl scripts off the web as root, and I agree that solution won't work for everyone and every system.

So here's my in-progress personal preinstall procedure for testing hardware component compatibility and capabilities before installing FreeBSD on a new PC. This will definitely be updated a few times, especially when I and/or someone else actually tests things on AMD and Arm systems (I've only tested Intel so far).


Prerequisites​
  • A USB booting personal computer for installation. You should have backed up any critical files on the internal disk, though we won't install a new system on it in this guide.
  • Two spare USB flash drives, one of which has been formatted with a FreeBSD mini memstick image and the other of which does not have any critical files on it. I recommend cheap USBv2 drives for this.
  • A spare internet and web-capable device.
    • If you don't have one, look up documentation ahead of time. You can print PDF documentation and PDF printouts of web resources. This might be cost-prohibitive, especially with a public printer, so you can print or hand-write your own notes instead.
  • An internet connection using:
    • A FreeBSD-compatible (see "Hardware Notes") Ethernet or WiFi interface connected to the installation target and a router/gateway.
    • Another personal computer sharing a connection over a bridge.
    • A mobile device sharing a connection over USB tethering.
      • An Android device with a USB OTG port and tethering enabled is also a way to connect to public WiFi that doesn't "play nice" with your FreeBSD and/or Linux systems in general. Trying that with a bridge/NAT setup on a laptop might get your WiFi card blocked from the public network (ask me how I know). iOS also has USB tethering, but it only works with the mobile network (not WiFi).
  • Relevant FreeBSD documentation, including the Installation Chapter of the handbook, the Hardware Notes page for the FreeBSD version you're installing, the FreeBSD Basics chapter (particularly the Virtual Consoles and Terminals and Devices and Device Nodes sections), the Multimedia chapter, and the Advanced Networking chapter.
  • For a workstation system you'll also want the X Window System chapter available and possibly other stuff referenced on the Graphics wiki page such as the AMD and Intel graphics compatibility matrices. The X chapter includes information about Wayland.
  • There's also a section on setting up proprietary NVidia drivers (it needs updating, see below). Check their web search and try identifying the correct package for your card's driver or downloading it directly from their site. You also might need to load one of two drivers as I found out the hard way. It's mentioned in the post-installation notes of the NVidia driver packages.
  • For OEM PCs - including most if not all laptops - you can find a "user manual" and possibly a separate "maintenance" or "service manual" PDF by the manufacturer, and those documents will have detailed information on components like the graphics, storage, and wireless systems (example).
  • People working with whitebox (custom, non-OEM) PCs should disassemble them, identify the major components based on their labels, and check the parts' features and compatibility with one another and FreeBSD.


The First Boot​
  1. Don't plug in your installation medium yet. Instead, boot into your PC's firmware interface. This will usually require you to press a key during the early startup process as described in your device or motherboard's user manual. You should choose a boot option called "BIOS," "Firmware," "Platform," "Menu," or something probably containing one or more of those words. This should be specified in your device or motherboard's user manual.
    1. If you cannot access your firmware interface this way, you may be able to use software tools in an operating system to cause your device to automatically boot into the firmware when it reboots. Windows has this feature under its "Recovery" settings.
    2. If all else fails, you may be able to remove all storage - including the internal boot disk - which may force the system to boot into its firmware interface. If you go this far, be sure to power the device off and replace the internal storage before booting the installation medium for testing. You might be safe reattaching the storage while you're still booted into the firmware interface, but I haven't tried that myself.
  2. Explore what features are available and configurable from this interface.
    1. Make sure everything you want is enabled.
    2. Consider disabling extraneous things.
    3. Look up "FreeBSD <feature>" in a search engine if something seems unusual.
    4. Consider your OEM system recovery options and how you might be able to re-install the OEM operating system; don't take it for granted that you'll be able to boot from a USB drive or network interface and get things back to normal with anything made recently.
  3. Start keeping track of anything out of place between the features described in your device's maintenance manual and what you can see in this interface. Not every feature on your system will necessarily be reflected in the firmware interface, but you might catch problems that you'd later investigate the operating system for.
  4. Now plug in your installation media.
  5. Either find a "boot override" option and select your installation media, set your installation media as the first option in the boot order, exit the firmware interface and use a different key to select a boot device when the system reboots, or else use operating system tools to select the boot device (again, like Windows' Recovery settings).
  6. Boot the installation medium and select the first (default) boot option for multi-user mode, hit enter, or let the timer run down.
  7. When you get to the graphical prompt for "Install, Shell, or Live," select "Shell." The shell environment will let us gather information about the system, then easily return to the installation prompt.

Hardware Identification​

What we want here is to gather as much information about the system's hardware and required drivers as we can with our current software.

There's /var/run/dmesg.boot and /var/log/messages, but like I mentioned earlier, those are a little opaque. There are far clearer tools included with the FreeBSD installation images. We'll go over these easier tools and then I'll explore the entire /var/run/dmesg.boot file on my own system, extracting useful and specific hardware information.

Note that devices which are not compatible with FreeBSD may still show up in these commands. You'll need to check the device's compatibility and behavior. You might save time by simply looking for the devices on the Hardware Notes page and a search engine before you bother with testing anything yourself.

  1. The devinfo command gives an overview of the entire device tree. For more information on this device tree, some readers might be interested in reading about FreeBSD's Newbus architecture.
    1. Use devinfo to get a neat, indented tree of device names demonstrating the actual device tree.
    2. Use devinfo -u to organize the devices by type rather than by their position in the device tree. I find this less useful as an overview, but it might help you find something specific if you need it.
    3. To get a more explicit view of a single device's position in the tree, use devinfo -p <dev_name>. This will show the device's parent devices up to the root "nexus0" device.
  2. The pciconf command gives an overview of the PCI device tree in particular. Your device's USB host, display system, graphics card, internal storage, and likely other components will all be part of this device tree.
    1. Use pciconf -lv to get detailed, neatly printed information about all your PCI devices.
    2. Use pciconf -lv <device>, where <device> is the first part of the PCI device address.
      1. Example: a device with a full PCI address of "hdac0@pci0:1:0:1" would only need to be referred to as "hdac0," as in pciconf -lvc hdac0[cmd]. It also works with the full address.
        [/LIST]
        [/LIST]
        [*]The [cmd]usbconfig         command is similar to the pciconf command.
        1. Use usbconfig to get the names of all USB hubs and attached devices. This may include devices that are attached to your motherboard/CPU via USB, but aren't necessarily attached via your external USB ports. My integrated webcam shows up as a USB device on my system.
        2. USB devices have a bus number and address in the form "N.A," where "N" is the bus number and "A" is the address. You can get more specific information using the command form usbconfig -u $N -a $A <subcommand>
        3. You can use usbconfig -u $N -a $A show_ifdrv to identify the driver being used for the device. For example, my USB mass storage devices displayed the
          Code: 
          umass
          driver. My main USB hub showed up with the
          Code: 
          uhub
          driver. My webcam, which is not mentioned anywhere on the Hardware Notes page, did not list a driver in the output.
          1. This is a good way to start checking for compatibility with your existing USB devices; FreeBSD dynamically loads modules and adds devices as they are detected, so if you plug in a USB WiFi dongle and it doesn't show up in ifconfig, give driver output using usbconfig ... show_ifdrv, or show up by name on the Hardware Notes page, it probably doesn't work with FreeBSD. It might be worth looking up in a search engine before giving up on the USB device.
        4. There are several other sub-commands for usbconfig, you may want to browse man usbconfig if you're having unusual problems with a USB device.
      2. There are several commands that give useful information about storage devices. Here are a few.
        1. Use camcontrol devlist to get a list of all the CAM-compatible storage systems on your device. This can include internal storage, external USB storage, and empty optical disk readers. CAM stands for Common Access Method, and it works with most block storage devices.
        2. Use nvmecontrol for working with NVMe storage devices. NVMe is a more recent, high-speed storage system over a PCIe bus.

        The Test Installation

        Installing to a cheap USB flash drive will allow you to install and run advanced software for testing before you actually configure your final system.

        You can identify any hardware or driver-level problems much more easily by doing a pragmatic, minimalist installation testing the system features that you intend to use without committing to the complexity and customization your personal server or workstation deserves. Having configured things successfully once, you'll also be more confident and less clumsy in your final installation.

        I wouldn't necessarily go this far every time I install FreeBSD on a system, but experience with Linux has taught me that it's worth the work to practice things the easy-but-useless way before you try them the production-quality way.


        - Use a terminal multiplexer like screen, tmux, or dvtm for all of this. I don't want to imagine trying to switch back and forth between some of these log files and command outputs and the command shell. You'll want at least two or three "windows" visible in the console, plus your separate web device or printed documentation.

        - less /var/run/boot.dmesg, mentioned in the handbook, gives a snapshot of the kernel message buffer.
        - less /var/log/messages gives a more long-term view of the message buffer, which I found useful for finding the point where I installed a certain driver and comparing buffer messages before and after. You can search for things like package installations and reboots here.
        - tail -f /var/log/messages prints out kernel messages about hot plugged hardware as they come.

        I'm also going to work out a useful set of tests/benchmarks from the Phoronix testing suite for newbies to run and make that a reply in this thread.

 
Thanks!

Section 4, 2.2.1.3 you might like to replace the CODE with ICODE. (Incidentally, numbering can be frustrating with BBCode.)

If you like, create an anchor for each section (and don't number the sections, because the numbering within each section will start from 1).

little_blue_daemon said:
… see "Hardware Notes" …
Click to expand...

Please note, they're not intended to be comprehensive.

forums.freebsd.org

Hardware compatibility list

Seems to me that the hardware listed in the compatibility list for FreeBSD 13 is at least 4-5 years old. Is there no recent hardware on this list? or am I missing something?
forums.freebsd.org forums.freebsd.org

… Installing to a cheap USB flash drive will allow you to install and run advanced software for testing …
Click to expand...

With this type of drive, things might be excruciatingly slow.
 
You must log in or register to reply here.
Back
Top