-
Notifications
You must be signed in to change notification settings - Fork 10
BSL430.NET.FirmwareTools.Library
BSL430.NET.FirmwareTools is Cross-Platform library, BSL430.NET sub-package, that tries to make firmware manipulation easy. It supports Intel-HEX, TI-TXT and SREC formats for both read/write Parse/Create, and ELF format for read-only(currently dont have time to implement write support). Key functions are to Parse (read from file) and Create (write to file or string) a firmware. On top of that functions there is the rest, using them to provide extended abilities: Convert, Combine and Compare between any firmware formats, Validate firmware file and get information like addresses, CRC, sizes and finally Get BSL password used to correctly download fw by BSL430.NET (this is MSP430 specific functionality).
Note: This library can be built as any architecture possible (x86, x64, ARM..),
because it doesnt depend on unmanaged code, it uses standard C# api only.
- .NET Framework 4.0
- .NET Framework 4.5
- .NET Framework 4.6.1
- .NET Standard 2.0
Library FwTools is static, because it doesnt hold any state or use any instance data. This simplifies a lot, calling methods without instance management is nice for utility library like this. FwFormat is main enum providing information about format (INTEL_HEX, TI_TXT, SREC, ELF). Firmware is main class serving as a generic firmware container. It consists of FwInfo, information class with properties (Format, AddrFirst, AddrLast, SizeFull, SizeCode, CRC16, Valid..) and List of FwNodes. FwNode is the atomic piece of any firmware, holding address (long) and data (byte). This is enough to describe any firmware in the most basic kind of way. Firmware class provides also nice functionality with ToString, Equals and equality operators overiden. Firmware is usually created by Parse methods, but can also be created with raw List of FwNodes or with a MemoryStream, plus there is Getter for MemoryStream from already created class as well. FirmwareTools have also some extension methods firmware related, string to byte array, FwFormat to extension and Crc16Ccitt or just generic Crc16.
Parse firmware file from FirmwarePath in TI-TXT, Intel-HEX, ELF or SREC format and returns List of FwNode (Data+Addr) and Info. Auto Mode reads data and based on some particular characters determine what firmare format it should be. FillFF is optional parameter forcing to fill missing addr nodes with 0xFF and return monolithic piece of code, which is usefull for crc calc or overwriting whole memory in mcu. Log writes text (new line formatted) output only when parsing ELF firmware file.
public void ParseFirmware(string FwPath)
{
Firmware fw1 = FwTools.Parse(FwPath); // Fw.Format = AUTO
Firmware fw2 = FwTools.Parse(FwPath, FillFF: true); // gaps are filled with 0xFF
Firmware fw3 = FwTools.Parse(FwPath, FwFormat.SREC); // Fw.Format = SREC
Firmware fw4 = FwTools.Parse(FwPath, Log: new StringWriter()); // save parse log
}Create firmware multi-line string in TI-TXT, Intel-HEX or SREC format. ELF is not supported yet. AUTO format will force TI-TXT format. AddrStart is address of first byte in data collection. LineLength defines amount of data bytes per one text row. When = 0, default values are set (TI-TXT = 16, Intel-HEX = 32, SREC = 32).
public void CreateFromFirmware(Firmware Fw)
{
string fw1 = Create(Fw); // Fw.Format = AUTO, Len = default
string fw2 = Create(Fw, FwFormat.INTEL_HEX); // Fw.Format = Intel-HEX
string fw3 = Create(Fw, LineLength: 64); // custom line length, compatibility
}
public void CreateFromRawData(IEnumerable<byte> RawData, int AddrStart)
{
string fw1 = Create(RawData, AddrStart); // Fw.Format = AUTO, Line Len = default
string fw2 = Create(RawData, AddrStart, FwFormat.TI_TXT); // Fw.Format = TI-TXT
string fw3 = Create(RawData, AddrStart, LineLength: 128); // custom fw line length
}
public void CreateFromFwNodes(ICollection<FwNode> FwNodes)
{
string fw1 = Create(FwNodes); // Fw.Format = AUTO, Line Len = default
string fw2 = Create(FwNodes, FwFormat.SREC); // Fw.Format = SREC
string fw3 = Create(FwNodes, LineLength: 24); // custom fw line length
}Convert firmware TI-TXT, Intel-HEX, ELF or SREC format (auto detected) to firmware in TI-TXT, Intel-HEX or SREC format. Returned Fw is firmware and Format is useful for auto-detect feedback, indicates input format. FillFF is optional parameter forcing to fill missing addr nodes with 0xFF and return monolithic piece of code, which is usefull for crc calc or overwriting whole memory in mcu. LineLength defines amount of data bytes per one text row. When = 0, default values are set (TI-TXT = 16, Intel-HEX = 32, SREC = 32).
public void ConvertFirmware(string FwPath)
{
// simple convert of firmware, format auto-detected, to TI-TXT
var (Fw1, Format1) = Convert(FwPath, FwFormat.TI_TXT);
// convert when gaps in firmware are filled with 0xFF
var ret2 = Convert(FwPath, FwFormat.INTEL_HEX, true);
// custom output line length: 16
var ret3 = Convert(FwPath, FwFormat.SREC, LineLength: 16);
}Combines two firmware files into single one with format specified. Usually, main firmware and EEPROM file is done this way, or main firmware and Info A flash content is merged. Returned Fw is firmware and Format1 with Format2 are useful for auto-detect feedback, indicates input formats. FillFF is optional parameter forcing to fill missing addr nodes with 0xFF and return monolithic piece of code, which is usefull for crc calc or overwriting whole memory in mcu. LineLength defines amount of data bytes per one text row. When = 0, default values are set (TI-TXT = 16, Intel-HEX = 32, SREC = 32).
public void CombineFirmwares(string FwPath1, string FwPath2)
{
// simple combine of two firmware files
var (Fw1, Format1, Format2) = Combine(FwPath1, FwPath2, FwFormat.TI_TXT);
// combine and fill gaps with 0xFF
var ret2 = Combine(FwPath1, FwPath2, FwFormat.TI_TXT, true);
// combine and set custom output line length
var ret3 = Combine(FwPath1, FwPath2, FwFormat.TI_TXT, LineLength: 64);
}Compare two Firmware files. If string arguments used, first, auto-detects format, then parse Nodes (Address + Data) and finally run compare. If Firmware class argument used, things are much easier. This method leverages overiden Euqals or equality operators in Firmware class. Equal = True if both files contains exactly same set of Firmware Nodes, in other case result is false. Equal = False if any Firmware is null or if any Firmware Node count is zero. Match [0.0 ; 1.0] is match when 1.0 is full match and Equal = True, and 0.0 is different fw. BytesDiff is count of bytes (Data nodes) which both firmwares differ at. 0 means full match.
public void CompareFirmwareFiles(string FwPath1, string FwPath2)
{
var (Equal, Match, BytesDiff) = Compare(FwPath1, FwPath2); // simple fw compare
}
public void CompareFirmwares(Firmware Firmware1, Firmware Firmware2)
{
var (Equal, Match, BytesDiff) = Compare(Firmware1, Firmware2); // fw class cmp
}Validate firmware file and return FwInfo class, with specific firmware information. ResetVector and SizeBuffer are MSP430 specifics, other properties are universal. Log writes text (new line formatted) output only when parsing ELF firmware file.
public void ValidateFirmware(string FwPath)
{
FwInfo fwInfo1 = Validate(FwPath); // simple firmware validation
FwInfo fwInfo2 = Validate(FwPath, new StringWriter()); // save parse log
// If firmware is invalid, Valid = false. Otherwise Valid = True
Console.WriteLine(fwInfo1.Valid);
// Firmware format. TI-TXT, Intel-HEX, ELF or SREC
Console.WriteLine(fwInfo1.Format);
// First address in firmware, max 32-bit, usually 16-bit
Console.WriteLine(fwInfo1.AddrFirst);
// Last address in firmware, max 32-bit, usually 16-bit
Console.WriteLine(fwInfo1.AddrLast);
// Total length of firmware, count of all bytes from first address to last
Console.WriteLine(fwInfo1.SizeFull);
// Real count of all bytes in firmware parsed from file
Console.WriteLine(fwInfo1.SizeCode);
// CRC-16-CCITT is 16-bit crc value of all data bytes in firmware
Console.WriteLine(fwInfo1.Crc16);
// [MSP430 specific] Reset vector is address (value) located usually at
// 16-bit address 0xFFFE.
Console.WriteLine(fwInfo1.ResetVector);
// List<long>. When parsing FW, FillFF can be set, to output code in single
// piece. Addresses, that dont belong to original FW, are in this list.
Console.WriteLine(fwInfo1.FilledFFAddr);
}[MSP430 specific] Read and parse firmware file (format auto-detected) and return BSL password. Password is last 16-byte (F543x-non-A only) or 32-byte (others) of IVT (FFE0-FFFF), if newer 5xx/6xx MCU is used. If MCU from older series is used (1xx/2xx/4xx), password is exactly 20-byte long. Mostly it is 32-byte.
public void GetBSLPassword(string FwPath)
{
BslPasswords pw = GetPassword(FwPath); // read/parse fw file and get pw
// 32-Byte mostly used in todays MSP430, 5xx/6xx series except F543x (non A).
Console.WriteLine(BitConverter.ToString(pw.Password32Byte));
// 16-Byte used only in the very first series of 5xx, the F543x (non A)
Console.WriteLine(BitConverter.ToString(pw.Password16Byte));
// 20-byte long Password used in old 1xx/2xx/4xx series
Console.WriteLine(BitConverter.ToString(pw.Password20Byte));
}