Zerocat Chipflasher  v0.4.3 (board-edition-1)
Flash free firmware to BIOS chips, kick the Manageability Engine.
Macros | Functions | Variables
kick.c File Reference

This file contains the main() procedure of the chipflasher firmware. More...

#include "simpletext.h"
#include "simpletools.h"
#include <ctype.h>
#include "libprop/putChar.h"
#include "libcommon/common.h"
#include "libcommon/serial-codes.h"
#include "libcommon/filespec.h"
#include "libSPI/SPI-command-set.h"
#include "libSPI/SPI-flash-bits.h"
#include "libkick/proppins.h"
#include "libkick/chipspec.h"
#include "libkick/key-enable-bits.h"
#include "libkick/fast-SPI.h"
#include "kick.h"
#include "libprop/putChar.c"
#include "libcommon/hexdigit2bin.c"
#include "libcommon/bin2hexdigit.c"
#include "libcommon/filespec.c"
#include "libkick/chipspec.c"

Go to the source code of this file.


#define SCANNING_DATA   0x00
#define DATA_START   0x01
#define FF_START   0x02
#define SCANNING_FF   0x03
#define APPLY_CUT   0x01
#define HAS_NOT_BEEN_CUT_YET   0x02
#define IS_0XFF   0x04
#define MODE_0XFF   filespec->mode_0xff
#define PAYLOAD_DEFAULT   (filespec->payload_default)


int main (void)
 This is main() of kick, the firmware. More...
void connected (void)
void mirror (char *keymsg)
void option_readblock (const enum tag_blocksize blocksize)
int do__WIP_polling (void)
 Invoking WIP_polling() usually is accompanied by some checks and messages. More...
void range_error (void)
 Reports an Out-of-Range user input error and resets xcog1.inlevel. More...
void option_batchblockerase (const enum tag_blocksize blocksize, const unsigned char blockcmd)
 Versatile block erase function, which allows erasing of multiple blocks of different sizes, i.e. 4K (sectors), 32K and 64K. More...
void SR_intro (unsigned char regno)
 Provide each bit listing of an status register with a short header. More...
void global_sector_protect (unsigned char pswitch)
 Method to globally protect/unprotect all sectors. More...
void key_polling (unsigned char *key_is_valid, unsigned char *quit)
 Essential function. Scans stdin for configured keys and issues the apropriate actions. Typing 'q' quits this routine. More...
void check_dryrun (void)
 Checks wether a write fail should be expected. A function with very basic and poor functionality. More...
int plug_detect (void)
 Check if an SPI-Plug is detected and put a message on screen. More...
void menu (unsigned char mode)
 Put the chipflasher menu on screen and invoke key_polling(). More...
void hr (char c, int n, char nl)
 Put a horizontal line on screen. More...
unsigned char get_addrlen (enum tag_type_of_addrlen type_of_addrlen, unsigned int addr)
 Auxiliary function that returns the length of an address for different situations. More...
void key_config (void)
 Enable menu keys according to chip specs. More...
void menu_line (unsigned int k1, char *k1msg, unsigned int k2, char *k2msg, unsigned int k3, char *k3msg)
 Put a menu line with selected menu options on terminal screen. More...
void menu_options (void)
 Put menu options on terminal screen. More...
unsigned char verify_0xff (unsigned int firstloc, unsigned int memsize)
 This function scans the specified chip memory for values different than 0xff. If a value different to 0xff is found, an error status is returned. More...
void MOT_mkline (struct tag_linedat *linedat, union tag_typeS *typeS, char *linebuf)
 This function wraps a binary payload into a Motorola S-record frame. More...
int strpos (char *str, char c)
 Report the position of a character in a string. More...
void MOT_header (char *header, char *linebuf)
 This function invokes MOT_mkline(), but initializes parameters first with apropriate header data. More...
void MOT_data (struct tag_linedat *linedat, char *linebuf)
void MOT_summary (unsigned int lines, char *linebuf)
unsigned char yes_no (char *question, unsigned char level_rst)
 This function allows to put a question which expects true or false. More...
void chip_ini (unsigned char new_index)
signed char chip_read (struct tag_filespec *filespec, unsigned int firstloc, unsigned int memsize, unsigned int *lines, char *linebuf)
void chip_txfile (struct tag_filespec *filespec, unsigned char addrlen_in_bits, unsigned int firstloc, unsigned int memsize, unsigned char screenmode)
signed char linebuf_out (char *linebuf)
 Put a formatted data line onto tty. More...
char outfifo (char c)
int outstr (char *s)
void HEXDUMP_mkline (struct tag_linedat *linedat, char *linebuf_orig)
 This function transforms a binary payload into a row of ascii chars including line ending characters and stores it in a buffer. More...
void greeting ()
 Put a small headline on terminal screen that helps to identify the program. More...
void cmd_WREN (void)
 Set Write Enable Latch bit. More...
void cmd_WRSR (const unsigned char regno, const unsigned char byte)
 Write to Status Registers. More...
void page_write (const unsigned int addr, unsigned char *buffer)
 Write a page buffer to chip. More...
void exit_sequence (const char status)
 Tell terminal to exit listening mode. More...
int WIP_polling (void)
 Determine end of write cycle by polling the WIP bit. More...
unsigned int CPM_polling (void)
 Poll CPM bit. More...
unsigned char SR_report (unsigned char regno)
 Put status register's content on screen. More...
unsigned char inb (void)
unsigned int inbits (unsigned int msbit)
void outbits (const unsigned int value, unsigned int msbit)
void cmd (const unsigned char cmd, const unsigned int value, unsigned char bits)
int cmd_RDID_JEDEC (void)
void cmd_DP (void)
unsigned char cmd_RDSR (unsigned char regno)
 Read the status register. More...
void cmd_WRDI (void)
void SPI_ini (void)
 Initialize SPI bus; activate hardware write protection. More...
void SPI_off (int mode)
 Switch SPI bus off. More...
int hex2bin (unsigned char a, unsigned char b)
 Converts a pair of hexadecimal chars into binary value. More...
void PGM_cycle (enum tag_cmdstat *cmdstat, unsigned char odd_tracker)
void ledstat ()
 This function controls board LEDs. To be used with extra cog, to be stopped externally. More...
void burn ()
 Wite data to chip. More...
void MOT_typeS_fillup (union tag_typeS *typeS)
 Generating and parsing a Motorola S-record line needs to have some specs available about the line in question. This function fills a struct, based on some data that can be provided during runtime, to have all specs available when needed. More...
char HEXDUMP_rxline (struct tag_xcog0 *px, unsigned int *lines)
 Parse a Hexdump line. More...
char MOT_rxline (struct tag_xcog0 *px, unsigned int *lines, int hexmode)
 Receive and parse a line in Motorola S-Record format. This func finishes successfully after having parsed the line's checksum data, thus not evaluating any line ending characters. More...
char queue (struct tag_xcog0 *px, unsigned char vbin, unsigned int *pwr)
void report_err (char reported_err)
void chip_rxfile (struct tag_xcog0 *px, char screen_output)
void chip_erase (void)
 This function calls the global chip erase command. More...


int _cfg_modeterminal = -1
 configured through propeller-load More...
int _cfg_rstdisable = -1
 configured through propeller-load More...
int _cfg_baudrate = -1
 configured through propeller-load More...
unsigned char cmd_CE = CMD__CE_0X60
 Global chip erase command, may be overridden by key_config(). More...
struct tag_xcog0 xcog0
 Cog parameters for burn(). More...
struct tag_xcog1 xcog1
 Cog parameters for ledstat(). More...
enum tag_spimode spimode = mode_3
 SPI mode to be used through the whole program. More...
struct tag_chip chip = { 0, chipspec }
struct tag_filespecpfspec
 Pointer to specifications that are associated with selected format type. More...

Detailed Description

Zerocat Chipflasher — Flash free firmware to BIOS chips, kick the Manageability Engine.

Copyright (C) 2015, 2016, 2017, 2018 Kai Mertens

The Zerocat Chipflasher 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.

The Zerocat Chipflasher 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

This file is part of the Zerocat Chipflasher.

Implement a better initial handshake with connect.
Update schematic according to AN 'interfacing higher voltages'.


Broken Chips

Definition in file kick.c.

Macro Definition Documentation


#define APPLY_CUT   0x01


#define DATA_START   0x01


#define FF_START   0x02


#define HAS_NOT_BEEN_CUT_YET   0x02




#define IS_0XFF   0x04


#define MODE_0XFF   filespec->mode_0xff


#define PAYLOAD_DEFAULT   (filespec->payload_default)


#define SCANNING_DATA   0x00


#define SCANNING_FF   0x03

Function Documentation

◆ burn()

void burn ( )
To be used with extra cog. To be stopped externally.
Parameters are organized in struct tag_xcog0. Not all members have to be declared volatile.
Do not declare flags as volatile bitfield struct. It doesn't work.

< Run control.

Definition at line 2349 of file kick.c.

◆ check_dryrun()

void check_dryrun ( void  )
Shall we ignore bit 7 of all chips for the test?

Definition at line 820 of file kick.c.

◆ chip_erase()

void chip_erase ( void  )

Note that this function will be invoked only if the respective menu option is available.

Definition at line 3000 of file kick.c.

◆ chip_ini()

void chip_ini ( unsigned char  new_index)
What happens on division by zero?

Definition at line 1331 of file kick.c.

◆ chip_read()

signed char chip_read ( struct tag_filespec filespec,
unsigned int  firstloc,
unsigned int  memsize,
unsigned int *  lines,
char *  linebuf 

Definition at line 1345 of file kick.c.

◆ chip_rxfile()

void chip_rxfile ( struct tag_xcog0 px,
char  screen_output 

Definition at line 2861 of file kick.c.

◆ chip_txfile()

void chip_txfile ( struct tag_filespec filespec,
unsigned char  addrlen_in_bits,
unsigned int  firstloc,
unsigned int  memsize,
unsigned char  screenmode 

Definition at line 1507 of file kick.c.

◆ cmd()

void cmd ( const unsigned char  cmd,
const unsigned int  value,
unsigned char  bits 

Definition at line 2017 of file kick.c.

◆ cmd_DP()

void cmd_DP ( void  )

Definition at line 2045 of file kick.c.

◆ cmd_RDID_JEDEC()

int cmd_RDID_JEDEC ( void  )

Definition at line 2029 of file kick.c.

◆ cmd_RDSR()

unsigned char cmd_RDSR ( unsigned char  regno)
Returns the content of the status register.

Definition at line 2069 of file kick.c.

◆ cmd_WRDI()

void cmd_WRDI ( void  )

Definition at line 2098 of file kick.c.

◆ cmd_WREN()

void cmd_WREN ( void  )

Definition at line 1727 of file kick.c.

◆ cmd_WRSR()

void cmd_WRSR ( const unsigned char  regno,
const unsigned char  byte 

Definition at line 1743 of file kick.c.

◆ connected()

void connected ( void  )

Definition at line 182 of file kick.c.

◆ CPM_polling()

unsigned int CPM_polling ( void  )

Definition at line 1903 of file kick.c.

◆ do__WIP_polling()

int do__WIP_polling ( void  )

Definition at line 251 of file kick.c.

◆ exit_sequence()

void exit_sequence ( const char  status)
statusA status byte could be passed as well.

Definition at line 1862 of file kick.c.

◆ get_addrlen()

unsigned char get_addrlen ( enum tag_type_of_addrlen  type_of_addrlen,
unsigned int  addr 

Definition at line 939 of file kick.c.

◆ global_sector_protect()

void global_sector_protect ( unsigned char  pswitch)

Definition at line 387 of file kick.c.

◆ greeting()

void greeting ( )

Definition at line 1711 of file kick.c.

◆ hex2bin()

int hex2bin ( unsigned char  a,
unsigned char  b 
aFirst char (i.e. msnibble) of the character pair.
bSecond char (i.e. lsnibble) of the character pair.
Returns binary value 0x00 to 0xff or -1 if no validation possible.

Definition at line 2209 of file kick.c.

◆ hr()

void hr ( char  c,
int  n,
char  nl 

Definition at line 919 of file kick.c.

◆ inb()

unsigned char inb ( void  )

Definition at line 1971 of file kick.c.

◆ inbits()

unsigned int inbits ( unsigned int  msbit)

Definition at line 1980 of file kick.c.

◆ key_config()

void key_config ( void  )

Definition at line 971 of file kick.c.

◆ key_polling()

void key_polling ( unsigned char *  key_is_valid,
unsigned char *  quit 

Definition at line 420 of file kick.c.

◆ ledstat()

void ledstat ( )
Values greater than 5 for xcog1.inlevel are not supported with current settings for STATUS_CYCLE and LED_PHASE.

Definition at line 2266 of file kick.c.

◆ linebuf_out()

signed char linebuf_out ( char *  linebuf)
*linebufPointer to the prepared line, NULL is used to skip the line while keeping the STX/ETX/CAN protocol.
Returns -1 if the line has not been acknowledged by connect.

Definition at line 1592 of file kick.c.

◆ main()

int main ( void  )
Never returns.

Notes on Boot Conditions:

  1. SPI power is disabled during boot, because the pnp MOSFET does not switch on with its gate pulled up and PIN_PNP_DEVICE being in tristate.
  2. ledstat() is started on another cog, and won't be disabled other by switching the board off.
  3. _cfg_rstdisable allows to disable the RST line for a while, so that the system may be started from RAM.
  4. _cfg_baudrate will always be patched by propeller-load, even if not specified in the board config file. Its default value is 115200.
  5. _cfg_modeterminal allows to start a basic propeller-terminal communication instead of talking to connect, meant as a simple proof-of-concept. Btw, the propeller exit sequence is understood by both: connect and (of course) propeller-terminal.

Definition at line 116 of file kick.c.

◆ menu()

void menu ( unsigned char  mode)

Definition at line 866 of file kick.c.

◆ menu_line()

void menu_line ( unsigned int  k1,
char *  k1msg,
unsigned int  k2,
char *  k2msg,
unsigned int  k3,
char *  k3msg 

Definition at line 1040 of file kick.c.

◆ menu_options()

void menu_options ( void  )

Definition at line 1071 of file kick.c.

◆ mirror()

void mirror ( char *  keymsg)

Definition at line 193 of file kick.c.

◆ option_batchblockerase()

void option_batchblockerase ( const enum tag_blocksize  blocksize,
const unsigned char  blockcmd 

Definition at line 291 of file kick.c.

◆ option_readblock()

void option_readblock ( const enum tag_blocksize  blocksize)

Definition at line 204 of file kick.c.

◆ outbits()

void outbits ( const unsigned int  value,
unsigned int  msbit 

Definition at line 1997 of file kick.c.

◆ outfifo()

char outfifo ( char  c)

Definition at line 1615 of file kick.c.

◆ outstr()

int outstr ( char *  s)

Definition at line 1629 of file kick.c.

◆ page_write()

void page_write ( const unsigned int  addr,
unsigned char *  buffer 
This func is to be used with paged memories only.
addrPage start address.
*bufferPointer to page buffer.

Definition at line 1806 of file kick.c.

◆ PGM_cycle()

void PGM_cycle ( enum tag_cmdstat cmdstat,
unsigned char  odd_tracker 

Definition at line 2228 of file kick.c.

◆ plug_detect()

int plug_detect ( void  )

Definition at line 845 of file kick.c.

◆ queue()

char queue ( struct tag_xcog0 px,
unsigned char  vbin,
unsigned int *  pwr 

Definition at line 2831 of file kick.c.

◆ range_error()

void range_error ( void  )

Definition at line 275 of file kick.c.

◆ report_err()

void report_err ( char  reported_err)

Definition at line 2848 of file kick.c.

◆ SPI_ini()

void SPI_ini ( void  )

Initialise SPI lines:

  • activate pnp mosfet and power chip on
  • activate hardware write protection
  • PIN_MISO is always tristate, for it is used as input
  • setup clock level according to spimode
  • activate selected clock pins

Definition at line 2121 of file kick.c.

◆ SPI_off()

void SPI_off ( int  mode)

To enhance security, deep power down is entered right before switching off SPI power. When the SPI chip is powered on later with SPI_ini(), it will not start in deep power down mode, but in normal standby mode.

Leave pins in tristate condition, they might be used by other cogs!

Definition at line 2166 of file kick.c.

◆ SR_intro()

void SR_intro ( unsigned char  regno)

Definition at line 369 of file kick.c.

◆ SR_report()

unsigned char SR_report ( unsigned char  regno)

Definition at line 1929 of file kick.c.

◆ strpos()

int strpos ( char *  str,
char  c 

Definition at line 1214 of file kick.c.

◆ verify_0xff()

unsigned char verify_0xff ( unsigned int  firstloc,
unsigned int  memsize 

Definition at line 1122 of file kick.c.

◆ WIP_polling()

int WIP_polling ( void  )

Definition at line 1878 of file kick.c.

◆ yes_no()

unsigned char yes_no ( char *  question,
unsigned char  level_rst 

If it is used as a last security check before some delicate action takes place, level_rst should be zero in order to flag that no more inquiry will follow.

Definition at line 1303 of file kick.c.

Variable Documentation

◆ _cfg_baudrate

int _cfg_baudrate = -1

Definition at line 75 of file kick.c.

◆ _cfg_modeterminal

int _cfg_modeterminal = -1

Definition at line 73 of file kick.c.

◆ _cfg_rstdisable

int _cfg_rstdisable = -1

Definition at line 74 of file kick.c.

◆ chip

struct tag_chip chip = { 0, chipspec }

Definition at line 82 of file kick.c.

◆ cmd_CE

unsigned char cmd_CE = CMD__CE_0X60

Definition at line 78 of file kick.c.

◆ pfspec

struct tag_filespec* pfspec

Definition at line 83 of file kick.c.

◆ spimode

enum tag_spimode spimode = mode_3

Definition at line 81 of file kick.c.

◆ xcog0

struct tag_xcog0 xcog0

Definition at line 79 of file kick.c.

◆ xcog1

struct tag_xcog1 xcog1

Definition at line 80 of file kick.c.