1 /* Copyright 2016 The ChromiumOS Authors 2 * Use of this source code is governed by a BSD-style license that can be 3 * found in the LICENSE file. 4 */ 5 6 #ifndef __EC_CHIP_G_UPGRADE_FW_H 7 #define __EC_CHIP_G_UPGRADE_FW_H 8 9 #include <stddef.h> 10 11 #include "common.h" /* For __packed. */ 12 13 /* 14 * This file contains structures used to facilitate cr50 firmware updates, 15 * which can be used on any g chip. 16 * 17 * The firmware update protocol consists of two phases: connection 18 * establishment and actual image transfer. 19 * 20 * Image transfer is done in 1K blocks. The host supplying the image 21 * encapsulates blocks in frames by prepending a header including the flash 22 * offset where the block is destined and its digest. 23 * 24 * The CR50 device responds to each frame with a confirmation which is 1 byte 25 * response. Zero value means success, non zero value is the error code 26 * reported by CR50. 27 * 28 * To establish the connection, the host sends a different frame, which 29 * contains no data and is destined to offset 0. Receiving such a frame 30 * signals the CR50 that the host intends to transfer a new image. 31 * 32 * The connection establishment response is described by the 33 * first_response_pdu structure below. 34 */ 35 36 #define UPGRADE_PROTOCOL_VERSION 6 37 38 /* This is the format of the update frame header. */ 39 struct upgrade_command { 40 uint32_t block_digest; /* first 4 bytes of sha1 of the rest of the 41 * frame. 42 */ 43 uint32_t block_base; /* Offset of this frame into the flash SPI. */ 44 /* The actual payload goes here. */ 45 } __packed; 46 47 /* 48 * This is the frame format the host uses when sending update PDUs over USB. 49 * 50 * The PDUs are up to 1K bytes in size, they are fragmented into USB chunks of 51 * 64 bytes each and reassembled on the receive side before being passed to 52 * the flash update function. 53 * 54 * The flash update function receives the unframed PDU body (starting at the 55 * cmd field below), and puts its reply into the same buffer the PDU was in. 56 */ 57 struct update_frame_header { 58 uint32_t block_size; /* Total size of the block, including this 59 * field. 60 */ 61 struct upgrade_command cmd; 62 }; 63 64 /* 65 * A convenience structure which allows to group together various revision 66 * fields of the header created by the signer. 67 * 68 * These fields are compared when deciding if versions of two images are the 69 * same or when deciding which one of the available images to run. 70 */ 71 struct signed_header_version { 72 uint32_t minor; 73 uint32_t major; 74 uint32_t epoch; 75 }; 76 77 /* 78 * Response to the connection establishment request. 79 * 80 * When responding to the very first packet of the upgrade sequence, the 81 * original USB update implementation was responding with a four byte value, 82 * just as to any other block of the transfer sequence. 83 * 84 * It became clear that there is a need to be able to enhance the upgrade 85 * protocol, while staying backwards compatible. 86 * 87 * All newer protocol versions (starting with version 2) respond to the very 88 * first packet with an 8 byte or larger response, where the first 4 bytes are 89 * a version specific data, and the second 4 bytes - the protocol version 90 * number. 91 * 92 * This way the host receiving of a four byte value in response to the first 93 * packet is considered an indication of the target running the 'legacy' 94 * protocol, version 1. Receiving of an 8 byte or longer response would 95 * communicates the protocol version in the second 4 bytes. 96 */ 97 struct first_response_pdu { 98 uint32_t return_value; 99 100 /* The below fields are present in versions 2 and up. */ 101 uint32_t protocol_version; 102 103 /* The below fields are present in versions 3 and up. */ 104 uint32_t backup_ro_offset; 105 uint32_t backup_rw_offset; 106 107 /* The below fields are present in versions 4 and up. */ 108 /* Versions of the currently active RO and RW sections. */ 109 struct signed_header_version shv[2]; 110 111 /* The below fields are present in versions 5 and up */ 112 /* keyids of the currently active RO and RW sections. */ 113 uint32_t keyid[2]; 114 }; 115 116 #define UPGRADE_DONE 0xB007AB1E 117 118 void fw_upgrade_command_handler(void *body, size_t cmd_size, 119 size_t *response_size); 120 121 /* Used to tell fw upgrade the update ran successfully and is finished */ 122 void fw_upgrade_complete(void); 123 124 /* Verify integrity of the PDU received over USB. */ 125 int usb_pdu_valid(struct upgrade_command *cmd_body, size_t cmd_size); 126 127 /* Various upgrade command return values. */ 128 enum return_value { 129 UPGRADE_SUCCESS = 0, 130 UPGRADE_BAD_ADDR = 1, 131 UPGRADE_ERASE_FAILURE = 2, 132 UPGRADE_DATA_ERROR = 3, 133 UPGRADE_WRITE_FAILURE = 4, 134 UPGRADE_VERIFY_ERROR = 5, 135 UPGRADE_GEN_ERROR = 6, 136 UPGRADE_MALLOC_ERROR = 7, 137 UPGRADE_ROLLBACK_ERROR = 8, 138 UPGRADE_RATE_LIMIT_ERROR = 9, 139 UPGRADE_UNALIGNED_BLOCK_ERROR = 10, 140 UPGRADE_TRUNCATED_HEADER_ERROR = 11, 141 UPGRADE_BOARD_ID_ERROR = 12, 142 UPGRADE_BOARD_FLAGS_ERROR = 13, 143 UPGRADE_DEV_ID_MISMATCH_ERROR = 14, 144 }; 145 146 /* 147 * This is the size of the update frame payload, unless this is the last chunk 148 * of the image. 149 */ 150 #define SIGNED_TRANSFER_SIZE 1024 151 152 #endif /* ! __EC_CHIP_G_UPGRADE_FW_H */ 153