Adding new device support - Phase (1): Information collection

Hello,

I see that page of adding new device support does not have all information I needed to add new device support.

for example; what commands needed to collect all information from a device necessary to start adding new device support to openwrt.

I am making a project to learn how to develop Openwrt firmware to add new device support, my goal is to make this post as generic as possible so all of those who are interested to learn can learn and apply to their devices.

I have listed below all commands which I have so far to collect all information from existing router (assuming successful access to SSH):


# uname -an
# cat /proc/device-tree/model
# cat /proc/mtd
# cat /proc/partitions
# cat /proc/cpuinfo
# cat /proc/cmdline
# cat /proc/devices
# ls -aln /sys/devices/platform
# ifconfig -a
# ls -aln /sys/class/net
# brctl show
# ls -aln /sys/class/leds/
# ip link show
# wifi

Note that: gpio-dump.sh is a script for GPIO buttons

Optional commands:

# opkg list-installed
# ip link show
# iwinfo
# cat /proc/device-tree/boot_version 
# dmesg

Is there any remaining (or additional) command(s) needed other than the above? please share your experience.

Thank you in advance.

1 Like

This depends heavily on the device and how much access you have. If you can access the stock firmware, your instructions are fine. Sometimes, the boot log is sufficient for adding device support as it often contains a partition dump and sometimes the GPIO map. And then it depends on the target: some targets, like ipq40xx, give very detailed GPIO mappings in sysfs, other targets do not contain any information at all.
If you don't get access, this approach won't work.

I suggest hat you include other possible sources as well:

  • Vendor GPL dump
  • Doing a full partition dump (for example, using a clip) and analyzing the flash content
  • Extracting a firmware upgrade file using binwalk and associated tools

However, I agree that the wiki page is not very detailed and lacking some important information. Problem is: Once you're through with this process it's hard to remember what you did and it's not much fun to document all that.

I am trying to list the common commands so others can benefit from them.

I agree, all of the commands I listed are based on the assumption that there is SSH (and/or Telnet) access.

How to do those 3 steps above, can you give more details?

I am documenting all what I did, then later I hope (I am interested to) update OpenWrt wiki as well

1 Like

@andyboeh Here below are what I got from my search for far, do you think they are correct?

- For GPL Dump

In the context of OpenWRT firmware development, the term "GPL Dump" typically refers to the process of extracting and providing access to the source code of the components that are covered under the GNU General Public License (GPL) or other open-source licenses.

The GPL is a widely used free software license that requires the distribution of the corresponding source code along with the binary distribution of the software. Therefore, when developing OpenWRT firmware, which is based on open-source software, it is important to comply with the GPL and provide access to the source code of the software components used in the firmware.

The term "GPL Dump" signifies the act of gathering all the relevant source code files, documenting their versions and licenses, and making them available for download or distribution. This ensures compliance with the GPL and allows users and developers to access, modify, and redistribute the code as per the terms of the license.

- For Doing a full partition dump (for example, using a clip) and analyzing the flash content

Performing a full partition dump, such as using a clip, involves extracting the entire contents of a flash memory chip and analyzing the data it contains. Here's an example:

Let's say you have an OpenWRT router with a flash memory chip that contains multiple partitions, including the bootloader, firmware, configuration settings, and other data. To do a full partition dump, you would use a clip or similar hardware tool to connect to the flash memory chip directly.

1- Attach the clip: Connect the clip to the appropriate pins on the flash memory chip, ensuring a secure and proper connection.

Dumping the flash memory partitions:

  • Connect the clip or hardware tool to the flash memory chip.
  • Identify the flash device and its partitions. For example:
           $ lsblk
  • Create a backup file for each partition using a command like:

          `$ dd if=/dev/mtdX of=partitionX_backup.bin bs=1M`
    

Replace mtdX with the specific partition device, and partitionX_backup.bin with the desired backup file name.

2- Analyzing the flash content:

Use a suitable tool to examine the dumped flash content. For example:
For binary analysis: Use a hex editor like hexdump or xxd to inspect the binary data.

        `$ hexdump -C partitionX_backup.bin`

For file system analysis: Mount the file system within the dump and navigate through the directories and files.

            $ mkdir mount_point
            $ mount -o loop partitionX_backup.bin mount_point

For firmware analysis: Extract and analyze firmware-specific files, such as kernel, root filesystem, or configuration files.

        `$ binwalk partitionX_backup.bin`

3- Analyze the dump: Once the full partition dump is complete, you can analyze the extracted data. This may involve examining the firmware code, configuration files, and any other relevant information contained within the dump. (Will be discussed later in separate post for Analyzing)

4- Extract specific information: If you are looking for specific data, you can search through the dump to locate and extract the desired files or configurations. (Will be discussed later in separate post for Analyzing)

Note:
The specific commands and tools may vary depending on the device, flash memory architecture, and the tools available for that particular hardware. It's crucial to consult the documentation and resources specific to the device or seek guidance from the manufacturer for accurate instructions.

- For Extracting a firmware upgrade file using binwalk and associated tools

Here's an example of how you can use binwalk and associated tools to extract a firmware upgrade file:

  1. Install necessary tools:
    Install binwalk if you don't already have it:

    $ sudo apt-get install binwalk

  2. Identify the firmware upgrade file:

Locate the firmware upgrade file you want to extract. Let's say it's named upgrade.bin.

  1. Extract the firmware upgrade file using binwalk:

Run the following command to perform a preliminary analysis of the file and extract embedded file systems, compressed files, and other data:

    `$ binwalk -e upgrade.bin`
  1. Analyze the extracted contents:
  • Navigate to the output directory created by binwalk (usually named upgrade.bin.extracted) to explore the extracted contents.
  • You may find subdirectories with extracted files, such as squashfs-root, romfs, or others, depending on the firmware format.
  1. Further analysis and extraction:
  • Use additional tools specific to the extracted contents for further analysis or extraction.
    For example, if you have an extracted SquashFS file system, you can mount it to explore its contents:

    $ sudo mount -t squashfs -o loop upgrade.bin.extracted/squashfs-root /mnt

5 Likes

With the clip, you cannot dd or run lsblk. You will need a tool like flashrom to read/write the flash IC. Also, using a clip isn't possible for all flash ICs, i.e. I'm not sure if it's possible for a NAND IC. It often works on SPI flash chips, but YMMV.

You can also run binwalk on the dump to ease identification of the content.

I suggest binwalk -e -M to automatically parse and extract all embedded content. This avoids having to loop-mount the image. And for loop-mounting, make sure to mount it ro.

Noted! I will update my documentation accordingly.
Thanks @andyboeh for your valuable comments and feedback :+1:

Hi @andyboeh

do you mean by clip something like this Clip on AliExpress ?

and another question; is there a universal clip suitable for - almost - all flashes? if yes; can you recommend this universal clip ?, I am interested to buy one

No, that's a pogo-pin adapter. I meant a Pomona clip, they do not require to be held in place. And no, they are specific to the IC package, but SOIC-8 is quite common for SPI flash chips (with some being SOIC-16 and some completely different).

Okay, to avoid any confusion, could you send a picture of Pomona clip? Or Amazon / Ali Express page?

[UPDATE 23.12.2023]
Here is a picture for Pomona clips:

Those Pomona clips can be bought from Ali-Express