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

Go to the source code of this file.


union  tag_typeS
 Motorola S-Record Type Infos. More...
struct  tag_linedat
 Struct that characterizes a data line. More...
struct  tag_xcog1
 Cog parameters for ledstat(). More...
struct  tag_xcog0
 Cog parameters for burn(). More...
struct  tag_chip
 Struct that characterizes a chip. More...


#define HEADER_KICK   " Zerocat Chipflasher: kick " VERSION " "
#define SIZE_STR_MESSAGE   (1 << 7)
#define SIZE_STRBUF   (1 << 8)
#define SIZE_LINEBUF   (1 << 8)
#define BAUDRATE_DEFAULT   115200
 propeller-load default baudrate More...
#define NOT_APPLICABLE   -1
 some chipspec members may not make sense for some chips More...
#define POWERUP_SPI   25
 Give the attached system board some time to power up. Time in milliseconds. More...
 Give SPI lines some time to power up (i.e. GA-G41M-ES2L). More...
#define POWERUP_EXTRA   2
 If chip detection fails, how often shall we retry? More...
#define POWERUP_OFFTIME   100000
 Separate multiple chip detections, time in µ-seconds. More...
#define STACK_DEFAULT   0x40
 Default stack size for any extra cog function, then to be optimized. More...
#define STACK_BURNBUF   0x20
 Stack size for burn(). More...
#define STACK_LEDSTAT   0x20
 Stack size for ledstat(). More...
#define MAX_POLLING   100000000
 Set a timeout value for the WIP polling routine. More...
#define MODE_TERMINAL   0x01
#define MODE_CONNECT   0x02
#define MODE_SPI_OFF   0x00
#define MODE_FORCE_SPI_OFF   0x01
#define MODE_SPI_POWEROFF   0x02
#define LOOP_RES   ((CLKFREQ / 1000000) * 1000)
#define STATUS_CYCLE   1000
#define LED_PHASE   90
#define PUTCHAR_CR
#define PUTCHAR_NL
#define GET_CHAR_GROUP(n)
#define MSG_DONE   "...done.\r\n\n"
#define SPI_ON   SPI_ini()
#define SPI_OFF(mode)   SPI_off(mode)


enum  tag_cmdstat { cmd_off = 0, cmd_on, cmd_CP }
enum  tag_spimode { mode_0 = 0, mode_3 }
enum  tag_type_of_addrlen { ADDRLEN_IN_BYTES = 0, ADDRLEN_MOT, ADDRLEN_IN_BITS }
enum  tag_blocksize { BLOCK_4K = SIZE_4K, BLOCK_32K = SIZE_32K, BLOCK_64K = SIZE_64K }


int hex2bin (unsigned char a, unsigned char b)
 Converts a pair of hexadecimal chars into binary value. More...
void chip_erase (void)
 This function calls the global chip erase command. More...
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...
char HEXDUMP_rxline (struct tag_xcog0 *px, unsigned int *lines)
 Parse a Hexdump line. 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...
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...
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...
void chip_txfile (struct tag_filespec *filespec, unsigned char addrlen_in_bits, unsigned int firstloc, unsigned int memsize, unsigned char screenmode)
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 cmd_DP (void)
signed char linebuf_out (char *linebuf)
 Put a formatted data line onto tty. 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 outbits (const unsigned int value, unsigned int msbit)
int cmd_RDID_JEDEC (void)
char queue (struct tag_xcog0 *px, unsigned char vbin, unsigned int *pwr)
void chip_rxfile (struct tag_xcog0 *px, char screen_output)
signed char chip_read (struct tag_filespec *filespec, unsigned int firstloc, unsigned int memsize, unsigned int *lines, char *linebuf)
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_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)
void chip_ini (unsigned char new_index)
unsigned int CPM_polling (void)
 Poll CPM bit. More...
void PGM_cycle (enum tag_cmdstat *cmdstat, unsigned char odd_tracker)
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...
unsigned char inb (void)
unsigned int inbits (unsigned int msbit)
void key_config (void)
 Enable menu keys according to chip specs. More...
void menu_options (void)
 Put menu options on terminal screen. More...
void greeting ()
 Put a small headline on terminal screen that helps to identify the program. More...
unsigned char yes_no (char *question, unsigned char level_rst)
 This function allows to put a question which expects true or false. More...
void exit_sequence (const char status)
 Tell terminal to exit listening mode. More...
void SPI_ini (void)
 Initialize SPI bus; activate hardware write protection. More...
void SPI_off (int mode)
 Switch SPI bus off. More...
int WIP_polling (void)
 Determine end of write cycle by polling the WIP bit. More...
int strpos (char *str, char c)
 Report the position of a character in a string. More...
void cmd (const unsigned char cmd, const unsigned int value, unsigned char bits)
unsigned char cmd_RDSR (unsigned char regno)
 Read the status register. More...
void cmd_WRSR (const unsigned char regno, const unsigned char byte)
 Write to Status Registers. More...
unsigned char SR_report (unsigned char regno)
 Put status register's content on screen. More...
void SR_intro (unsigned char regno)
 Provide each bit listing of an status register with a short header. More...
void cmd_WREN (void)
 Set Write Enable Latch bit. More...
void cmd_WRDI (void)
void global_sector_protect (unsigned char pswitch)
 Method to globally protect/unprotect all sectors. More...
void option_readblock (const enum tag_blocksize blocksize)
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...
int do__WIP_polling (void)
 Invoking WIP_polling() usually is accompanied by some checks and messages. 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 range_error (void)
 Reports an Out-of-Range user input error and resets xcog1.inlevel. More...
void page_write (const unsigned int addr, unsigned char *buffer)
 Write a page buffer to chip. 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...
char outfifo (char c)
int outstr (char *s)
void connected (void)
void hr (char c, int n, char nl)
 Put a horizontal line on screen. More...
void mirror (char *keymsg)
void putChar (char c)
void report_err (char reported_err)
void check_dryrun (void)
 Checks wether a write fail should be expected. A function with very basic and poor functionality. 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.

Definition in file kick.h.

Macro Definition Documentation


#define BAUDRATE_DEFAULT   115200

Definition at line 69 of file kick.h.



Definition at line 60 of file kick.h.


#define GET_CHAR_GROUP (   n)
for(unsigned char i = 0; i < n; i++) { \
c[i] = outfifo(getChar()); \

Definition at line 103 of file kick.h.


#define HEADER_KICK   " Zerocat Chipflasher: kick " VERSION " "

Definition at line 65 of file kick.h.


#define LED_PHASE   90

Definition at line 92 of file kick.h.


#define LOOP_RES   ((CLKFREQ / 1000000) * 1000)

Definition at line 90 of file kick.h.


#define MAX_POLLING   100000000

Definition at line 78 of file kick.h.


#define MODE_CONNECT   0x02

Definition at line 82 of file kick.h.


#define MODE_FORCE_SPI_OFF   0x01

Definition at line 86 of file kick.h.


#define MODE_SPI_OFF   0x00

Definition at line 85 of file kick.h.


#define MODE_SPI_POWEROFF   0x02

Definition at line 87 of file kick.h.


#define MODE_TERMINAL   0x01

Definition at line 81 of file kick.h.


#define MSG_DONE   "...done.\r\n\n"

Definition at line 107 of file kick.h.


#define NOT_APPLICABLE   -1

Definition at line 70 of file kick.h.


#define POWERUP_EXTRA   2

Definition at line 73 of file kick.h.


#define POWERUP_OFFTIME   100000

Definition at line 74 of file kick.h.


#define POWERUP_SPI   25

Definition at line 71 of file kick.h.



Definition at line 72 of file kick.h.


#define PUTCHAR_CR
do { \
outfifo(CARR_RET); \
} while(0)

Definition at line 95 of file kick.h.


#define PUTCHAR_NL
do { \
outfifo(NEW_LINE); \
} while(0)

Definition at line 99 of file kick.h.


#define SIZE_LINEBUF   (1 << 8)

Definition at line 68 of file kick.h.


#define SIZE_STR_MESSAGE   (1 << 7)

Definition at line 66 of file kick.h.


#define SIZE_STRBUF   (1 << 8)

Definition at line 67 of file kick.h.


#define SPI_OFF (   mode)    SPI_off(mode)

Definition at line 110 of file kick.h.


#define SPI_ON   SPI_ini()

Definition at line 109 of file kick.h.


#define STACK_BURNBUF   0x20

Definition at line 76 of file kick.h.


#define STACK_DEFAULT   0x40

Definition at line 75 of file kick.h.


#define STACK_LEDSTAT   0x20

Definition at line 77 of file kick.h.


#define STATUS_CYCLE   1000

Definition at line 91 of file kick.h.

Enumeration Type Documentation

◆ tag_blocksize


Definition at line 131 of file kick.h.

◆ tag_cmdstat


Definition at line 114 of file kick.h.

◆ tag_spimode


Definition at line 120 of file kick.h.

◆ tag_type_of_addrlen


Definition at line 125 of file kick.h.

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.

◆ 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.

◆ putChar()

void putChar ( char  c)

Definition at line 46 of file putChar.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.

#define NEW_LINE
Ascii LF "\n" 'line feed'.
Definition: serial-codes.h:53
char outfifo(char c)
Definition: kick.c:1615
#define CARR_RET
Ascii CR "\r" 'carriage return'.
Definition: serial-codes.h:54