0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ====================
0004 iosm devlink support
0005 ====================
0006
0007 This document describes the devlink features implemented by the ``iosm``
0008 device driver.
0009
0010 Parameters
0011 ==========
0012
0013 The ``iosm`` driver implements the following driver-specific parameters.
0014
0015 .. list-table:: Driver-specific parameters implemented
0016 :widths: 5 5 5 85
0017
0018 * - Name
0019 - Type
0020 - Mode
0021 - Description
0022 * - ``erase_full_flash``
0023 - u8
0024 - runtime
0025 - erase_full_flash parameter is used to check if full erase is required for
0026 the device during firmware flashing.
0027 If set, Full nand erase command will be sent to the device. By default,
0028 only conditional erase support is enabled.
0029
0030
0031 Flash Update
0032 ============
0033
0034 The ``iosm`` driver implements support for flash update using the
0035 ``devlink-flash`` interface.
0036
0037 It supports updating the device flash using a combined flash image which contains
0038 the Bootloader images and other modem software images.
0039
0040 The driver uses DEVLINK_SUPPORT_FLASH_UPDATE_COMPONENT to identify type of
0041 firmware image that need to be flashed as requested by user space application.
0042 Supported firmware image types.
0043
0044 .. list-table:: Firmware Image types
0045 :widths: 15 85
0046
0047 * - Name
0048 - Description
0049 * - ``PSI RAM``
0050 - Primary Signed Image
0051 * - ``EBL``
0052 - External Bootloader
0053 * - ``FLS``
0054 - Modem Software Image
0055
0056 PSI RAM and EBL are the RAM images which are injected to the device when the
0057 device is in BOOT ROM stage. Once this is successful, the actual modem firmware
0058 image is flashed to the device. The modem software image contains multiple files
0059 each having one secure bin file and at least one Loadmap/Region file. For flashing
0060 these files, appropriate commands are sent to the modem device along with the
0061 data required for flashing. The data like region count and address of each region
0062 has to be passed to the driver using the devlink param command.
0063
0064 If the device has to be fully erased before firmware flashing, user application
0065 need to set the erase_full_flash parameter using devlink param command.
0066 By default, conditional erase feature is supported.
0067
0068 Flash Commands:
0069 ===============
0070 1) When modem is in Boot ROM stage, user can use below command to inject PSI RAM
0071 image using devlink flash command.
0072
0073 $ devlink dev flash pci/0000:02:00.0 file <PSI_RAM_File_name>
0074
0075 2) If user want to do a full erase, below command need to be issued to set the
0076 erase full flash param (To be set only if full erase required).
0077
0078 $ devlink dev param set pci/0000:02:00.0 name erase_full_flash value true cmode runtime
0079
0080 3) Inject EBL after the modem is in PSI stage.
0081
0082 $ devlink dev flash pci/0000:02:00.0 file <EBL_File_name>
0083
0084 4) Once EBL is injected successfully, then the actual firmware flashing takes
0085 place. Below is the sequence of commands used for each of the firmware images.
0086
0087 a) Flash secure bin file.
0088
0089 $ devlink dev flash pci/0000:02:00.0 file <Secure_bin_file_name>
0090
0091 b) Flashing the Loadmap/Region file
0092
0093 $ devlink dev flash pci/0000:02:00.0 file <Load_map_file_name>
0094
0095 Regions
0096 =======
0097
0098 The ``iosm`` driver supports dumping the coredump logs.
0099
0100 In case a firmware encounters an exception, a snapshot will be taken by the
0101 driver. Following regions are accessed for device internal data.
0102
0103 .. list-table:: Regions implemented
0104 :widths: 15 85
0105
0106 * - Name
0107 - Description
0108 * - ``report.json``
0109 - The summary of exception details logged as part of this region.
0110 * - ``coredump.fcd``
0111 - This region contains the details related to the exception occurred in the
0112 device (RAM dump).
0113 * - ``cdd.log``
0114 - This region contains the logs related to the modem CDD driver.
0115 * - ``eeprom.bin``
0116 - This region contains the eeprom logs.
0117 * - ``bootcore_trace.bin``
0118 - This region contains the current instance of bootloader logs.
0119 * - ``bootcore_prev_trace.bin``
0120 - This region contains the previous instance of bootloader logs.
0121
0122
0123 Region commands
0124 ===============
0125
0126 $ devlink region show
0127
0128 $ devlink region new pci/0000:02:00.0/report.json
0129
0130 $ devlink region dump pci/0000:02:00.0/report.json snapshot 0
0131
0132 $ devlink region del pci/0000:02:00.0/report.json snapshot 0
0133
0134 $ devlink region new pci/0000:02:00.0/coredump.fcd
0135
0136 $ devlink region dump pci/0000:02:00.0/coredump.fcd snapshot 1
0137
0138 $ devlink region del pci/0000:02:00.0/coredump.fcd snapshot 1
0139
0140 $ devlink region new pci/0000:02:00.0/cdd.log
0141
0142 $ devlink region dump pci/0000:02:00.0/cdd.log snapshot 2
0143
0144 $ devlink region del pci/0000:02:00.0/cdd.log snapshot 2
0145
0146 $ devlink region new pci/0000:02:00.0/eeprom.bin
0147
0148 $ devlink region dump pci/0000:02:00.0/eeprom.bin snapshot 3
0149
0150 $ devlink region del pci/0000:02:00.0/eeprom.bin snapshot 3
0151
0152 $ devlink region new pci/0000:02:00.0/bootcore_trace.bin
0153
0154 $ devlink region dump pci/0000:02:00.0/bootcore_trace.bin snapshot 4
0155
0156 $ devlink region del pci/0000:02:00.0/bootcore_trace.bin snapshot 4
0157
0158 $ devlink region new pci/0000:02:00.0/bootcore_prev_trace.bin
0159
0160 $ devlink region dump pci/0000:02:00.0/bootcore_prev_trace.bin snapshot 5
0161
0162 $ devlink region del pci/0000:02:00.0/bootcore_prev_trace.bin snapshot 5
