1.. SPDX-License-Identifier: GPL-2.0
2
3====================
4iosm devlink support
5====================
6
7This document describes the devlink features implemented by the ``iosm``
8device driver.
9
10Parameters
11==========
12
13The ``iosm`` driver implements the following driver-specific parameters.
14
15.. list-table:: Driver-specific parameters implemented
16   :widths: 5 5 5 85
17
18   * - Name
19     - Type
20     - Mode
21     - Description
22   * - ``erase_full_flash``
23     - u8
24     - runtime
25     - erase_full_flash parameter is used to check if full erase is required for
26       the device during firmware flashing.
27       If set, Full nand erase command will be sent to the device. By default,
28       only conditional erase support is enabled.
29   * - ``download_region``
30     - u8
31     - runtime
32     - download_region parameter is used to identify if we are flashing the
33       loadmap/region file during the firmware flashing.
34   * - ``address``
35     - u32
36     - runtime
37     - address parameter is used to send the address information of the
38       loadmap/region file which is required during the firmware flashing
39       process. Each region file has be flashed to its respective flash address.
40   * - ``region_count``
41     - u8
42     - runtime
43     - region_count parameter is used to inform the driver on how many total
44       loadmap/region files are present in modem firmware image that has to be
45       flashed.
46
47
48Flash Update
49============
50
51The ``iosm`` driver implements support for flash update using the
52``devlink-flash`` interface.
53
54It supports updating the device flash using a combined flash image which contains
55the Bootloader images and other modem software images.
56
57The driver uses DEVLINK_SUPPORT_FLASH_UPDATE_COMPONENT to identify type of
58firmware image that need to be flashed as requested by user space application.
59Supported firmware image types.
60
61.. list-table:: Firmware Image types
62    :widths: 15 85
63
64    * - Name
65      - Description
66    * - ``PSI RAM``
67      - Primary Signed Image
68    * - ``EBL``
69      - External Bootloader
70    * - ``FLS``
71      - Modem Software Image
72
73PSI RAM and EBL are the RAM images which are injected to the device when the
74device is in BOOT ROM stage. Once this is successful, the actual modem firmware
75image is flashed to the device. The modem software image contains multiple files
76each having one secure bin file and at least one Loadmap/Region file. For flashing
77these files, appropriate commands are sent to the modem device along with the
78data required for flashing. The data like region count and address of each region
79has to be passed to the driver using the devlink param command.
80
81If the device has to be fully erased before firmware flashing, user application
82need to set the erase_full_flash parameter using devlink param command.
83By default, conditional erase feature is supported.
84
85Flash Commands:
86===============
871) When modem is in Boot ROM stage, user can use below command to inject PSI RAM
88image using devlink flash command.
89
90$ devlink dev flash pci/0000:02:00.0 file <PSI_RAM_File_name> component PSI
91
922) If user want to do a full erase, below command need to be issued to set the
93erase full flash param (To be set only if full erase required).
94
95$ devlink dev param set pci/0000:02:00.0 name erase_full_flash value true cmode runtime
96
973) Inject EBL after the modem is in PSI stage.
98$ devlink dev flash pci/0000:02:00.0 file <EBL_File_name> component EBL
99
1004) Once EBL is injected successfully, then the actual firmware flashing takes
101place. Below is the sequence of commands used for each of the firmware images.
102
103a) Flash secure bin file.
104$ devlink dev flash pci/0000:02:00.0 file <Secure_bin_file_name> component FLS
105
106b) Flashing the Loadmap/Region file
107$ devlink dev param set pci/0000:02:00.0 name region_count value 1 cmode runtime
108
109$ devlink dev param set pci/0000:02:00.0 name download_region value true cmode runtime
110
111$ devlink dev param set pci/0000:02:00.0 name address value <Nand_address> cmode runtime
112
113$ devlink dev flash pci/0000:02:00.0 file <Load_map_file_name> component FLS
114
115Regions
116=======
117
118The ``iosm`` driver supports dumping the coredump logs.
119
120In case a firmware encounters an exception, a snapshot will be taken by the
121driver. Following regions are accessed for device internal data.
122
123.. list-table:: Regions implemented
124    :widths: 15 85
125
126    * - Name
127      - Description
128    * - ``report.json``
129      - The summary of exception details logged as part of this region.
130    * - ``coredump.fcd``
131      - This region contains the details related to the exception occurred in the
132        device (RAM dump).
133    * - ``cdd.log``
134      - This region contains the logs related to the modem CDD driver.
135    * - ``eeprom.bin``
136      - This region contains the eeprom logs.
137    * - ``bootcore_trace.bin``
138      -  This region contains the current instance of bootloader logs.
139    * - ``bootcore_prev_trace.bin``
140      - This region contains the previous instance of bootloader logs.
141
142
143Region commands
144===============
145
146$ devlink region show
147
148$ devlink region new pci/0000:02:00.0/report.json
149
150$ devlink region dump pci/0000:02:00.0/report.json snapshot 0
151
152$ devlink region del pci/0000:02:00.0/report.json snapshot 0
153
154$ devlink region new pci/0000:02:00.0/coredump.fcd
155
156$ devlink region dump pci/0000:02:00.0/coredump.fcd snapshot 1
157
158$ devlink region del pci/0000:02:00.0/coredump.fcd snapshot 1
159
160$ devlink region new pci/0000:02:00.0/cdd.log
161
162$ devlink region dump pci/0000:02:00.0/cdd.log snapshot 2
163
164$ devlink region del pci/0000:02:00.0/cdd.log snapshot 2
165
166$ devlink region new pci/0000:02:00.0/eeprom.bin
167
168$ devlink region dump pci/0000:02:00.0/eeprom.bin snapshot 3
169
170$ devlink region del pci/0000:02:00.0/eeprom.bin snapshot 3
171
172$ devlink region new pci/0000:02:00.0/bootcore_trace.bin
173
174$ devlink region dump pci/0000:02:00.0/bootcore_trace.bin snapshot 4
175
176$ devlink region del pci/0000:02:00.0/bootcore_trace.bin snapshot 4
177
178$ devlink region new pci/0000:02:00.0/bootcore_prev_trace.bin
179
180$ devlink region dump pci/0000:02:00.0/bootcore_prev_trace.bin snapshot 5
181
182$ devlink region del pci/0000:02:00.0/bootcore_prev_trace.bin snapshot 5
183