mac-rom-simm-programmer/programmer_protocol.h
Doug Brown 8b1cd63210 Change license to GPLv3
I can't use GPLv2 as soon as I need to start using the Nuvoton sample
code which is licensed with an Apache 2.0 license.
2023-09-10 05:02:44 -07:00

201 lines
7.4 KiB
C

/*
* programmer_protocol.h
*
* Created on: Dec 26, 2011
* Author: Doug
*
* Copyright (C) 2011-2023 Doug Brown
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*
*/
#ifndef PROGRAMMER_PROTOCOL_H_
#define PROGRAMMER_PROTOCOL_H_
/// When the programmer is in "waiting for command" mode,
/// you send it one of the bytes below to do something (or begin to do something)
typedef enum ProgrammerCommand
{
EnterWaitingMode = 0,
DoElectricalTest,
IdentifyChips,
ReadByte,
ReadChips,
EraseChips,
WriteChips,
GetBootloaderState,
EnterBootloader,
EnterProgrammer,
BootloaderEraseAndWriteProgram,
SetSIMMTypePLCC32_2MB,
SetSIMMTypeLarger,
SetVerifyWhileWriting,
SetNoVerifyWhileWriting,
ErasePortion,
WriteChipsAt,
ReadChipsAt,
SetChipsMask,
SetSectorLayout,
GetFirmwareVersion
} ProgrammerCommand;
// After a command is sent, the programmer will always respond with
// one of the replies below. (Depending on the command, it may reply with other
// stuff after that, too)
typedef enum ProgrammerReply
{
CommandReplyOK = 0,
CommandReplyError,
CommandReplyInvalid
} ProgrammerReply;
// ------------------------- ELECTRICAL TEST PROTOCOL -------------------------
// After CommandReplyOK, any failures are reported by the programmer.
// It will send ProgrammerElectricalTestFail followed by two more bytes -- each
// representing an index of the failure location. Any more electrical test failures
// will result in another 3-byte sequence as described above.
// When it's totally finished, it will send ProgrammerElectricalTestDone.
// So a pass would be indicated by no ProgrammerElectricalTestFail sequences being
// sent.
typedef enum ProgrammerElectricalTestReply
{
ProgrammerElectricalTestFail = 0,
ProgrammerElectricalTestDone
} ProgrammerElectricalTestReply;
// ------------------------- IDENTIFY CHIPS PROTOCOL -------------------------
// After CommandReplyOK, it will send the manufacturer ID and device ID of each
// of the 4 chips:
// M1, D1, M2, D2, M3, D3, M4, D4
// followed by ProgrammerIdentifyDone.
typedef enum ProgrammerIdentifyReply
{
ProgrammerIdentifyDone = 0
} ProgrammerIdentifyReply;
// ------------------------- READ PROTOCOL -------------------------
// After CommandReplyOK, the requester will send a 4-byte value containing
// the number of bytes requested to read (should be a multiple of the read
// chunk size of 1024 bytes, though). The programmer will reply with OK or
// error, and if OK, also send a chunk of data.
// The computer will send a reply (see the enum below this one)
// The programmer will then reply to *that* reply (see this enum)
typedef enum ProgrammerReadReply
{
ProgrammerReadOK = 0,
ProgrammerReadError,
ProgrammerReadMoreData,
ProgrammerReadFinished,
ProgrammerReadConfirmCancel
} ProgrammerReadReply;
// When the computer is confirming reception of a block of data from the device,
// it should reply with either OK that it received the data OK, or cancel
// to tell the device that the user canceled the read.
typedef enum ComputerReadReply
{
ComputerReadOK = 0,
ComputerReadCancel
} ComputerReadReply;
// ------------------------- ERASE PROTOCOL -------------------------
// There is none -- a reply of CommandReplyOK will indicate that the erase
// completed successfully.
// ------------------------- WRITE PROTOCOL -------------------------
// After CommandReplyOK, the computer should send one of the commands below.
// The programmer will reply with one of the replies seen in the enum below
// this one, and then the computer can send a 1024-byte chunk of data.
// The programmer will reply with ProgrammerWriteOK, and then the cycle can
// continue (the computer sends another request in this enum)
//
// If the programmer was asked to verify while writing and a verification error
// occurs, it will respond with ProgrammerWriteVerificationError ORed with a bit
// mask of chips that are acting up (so it could be 0x81 if IC1 is acting up,
// for example)
typedef enum ComputerWriteRequest
{
ComputerWriteMore = 0,
ComputerWriteFinish,
ComputerWriteCancel
} ComputerWriteRequest;
typedef enum ProgrammerWriteReply
{
ProgrammerWriteOK = 0,
ProgrammerWriteError,
ProgrammerWriteConfirmCancel,
ProgrammerWriteVerificationError = 0x80 /* high bit signifies verify error, low bits signify which chips are bad */
} ProgrammerWriteReply;
// ------------------------- BOOTLOADER STATE PROTOCOL -------------------------
// If the command is GetBootloaderState, it will reply with CommandReplyOK followed
// by one of the two replies below to tell the control program which mode
// the device is currently in.
typedef enum BootloaderStateReply
{
BootloaderStateInBootloader = 0,
BootloaderStateInProgrammer
} BootloaderStateReply;
// ------------------------- BOOTLOADER ERASE/WRITE PROTOCOL -------------------------
// If the command is BootloaderEraseAndWriteProgram, it will reply with CommandReplyOK
// followed by either BootloaderEraseOK or BootloaderEraseError. At this point
// the program can ask to write more data or finish or cancel, and then the appropriate
// reply will be sent back to it. Works very similar to the write protocol.
typedef enum ProgrammerBootloaderEraseWriteReply
{
BootloaderWriteOK,
BootloaderWriteError,
BootloaderWriteConfirmCancel
} ProgrammerBootloaderEraseWriteReply;
typedef enum ComputerBootloaderEraseWriteRequest
{
ComputerBootloaderWriteMore = 0,
ComputerBootloaderFinish,
ComputerBootloaderCancel
} ComputerBootloaderEraseWriteRequest;
// ------------------------- ERASE PORTION OF CHIP PROTOCOL -------------------------
// If the command is ErasePortion, the programmer will reply CommandReplyOK.
// Next, the program will send the beginning position to erase as a 4-byte little
// endian integer, followed by the length to erase as a 4-byte little endian
// integer. The programmer will reply with ProgrammerErasePortionOK to signify
// that the erase is beginning, followed by ProgrammerErasePortionFinished when
// everything is done.
// The length and position to erase must be on 256 KB boundaries and shouldn't
// go past the end of the selected type of chip. If any error occurs, it will
// reply with ProgrammerErasePortionError instead.
typedef enum ProgrammerErasePortionOfChipReply
{
ProgrammerErasePortionOK = 0,
ProgrammerErasePortionError,
ProgrammerErasePortionFinished
} ProgrammerErasePortionOfChipReply;
// ------------------------- GET FIRMWARE VERSION PROTOCOL -------------------------
// If the command is GetFirmwareVersion, the programmer will reply CommandReplyOK.
// Next, it will return 4 bytes: major version, minor version, revision, and a final
// byte where 0 means it's a normal version and 1 means it's a prerelease version.
// Other values are reserved.
// Finally, it will finish the response with ProgrammerGetFWVersionDone.
typedef enum ProgrammerGetFWVersionReply
{
ProgrammerGetFWVersionDone
} ProgrammerGetFWVersionReply;
#endif /* PROGRAMMER_PROTOCOL_H_ */