# Parse a single line of S-record, validate the line, and extract the address
# and data fields. Return a list of three scalars:
#  1. TRUE if extraction was successful, FALSE otherwise (i.e. not a valid data
#     carrying S-record, bad s-record length, bad s-record checksum).
#  2. The address of the line's payload, as a string.
#  3. The data of the line's payload, as a string.
sub ProcessSrecLine
{
    my $line = shift;
    
    # Get rid of all line endings, regardless of which flavor they are
    $line =~ s/(\n|\r)//g;

    # be a pessimist
    my $status = 0;
    my $type;
    my $count;
    my $address;
    my $data;
    my $cs;

    # does this look like a S1, S2, or S3 record? These are the only ones that
    # carry an actual data payload. Other record types do not, so just ignore
    # them.
    if (
        ($line =~ /^s(1)([0-9a-f]{2})([0-9a-f]{4})([0-9a-f]+)([0-9a-f]{2})$/i) ||
        ($line =~ /^s(2)([0-9a-f]{2})([0-9a-f]{6})([0-9a-f]+)([0-9a-f]{2})$/i) ||
        ($line =~ /^s(3)([0-9a-f]{2})([0-9a-f]{8})([0-9a-f]+)([0-9a-f]{2})$/i)
       )
    {
        $type = $1;
        $count = $2;
        $address = $3;
        $data = $4;
        $cs = $5;

        # Make sure the COUNT field makes sense. It should represent the sum of
        # address, data, and checksum fields, in bytes
        if ( hex($count) == ((length($address) + length($data) + length($cs)) / 2) )
        {
            # Make sure the checksum makes sense. It is the two's complement of
            # the sum of count, address, and data fields
            my $compCs = hex($count);
            for (my $i=0; $i<length($address); $i+=2)
            {
                $compCs += hex(substr($address, $i, 2)); 
            }
            for (my $i=0; $i<length($data); $i+=2)
            {
                $compCs += hex(substr($data, $i, 2)); 
            }
            $compCs %= 256;
            $compCs = 255 - $compCs;

            # if the checksum actually matches, then call it a good S-record
            if ($compCs == hex($cs))
            {
                $status = 1;
            }
        }

        return ($status, $address, $data);
    }
}