1 2Firmware Management 3------------------- 4 Copyright 2016 Google Inc. 5 Copyright 2016 Linaro Ltd. 6 7Interface-Manifest 8------------------ 9 10All firmware packages on the Modules or Interfaces are managed by a special 11Firmware Management Protocol. To support Firmware Management by the AP, the 12Interface Manifest shall at least contain the Firmware Management Bundle and a 13Firmware Management Protocol CPort within it. 14 15The bundle may contain additional CPorts based on the extra functionality 16required to manage firmware packages. 17 18For example, this is how the Firmware Management part of the Interface Manifest 19may look like: 20 21 ; Firmware Management Bundle (Bundle 1): 22 [bundle-descriptor 1] 23 class = 0x16 24 25 ; (Mandatory) Firmware Management Protocol on CPort 1 26 [cport-descriptor 2] 27 bundle = 1 28 protocol = 0x18 29 30 ; (Optional) Firmware Download Protocol on CPort 2 31 [cport-descriptor 1] 32 bundle = 1 33 protocol = 0x17 34 35 ; (Optional) SPI protocol on CPort 3 36 [cport-descriptor 3] 37 bundle = 1 38 protocol = 0x0b 39 40 ; (Optional) Component Authentication Protocol (CAP) on CPort 4 41 [cport-descriptor 4] 42 bundle = 1 43 protocol = 0x19 44 45 46Sysfs Interfaces - Firmware Management 47-------------------------------------- 48 49The Firmware Management Protocol interacts with Userspace using the character 50device interface. The character device will be present in /dev/ directory 51and will be named gb-fw-mgmt-<N>. The number <N> is assigned at runtime. 52 53Identifying the Character Device 54================================ 55 56There can be multiple devices present in /dev/ directory with name gb-fw-mgmt-N 57and user first needs to identify the character device used for 58firmware-management for a particular interface. 59 60The Firmware Management core creates a device of class 'gb_fw_mgmt', which shall 61be used by the user to identify the right character device for it. The class 62device is created within the Bundle directory for a particular Interface. 63 64For example this is how the class-device can be present: 65 66/sys/bus/greybus/devices/1-1/1-1.1/1-1.1.1/gb_fw_mgmt/gb-fw-mgmt-0 67 68The last name in this path: gb-fw-mgmt-0 is precisely the name of the char 69device and so the device in this case will be: 70 71/dev/gb-fw-mgmt-0. 72 73Operations on the Char device 74============================= 75 76The Character device (gb-fw-mgmt-0 in example) can be opened by the userspace 77application and it can perform various 'ioctl' operations on the device. The 78device doesn't support any read/write operations. 79 80Following are the IOCTLs and their data structures available to the user: 81 82/* IOCTL support */ 83#define GB_FW_LOAD_METHOD_UNIPRO 0x01 84#define GB_FW_LOAD_METHOD_INTERNAL 0x02 85 86#define GB_FW_LOAD_STATUS_FAILED 0x00 87#define GB_FW_LOAD_STATUS_UNVALIDATED 0x01 88#define GB_FW_LOAD_STATUS_VALIDATED 0x02 89#define GB_FW_LOAD_STATUS_VALIDATION_FAILED 0x03 90 91#define GB_FW_BACKEND_FW_STATUS_SUCCESS 0x01 92#define GB_FW_BACKEND_FW_STATUS_FAIL_FIND 0x02 93#define GB_FW_BACKEND_FW_STATUS_FAIL_FETCH 0x03 94#define GB_FW_BACKEND_FW_STATUS_FAIL_WRITE 0x04 95#define GB_FW_BACKEND_FW_STATUS_INT 0x05 96#define GB_FW_BACKEND_FW_STATUS_RETRY 0x06 97#define GB_FW_BACKEND_FW_STATUS_NOT_SUPPORTED 0x07 98 99#define GB_FW_BACKEND_VERSION_STATUS_SUCCESS 0x01 100#define GB_FW_BACKEND_VERSION_STATUS_NOT_AVAILABLE 0x02 101#define GB_FW_BACKEND_VERSION_STATUS_NOT_SUPPORTED 0x03 102#define GB_FW_BACKEND_VERSION_STATUS_RETRY 0x04 103#define GB_FW_BACKEND_VERSION_STATUS_FAIL_INT 0x05 104 105 106struct fw_mgmt_ioc_get_intf_version { 107 __u8 firmware_tag[GB_FIRMWARE_U_TAG_MAX_SIZE]; 108 __u16 major; 109 __u16 minor; 110} __attribute__ ((__packed__)); 111 112struct fw_mgmt_ioc_get_backend_version { 113 __u8 firmware_tag[GB_FIRMWARE_U_TAG_MAX_SIZE]; 114 __u16 major; 115 __u16 minor; 116 __u8 status; 117} __attribute__ ((__packed__)); 118 119struct fw_mgmt_ioc_intf_load_and_validate { 120 __u8 firmware_tag[GB_FIRMWARE_TAG_MAX_SIZE]; 121 __u8 load_method; 122 __u8 status; 123 __u16 major; 124 __u16 minor; 125} __packed; 126 127struct fw_mgmt_ioc_backend_fw_update { 128 __u8 firmware_tag[GB_FIRMWARE_TAG_MAX_SIZE]; 129 __u8 status; 130} __packed; 131 132#define FW_MGMT_IOCTL_BASE 'S' 133#define FW_MGMT_IOC_GET_INTF_FW _IOR(FW_MGMT_IOCTL_BASE, 0, struct fw_mgmt_ioc_get_intf_version) 134#define FW_MGMT_IOC_GET_BACKEND_FW _IOWR(FW_MGMT_IOCTL_BASE, 1, struct fw_mgmt_ioc_get_backend_version) 135#define FW_MGMT_IOC_INTF_LOAD_AND_VALIDATE _IOWR(FW_MGMT_IOCTL_BASE, 2, struct fw_mgmt_ioc_intf_load_and_validate) 136#define FW_MGMT_IOC_INTF_BACKEND_FW_UPDATE _IOWR(FW_MGMT_IOCTL_BASE, 3, struct fw_mgmt_ioc_backend_fw_update) 137#define FW_MGMT_IOC_SET_TIMEOUT_MS _IOW(FW_MGMT_IOCTL_BASE, 4, unsigned int) 138#define FW_MGMT_IOC_MODE_SWITCH _IO(FW_MGMT_IOCTL_BASE, 5) 139 1401. FW_MGMT_IOC_GET_INTF_FW: 141 142 This ioctl shall be used by the user to get the version and firmware-tag of 143 the currently running Interface Firmware. All the fields of the 'struct 144 fw_mgmt_ioc_get_fw' are filled by the kernel. 145 1462. FW_MGMT_IOC_GET_BACKEND_FW: 147 148 This ioctl shall be used by the user to get the version of a currently 149 running Backend Interface Firmware identified by a firmware-tag. The user is 150 required to fill the 'firmware_tag' field of the 'struct fw_mgmt_ioc_get_fw' 151 in this case. The 'major' and 'minor' fields are set by the kernel in 152 response. 153 1543. FW_MGMT_IOC_INTF_LOAD_AND_VALIDATE: 155 156 This ioctl shall be used by the user to load an Interface Firmware package on 157 an Interface. The user needs to fill the 'firmware_tag' and 'load_method' 158 fields of the 'struct fw_mgmt_ioc_intf_load_and_validate'. The 'status', 159 'major' and 'minor' fields are set by the kernel in response. 160 1614. FW_MGMT_IOC_INTF_BACKEND_FW_UPDATE: 162 163 This ioctl shall be used by the user to request an Interface to update a 164 Backend Interface Firmware. The user is required to fill the 'firmware_tag' 165 field of the 'struct fw_mgmt_ioc_get_fw' in this case. The 'status' field is 166 set by the kernel in response. 167 1685. FW_MGMT_IOC_SET_TIMEOUT_MS: 169 170 This ioctl shall be used by the user to increase the timeout interval within 171 which the firmware must get loaded by the Module. The default timeout is 1 172 second. The user needs to pass the timeout in milliseconds. 173 1746. FW_MGMT_IOC_MODE_SWITCH: 175 176 This ioctl shall be used by the user to mode-switch the module to the 177 previously loaded interface firmware. If the interface firmware isn't loaded 178 previously, or if another unsuccessful FW_MGMT_IOC_INTF_LOAD_AND_VALIDATE 179 operation is started after loading interface firmware, then the firmware core 180 wouldn't allow mode-switch. 181 182 183Sysfs Interfaces - Authentication 184--------------------------------- 185 186The Component Authentication Protocol interacts with Userspace using the 187character device interface. The character device will be present in /dev/ 188directory and will be named gb-authenticate-<N>. The number <N> is assigned at 189runtime. 190 191Identifying the Character Device 192================================ 193 194There can be multiple devices present in /dev/ directory with name 195gb-authenticate-N and user first needs to identify the character device used for 196authentication a of particular interface. 197 198The Authentication core creates a device of class 'gb_authenticate', which shall 199be used by the user to identify the right character device for it. The class 200device is created within the Bundle directory for a particular Interface. 201 202For example this is how the class-device can be present: 203 204/sys/bus/greybus/devices/1-1/1-1.1/1-1.1.1/gb_authenticate/gb-authenticate-0 205 206The last name in this path: gb-authenticate-0 is precisely the name of the char 207device and so the device in this case will be: 208 209/dev/gb-authenticate-0. 210 211Operations on the Char device 212============================= 213 214The Character device (/dev/gb-authenticate-0 in above example) can be opened by 215the userspace application and it can perform various 'ioctl' operations on the 216device. The device doesn't support any read/write operations. 217 218Following are the IOCTLs and their data structures available to the user: 219 220#define CAP_CERTIFICATE_MAX_SIZE 1600 221#define CAP_SIGNATURE_MAX_SIZE 320 222 223/* Certificate class types */ 224#define CAP_CERT_IMS_EAPC 0x00000001 225#define CAP_CERT_IMS_EASC 0x00000002 226#define CAP_CERT_IMS_EARC 0x00000003 227#define CAP_CERT_IMS_IAPC 0x00000004 228#define CAP_CERT_IMS_IASC 0x00000005 229#define CAP_CERT_IMS_IARC 0x00000006 230 231/* IMS Certificate response result codes */ 232#define CAP_IMS_RESULT_CERT_FOUND 0x00 233#define CAP_IMS_RESULT_CERT_CLASS_INVAL 0x01 234#define CAP_IMS_RESULT_CERT_CORRUPT 0x02 235#define CAP_IMS_RESULT_CERT_NOT_FOUND 0x03 236 237/* Authentication types */ 238#define CAP_AUTH_IMS_PRI 0x00000001 239#define CAP_AUTH_IMS_SEC 0x00000002 240#define CAP_AUTH_IMS_RSA 0x00000003 241 242/* Authenticate response result codes */ 243#define CAP_AUTH_RESULT_CR_SUCCESS 0x00 244#define CAP_AUTH_RESULT_CR_BAD_TYPE 0x01 245#define CAP_AUTH_RESULT_CR_WRONG_EP 0x02 246#define CAP_AUTH_RESULT_CR_NO_KEY 0x03 247#define CAP_AUTH_RESULT_CR_SIG_FAIL 0x04 248 249 250/* IOCTL support */ 251struct cap_ioc_get_endpoint_uid { 252 __u8 uid[8]; 253} __attribute__ ((__packed__)); 254 255struct cap_ioc_get_ims_certificate { 256 __u32 certificate_class; 257 __u32 certificate_id; 258 259 __u8 result_code; 260 __u32 cert_size; 261 __u8 certificate[CAP_CERTIFICATE_MAX_SIZE]; 262} __attribute__ ((__packed__)); 263 264struct cap_ioc_authenticate { 265 __u32 auth_type; 266 __u8 uid[8]; 267 __u8 challenge[32]; 268 269 __u8 result_code; 270 __u8 response[64]; 271 __u32 signature_size; 272 __u8 signature[CAP_SIGNATURE_MAX_SIZE]; 273} __attribute__ ((__packed__)); 274 275#define CAP_IOCTL_BASE 'C' 276#define CAP_IOC_GET_ENDPOINT_UID _IOR(CAP_IOCTL_BASE, 0, struct cap_ioc_get_endpoint_uid) 277#define CAP_IOC_GET_IMS_CERTIFICATE _IOWR(CAP_IOCTL_BASE, 1, struct cap_ioc_get_ims_certificate) 278#define CAP_IOC_AUTHENTICATE _IOWR(CAP_IOCTL_BASE, 2, struct cap_ioc_authenticate) 279 280 2811. CAP_IOC_GET_ENDPOINT_UID: 282 283 This ioctl shall be used by the user to get the endpoint UID associated with 284 the Interface. All the fields of the 'struct cap_ioc_get_endpoint_uid' are 285 filled by the kernel. 286 2872. CAP_IOC_GET_IMS_CERTIFICATE: 288 289 This ioctl shall be used by the user to retrieve one of the available 290 cryptographic certificates held by the Interface for use in Component 291 Authentication. The user is required to fill the 'certificate_class' and 292 'certificate_id' field of the 'struct cap_ioc_get_ims_certificate' in this 293 case. The other fields will be set by the kernel in response. The first 294 'cert_size' bytes of the 'certificate' shall be read by the user and others 295 must be discarded. 296 2973. CAP_IOC_AUTHENTICATE: 298 299 This ioctl shall be used by the user to authenticate the Module attached to 300 an Interface. The user needs to fill the 'auth_type', 'uid', and 'challenge' 301 fields of the 'struct cap_ioc_authenticate'. The other fields will be set by 302 the kernel in response. The first 'signature_size' bytes of the 'signature' 303 shall be read by the user and others must be discarded. 304 305 306Sysfs Interfaces - Firmware Download 307------------------------------------ 308 309The Firmware Download Protocol uses the existing Linux Kernel's Firmware class 310and the interface provided to userspace are described in: 311Documentation/firmware_class/. 312 313 314Sysfs Interfaces - SPI Flash 315---------------------------- 316 317The SPI flash is exposed in userspace as a MTD device and is created 318within the Bundle directory. For example, this is how the path may look like: 319 320$ ls /sys/bus/greybus/devices/1-1/1-1.1/1-1.1.1/spi_master/spi32766/spi32766.0/mtd 321mtd0 mtd0ro 322 323 324Sample Applications 325------------------- 326 327The current directory also provides a firmware.c test application, which can be 328referenced while developing userspace application to talk to firmware-management 329protocol. 330 331The current directory also provides a authenticate.c test application, which can 332be referenced while developing userspace application to talk to 333component authentication protocol. 334