share/man/man4/mlx5io.4

   1 .\"
   2 .\" Copyright (c) 2018, 2019 Mellanox Technologies
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .Dd October 2, 2019
  27 .Dt mlx5io 4
  28 .Os
  29 .Sh NAME
  30 .Nm mlx5io
  31 .Nd IOCTL interface to manage Connect-X 4/5/6 Mellanox network adapters
  32 .Sh SYNOPSIS
  33 .In dev/mlx5/mlx5io.h
  34 .Sh DESCRIPTION
  35 The
  36 .Nm
  37 interface is provided for management of the Connect-X4, 5 and 6 network adapters
  38 in the aspects not covered by the generic network configuration,
  39 mostly related to the PCIe attachment and internal card working.
  40 Interface consists of the commands, which are passed by means of
  41 .Xr ioctl 2
  42 on the file descriptor, opened from the
  43 .Pa /dev/mlx5ctl
  44 device node.
  45 .Pp
  46 The following commands are implemented:
  47 .Bl -tag -width indent
  48 .It Dv MLX5_FWDUMP_FORCE
  49 Take the snapshot of the firmware registers state and store it in the
  50 kernel buffer.
  51 The buffer must be empty, in other words, no dumps should be written so
  52 far, or existing dump cleared with the
  53 .Dv MLX5_FWDUMP_RESET
  54 command for the specified device.
  55 The argument for the command should point to the
  56 .Vt struct mlx5_tool_addr
  57 structure, containing the PCIe bus address of the device.
  58 .Bd -literal
  59 struct mlx5_tool_addr {
  60         uint32_t domain;
  61         uint8_t bus;
  62         uint8_t slot;
  63         uint8_t func;
  64 };
  65 .Ed
  66 .It Dv MLX5_FWDUMP_RESET
  67 Clear the stored firmware dump, preparing the kernel buffer for
  68 the next dump.
  69 The argument for the command should point to the
  70 .Vt struct mlx5_tool_addr
  71 structure, containing the PCIe bus address of the device.
  72 .It Dv MLX5_FWDUMP_GET
  73 Fetch the stored firmware dump into the user memory.
  74 The argument to the command should point to the input/output
  75 .Vt struct mlx5_fwdump_get
  76 structure.
  77 Its
  78 .Dv devaddr
  79 field specifies the address of the device, the
  80 .Dv buf
  81 fields points to the array of
  82 .Vt struct mlx5_fwdump_reg
  83 of records of the registers values, the size of the array is specified
  84 in the
  85 .Dv reg_cnt
  86 field.
  87 .Bd -literal
  88 struct mlx5_fwdump_get {
  89         struct mlx5_tool_addr devaddr;
  90         struct mlx5_fwdump_reg *buf;
  91         size_t reg_cnt;
  92         size_t reg_filled; /* out */
  93 };
  94 .Ed
  95 .Pp
  96 On successfull return, the
  97 .Dv reg_filled
  98 field reports the number of the
  99 .Dv buf
 100 array elements actually filled with the registers values.
 101 If
 102 .Dv buf
 103 contains the
 104 .Dv NULL
 105 pointer, no registers are filled, but
 106 .Dv reg_filled
 107 still contains the number of registers that should be passed for
 108 the complete dump.
 109 .Pp
 110 The
 111 .Vt struct mlx5_fwdump_reg
 112 element contains the address of the register in the field
 113 .Dv addr ,
 114 and its value in the field
 115 .Dv val .
 116 .Bd -literal
 117 struct mlx5_fwdump_reg {
 118         uint32_t addr;
 119         uint32_t val;
 120 };
 121 .Ed
 122 .It Dv MLX5_FW_UPDATE
 123 Requests firmware update (flash) on the adapter specified by the
 124 .Dv devaddr
 125 using the firmware image in
 126 .Dv MFA2
 127 format.
 128 The argument for the ioctl command is the
 129 .Vt struct mlx5_fw_update
 130 with the following definition.
 131 .Bd -literal
 132 struct mlx5_fw_update {
 133         struct mlx5_tool_addr devaddr;
 134         void *img_fw_data;
 135         size_t img_fw_data_len;
 136 };
 137 .Ed
 138 Image address in memory is passed in
 139 .Dv img_fw_data ,
 140 the length of the image is specified in
 141 .Dv img_fw_data_len
 142 field.
 143 .It Dv MLX5_FW_RESET
 144 Requests PCIe link-level reset on the device.
 145 The address of the device is specified by the
 146 .Vt struct mlx5_tool_addr
 147 structure, which should be passed as an argument.
 148 .It Dv MLX5_EEPROM_GET
 149 Fetch EEPROM information.
 150 The argument to the command should point to the input/output
 151 .Vt struct mlx5_eeprom_get
 152 structure where, the
 153 .Dv devaddr
 154 field specifies the address of the device.
 155 .Bd -literal
 156 struct mlx5_eeprom_get {
 157         struct mlx5_tool_addr devaddr;
 158         size_t eeprom_info_page_valid;
 159         uint32_t *eeprom_info_buf;
 160         size_t eeprom_info_out_len;
 161 };
 162 .Ed
 163 .Pp
 164 On successfull return, the
 165 .Dv eeprom_info_out_len
 166 field reports the length of the EEPROM information.
 167 .Dv eeprom_info_buf
 168 field contains the actual EEPROM information.
 169 .Dv eeprom_info_page_valid
 170 field reports the third page validity.
 171 .El
 172 .Sh FILES
 173 The
 174 .Pa /dev/mlx5ctl
 175 .Xr devfs 5
 176 node is used to pass commands to the driver.
 177 .Sh RETURN VALUES
 178 If successful, the IOCTL returns zero.
 179 Otherwise, -1 is returned and the global variable
 180 .Va errno
 181 is set to indicate the error.
 182 .Sh SEE ALSO
 183 .Xr errno 2 ,
 184 .Xr ioctl 2 ,
 185 .Xr mlx5en 4 ,
 186 .Xr mlx5ib 4 ,
 187 .Xr mlx5tool 8
 188 and
 189 .Xr pci 9 .