drivers/staging/greybus/Documentation/firmware/firmware-management

   1
   2 Firmware Management
   3 -------------------
   4  Copyright 2016 Google Inc.
   5  Copyright 2016 Linaro Ltd.
   6
   7 Interface-Manifest
   8 ------------------
   9
  10 All firmware packages on the Modules or Interfaces are managed by a special
  11 Firmware Management Protocol. To support Firmware Management by the AP, the
  12 Interface Manifest shall at least contain the Firmware Management Bundle and a
  13 Firmware Management Protocol CPort within it.
  14
  15 The bundle may contain additional CPorts based on the extra functionality
  16 required to manage firmware packages.
  17
  18 For example, this is how the Firmware Management part of the Interface Manifest
  19 may 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
  46 Sysfs Interfaces - Firmware Management
  47 --------------------------------------
  48
  49 The Firmware Management Protocol interacts with Userspace using the character
  50 device interface. The character device will be present in /dev/ directory
  51 and will be named gb-fw-mgmt-<N>. The number <N> is assigned at runtime.
  52
  53 Identifying the Character Device
  54 ================================
  55
  56 There can be multiple devices present in /dev/ directory with name gb-fw-mgmt-N
  57 and user first needs to identify the character device used for
  58 firmware-management for a particular interface.
  59
  60 The Firmware Management core creates a device of class 'gb_fw_mgmt', which shall
  61 be used by the user to identify the right character device for it. The class
  62 device is created within the Bundle directory for a particular Interface.
  63
  64 For 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
  68 The last name in this path: gb-fw-mgmt-0 is precisely the name of the char
  69 device and so the device in this case will be:
  70
  71 /dev/gb-fw-mgmt-0.
  72
  73 Operations on the Char device
  74 =============================
  75
  76 The Character device (gb-fw-mgmt-0 in example) can be opened by the userspace
  77 application and it can perform various 'ioctl' operations on the device. The
  78 device doesn't support any read/write operations.
  79
  80 Following 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
 106 struct 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
 112 struct 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
 119 struct 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
 127 struct 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
 140 1. 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
 146 2. 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
 154 3. 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
 161 4. 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
 168 5. 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
 174 6. 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
 183 Sysfs Interfaces - Authentication
 184 ---------------------------------
 185
 186 The Component Authentication Protocol interacts with Userspace using the
 187 character device interface. The character device will be present in /dev/
 188 directory and will be named gb-authenticate-<N>. The number <N> is assigned at
 189 runtime.
 190
 191 Identifying the Character Device
 192 ================================
 193
 194 There can be multiple devices present in /dev/ directory with name
 195 gb-authenticate-N and user first needs to identify the character device used for
 196 authentication a of particular interface.
 197
 198 The Authentication core creates a device of class 'gb_authenticate', which shall
 199 be used by the user to identify the right character device for it. The class
 200 device is created within the Bundle directory for a particular Interface.
 201
 202 For 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
 206 The last name in this path: gb-authenticate-0 is precisely the name of the char
 207 device and so the device in this case will be:
 208
 209 /dev/gb-authenticate-0.
 210
 211 Operations on the Char device
 212 =============================
 213
 214 The Character device (/dev/gb-authenticate-0 in above example) can be opened by
 215 the userspace application and it can perform various 'ioctl' operations on the
 216 device. The device doesn't support any read/write operations.
 217
 218 Following 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 */
 251 struct cap_ioc_get_endpoint_uid {
 252         __u8                    uid[8];
 253 } __attribute__ ((__packed__));
 254
 255 struct 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
 264 struct 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
 281 1. 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
 287 2. 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
 297 3. 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
 306 Sysfs Interfaces - Firmware Download
 307 ------------------------------------
 308
 309 The Firmware Download Protocol uses the existing Linux Kernel's Firmware class
 310 and the interface provided to userspace are described in:
 311 Documentation/firmware_class/.
 312
 313
 314 Sysfs Interfaces - SPI Flash
 315 ----------------------------
 316
 317 The SPI flash is exposed in userspace as a MTD device and is created
 318 within 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
 321 mtd0    mtd0ro
 322
 323
 324 Sample Applications
 325 -------------------
 326
 327 The current directory also provides a firmware.c test application, which can be
 328 referenced while developing userspace application to talk to firmware-management
 329 protocol.
 330
 331 The current directory also provides a authenticate.c test application, which can
 332 be referenced while developing userspace application to talk to
 333 component authentication protocol.