4 Copyright 2016 Google Inc.
5 Copyright 2016 Linaro Ltd.
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.
15 The bundle may contain additional CPorts based on the extra functionality
16 required to manage firmware packages.
18 For example, this is how the Firmware Management part of the Interface Manifest
21 ; Firmware Management Bundle (Bundle 1):
25 ; (Mandatory) Firmware Management Protocol on CPort 1
30 ; (Optional) Firmware Download Protocol on CPort 2
35 ; (Optional) SPI protocol on CPort 3
40 ; (Optional) Component Authentication Protocol (CAP) on CPort 4
46 Sysfs Interfaces - Firmware Management
47 --------------------------------------
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.
53 Identifying the Character Device
54 ================================
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.
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.
64 For example this is how the class-device can be present:
66 /sys/bus/greybus/devices/1-1/1-1.1/1-1.1.1/gb_fw_mgmt/gb-fw-mgmt-0
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:
73 Operations on the Char device
74 =============================
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.
80 Following are the IOCTLs and their data structures available to the user:
83 #define GB_FW_LOAD_METHOD_UNIPRO 0x01
84 #define GB_FW_LOAD_METHOD_INTERNAL 0x02
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
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
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
106 struct fw_mgmt_ioc_get_intf_version {
107 __u8 firmware_tag[GB_FIRMWARE_U_TAG_MAX_SIZE];
110 } __attribute__ ((__packed__));
112 struct fw_mgmt_ioc_get_backend_version {
113 __u8 firmware_tag[GB_FIRMWARE_U_TAG_MAX_SIZE];
117 } __attribute__ ((__packed__));
119 struct fw_mgmt_ioc_intf_load_and_validate {
120 __u8 firmware_tag[GB_FIRMWARE_TAG_MAX_SIZE];
127 struct fw_mgmt_ioc_backend_fw_update {
128 __u8 firmware_tag[GB_FIRMWARE_TAG_MAX_SIZE];
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)
140 1. FW_MGMT_IOC_GET_INTF_FW:
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.
146 2. FW_MGMT_IOC_GET_BACKEND_FW:
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
154 3. FW_MGMT_IOC_INTF_LOAD_AND_VALIDATE:
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.
161 4. FW_MGMT_IOC_INTF_BACKEND_FW_UPDATE:
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.
168 5. FW_MGMT_IOC_SET_TIMEOUT_MS:
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.
174 6. FW_MGMT_IOC_MODE_SWITCH:
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.
183 Sysfs Interfaces - Authentication
184 ---------------------------------
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
191 Identifying the Character Device
192 ================================
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.
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.
202 For example this is how the class-device can be present:
204 /sys/bus/greybus/devices/1-1/1-1.1/1-1.1.1/gb_authenticate/gb-authenticate-0
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:
209 /dev/gb-authenticate-0.
211 Operations on the Char device
212 =============================
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.
218 Following are the IOCTLs and their data structures available to the user:
220 #define CAP_CERTIFICATE_MAX_SIZE 1600
221 #define CAP_SIGNATURE_MAX_SIZE 320
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
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
237 /* Authentication types */
238 #define CAP_AUTH_IMS_PRI 0x00000001
239 #define CAP_AUTH_IMS_SEC 0x00000002
240 #define CAP_AUTH_IMS_RSA 0x00000003
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
251 struct cap_ioc_get_endpoint_uid {
253 } __attribute__ ((__packed__));
255 struct cap_ioc_get_ims_certificate {
256 __u32 certificate_class;
257 __u32 certificate_id;
261 __u8 certificate[CAP_CERTIFICATE_MAX_SIZE];
262 } __attribute__ ((__packed__));
264 struct cap_ioc_authenticate {
271 __u32 signature_size;
272 __u8 signature[CAP_SIGNATURE_MAX_SIZE];
273 } __attribute__ ((__packed__));
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)
281 1. CAP_IOC_GET_ENDPOINT_UID:
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.
287 2. CAP_IOC_GET_IMS_CERTIFICATE:
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
297 3. CAP_IOC_AUTHENTICATE:
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.
306 Sysfs Interfaces - Firmware Download
307 ------------------------------------
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/.
314 Sysfs Interfaces - SPI Flash
315 ----------------------------
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:
320 $ ls /sys/bus/greybus/devices/1-1/1-1.1/1-1.1.1/spi_master/spi32766/spi32766.0/mtd
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
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.