Powershell script to search for a string inside an intel hex (iHex) formatted file, returning the address (with optional offset) to all found occurrences, and a count of how many times the string was found.

README.md

FindIHexString.ps1

Note

I have made an improved version of this script, called FindIHexStringExtract .ps1 which can also return data from an offset of the addresses found. Check it out here: https://gist.github.com/f-steff/cb592cd2d0bdb1d858595118915f3a06

Overview

FindIHexString.ps1 is a PowerShell script designed to search for a specific string within an Intel HEX formatted file. The script outputs the memory addresses where the string is found, followed by a count of occurrences on the final line. This tool is a quick and effective way to locate specific data within a HEX file, particularly useful for embedded systems developers or anyone working with microcontroller firmware.

Motivation

When dealing with Intel HEX files, particularly in embedded systems development, it's often necessary to search for specific strings or patterns. Unfortunately, there aren't many straightforward tools to perform such searches within Intel HEX files. FindIHexString.ps1 was created as a quickly hacked together solution to fill this gap, providing an easy-to-use script for searching and identifying string occurrences within these files.

The latest version of this script can always be found on this Github gist:

https://gist.github.com/f-steff/01ff67a566835a9ca3aba7a0537507c3

Usage

Command Syntax

.\FindIHexString.ps1 -HexFile <path> -SearchString <string> [-Offset <integer>] [-Help]

Parameters

• -HexFile : (Required) The path to the Intel HEX file. Can be an absolute or relative path.
• -SearchString : (Required) The string to search for within the Intel HEX file.
• -Offset : (Optional) An address offset to apply to the found addresses. Can be positive or negative. Default is 0.
• -Help: (Optional) Displays usage information and examples.

Examples

Basic Search

Search for the string "my_string" in a Intel HEX file:

.\FindIHexString.ps1 -HexFile "C:\path\to\file.hex" -SearchString "my_string"
0xFFF80005
0xFFFF0005
2

Search with Positive Offset

Search for "test" in the Intel HEX file, adding an offset of 5 to all found addresses:

.\FindIHexString.ps1 -HexFile "file.hex" -SearchString "test" -Offset 5
0xFFF8000A
0xFFFF000A
2

Search with Negative Offset

Search for "test" in the Intel HEX file, subtracting 5 from all found addresses:

.\FindIHexString.ps1 -HexFile "file.hex" -SearchString "test" -Offset -5
0xFFF80000
0xFFFF0000
2

Search for a string with special characters

Search for "$VER:" in the Intel HEX file, requires a slightly different format, as Powershell will reach to some special characters. To overcome this problem, the search string must be wrapped in single-quotes like this: '$VER:'

.\FindIHexString.ps1 -HexFile "file.hex" -SearchString '$VER:'
0xFFF70000
0xFFFE0000
2

Display Help

Display usage information and examples:

.\FindIHexString.ps1 -Help

Error Messages

• Search string cannot be empty.
  Occurs when the -SearchString parameter is provided with an empty string. The script requires a non-empty search string to function.

• Offset must be a numeric value.
  Occurs when the -Offset parameter is provided with a non-numeric value. The offset must be a valid integer.

• File not found: .
  Occurs when the file specified by the -HexFile parameter does not exist. Ensure the path is correct.

Return Codes

• 0: The script executed successfully. All operations were completed without errors.
• 1: The script encountered an error. This could be due to an invalid search string, non-numeric offset, or file not found. Read the exact error description.

Notes

• The script was designed as a quick solution to address a specific need. It performs the required operations efficiently but may lack advanced features of more sophisticated tools.
• For lack of a better tool, FindIHexString is a valuable resource for developers working with Intel HEX files, providing an easy and reliable way to locate specific data within such files.

FindIHexString.ps1

param (
    [string]$HexFile,         # Path to the HEX file
    [string]$SearchString,    # The string to search for
    $Offset = 0,              # Optional address offset (default is 0)
    [switch]$Help             # Optional help switch
)

# Display help and exit if -help is provided
if ($Help) {
    Write-Host "For lack of a better tool, FindIHexString is a quickly hacked together script that searches through"
    Write-Host "an intel hex formatted file, outputting the address of any occourcenses of the provided string."
    Write-Host "Last line in the outout is always the number of strings found within the intel hex file."
    Write-Host ""
    Write-Host "Version 1.0   2024-08-15"
    Write-Host "Latest version available from https://gist.github.com/f-steff/01ff67a566835a9ca3aba7a0537507c3"
    Write-Host ""
    Write-Host "Usage: .\FindHexString.ps1 -HexFile <path> -SearchString <string> [-Offset <integer>] [-Help]"
    Write-Host ""
    Write-Host "Arguments:"
    Write-Host "  -HexFile <path>          : Path to the HEX file (absolute or relative)"
    Write-Host "  -SearchString <string>   : String to search for in the HEX file"
    Write-Host "  -Offset <integer>        : Optional address offset, positive or negative (default is 0)"
    Write-Host "  -Help                    : Display this help message and exit"
    Write-Host ""
    Write-Host "Examples:"
    Write-Host "  .\FindHexString.ps1 -HexFile C:\path\to\file.hex -SearchString my_string"
    Write-Host "  .\FindHexString.ps1 -HexFile file.hex -SearchString test -Offset 10"
    Write-Host "  .\FindHexString.ps1 -HexFile file.hex -SearchString test -Offset -20"
    exit 0
}

# Check if the search string is empty
if ([string]::IsNullOrWhiteSpace($SearchString)) {
    Write-Error "Search string cannot be empty."
    exit 1
}

# Check if the offset is numeric
if (-not ([int]::TryParse($Offset, [ref]$null))) {
    Write-Error "Offset must be a numeric value."
    exit 1
}

if (-not (Test-Path $HexFile)) {
    Write-Error "File not found: $HexFile"
    exit 1
}

$foundCount = 0
$extendedAddress = 0

# Read the file line by line
Get-Content $HexFile | ForEach-Object {
    $line = $_
    
    # Get the record type (position 8-9)
    $recordType = $line.Substring(7, 2)

    if ($recordType -eq "04") {
        # This is an Extended Linear Address Record, update the $extendedAddress
        $extendedAddress = [convert]::ToInt32($line.Substring(9, 4), 16) * 65536
    }

    # Skip lines that do not contain data records (record type 00)
    if ($recordType -eq "00") {
        # Extract the address field (aaaa)
        $address = [convert]::ToInt32($line.Substring(3, 4), 16) + $extendedAddress
        
        # Extract the data portion of the line
        $data = $line.Substring(9, $line.Length - 11)
        
        # Convert data from HEX to ASCII
        $asciiDataArray = @()
        for ($i=0; $i -lt $data.Length; $i+=2) {
            $asciiDataArray += [char][convert]::ToByte($data.Substring($i, 2), 16)
        }
        $asciiData = -join $asciiDataArray
        
        # Check if the string is in the data
        if ($asciiData -like "*$SearchString*") {
            $position = $asciiData.IndexOf($SearchString) * 2
            $exactAddress = [convert]::ToInt64($address + ($position / 2)) + $Offset
            Write-Output ("0x{0:X8}" -f $exactAddress)
            $foundCount++
        }
    }
}

# Output the total number of occurrences
Write-Output $foundCount

version.txt

   0.1     2024-08-15     Initial version.
   1.0     2024-08-15     Added Gist URL