diff options
Diffstat (limited to 'Documentation/ABI/testing')
| -rw-r--r-- | Documentation/ABI/testing/sysfs-block-rnbd | 46 | ||||
| -rw-r--r-- | Documentation/ABI/testing/sysfs-class-rnbd-client | 111 | ||||
| -rw-r--r-- | Documentation/ABI/testing/sysfs-class-rnbd-server | 50 | ||||
| -rw-r--r-- | Documentation/ABI/testing/sysfs-class-rtrs-client | 131 | ||||
| -rw-r--r-- | Documentation/ABI/testing/sysfs-class-rtrs-server | 53 |
5 files changed, 391 insertions, 0 deletions
diff --git a/Documentation/ABI/testing/sysfs-block-rnbd b/Documentation/ABI/testing/sysfs-block-rnbd new file mode 100644 index 000000000000..8f070b47f361 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-block-rnbd @@ -0,0 +1,46 @@ +What: /sys/block/rnbd<N>/rnbd/unmap_device +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: To unmap a volume, "normal" or "force" has to be written to: + /sys/block/rnbd<N>/rnbd/unmap_device + + When "normal" is used, the operation will fail with EBUSY if any process + is using the device. When "force" is used, the device is also unmapped + when device is in use. All I/Os that are in progress will fail. + + Example: + + # echo "normal" > /sys/block/rnbd0/rnbd/unmap_device + +What: /sys/block/rnbd<N>/rnbd/state +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: The file contains the current state of the block device. The state file + returns "open" when the device is successfully mapped from the server + and accepting I/O requests. When the connection to the server gets + disconnected in case of an error (e.g. link failure), the state file + returns "closed" and all I/O requests submitted to it will fail with -EIO. + +What: /sys/block/rnbd<N>/rnbd/session +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: RNBD uses RTRS session to transport the data between client and + server. The entry "session" contains the name of the session, that + was used to establish the RTRS session. It's the same name that + was passed as server parameter to the map_device entry. + +What: /sys/block/rnbd<N>/rnbd/mapping_path +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Contains the path that was passed as "device_path" to the map_device + operation. + +What: /sys/block/rnbd<N>/rnbd/access_mode +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Contains the device access mode: ro, rw or migration. diff --git a/Documentation/ABI/testing/sysfs-class-rnbd-client b/Documentation/ABI/testing/sysfs-class-rnbd-client new file mode 100644 index 000000000000..c084f203b41e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-rnbd-client @@ -0,0 +1,111 @@ +What: /sys/class/rnbd-client +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Provide information about RNBD-client. + All sysfs files that are not read-only provide the usage information on read: + + Example: + # cat /sys/class/rnbd-client/ctl/map_device + + > Usage: echo "sessname=<name of the rtrs session> path=<[srcaddr,]dstaddr> + > [path=<[srcaddr,]dstaddr>] device_path=<full path on remote side> + > [access_mode=<ro|rw|migration>] > map_device + > + > addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ] + +What: /sys/class/rnbd-client/ctl/map_device +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Expected format is the following: + + sessname=<name of the rtrs session> + path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr> ...] + device_path=<full path on remote side> + [access_mode=<ro|rw|migration>] + + Where: + + sessname: accepts a string not bigger than 256 chars, which identifies + a given session on the client and on the server. + I.e. "clt_hostname-srv_hostname" could be a natural choice. + + path: describes a connection between the client and the server by + specifying destination and, when required, the source address. + The addresses are to be provided in the following format: + + ip:<IPv6> + ip:<IPv4> + gid:<GID> + + for example: + + path=ip:10.0.0.66 + The single addr is treated as the destination. + The connection will be established to this server from any client IP address. + + path=ip:10.0.0.66,ip:10.0.1.66 + First addr is the source address and the second is the destination. + + If multiple "path=" options are specified multiple connection + will be established and data will be sent according to + the selected multipath policy (see RTRS mp_policy sysfs entry description). + + device_path: Path to the block device on the server side. Path is specified + relative to the directory on server side configured in the + 'dev_search_path' module parameter of the rnbd_server. + The rnbd_server prepends the <device_path> received from client + with <dev_search_path> and tries to open the + <dev_search_path>/<device_path> block device. On success, + a /dev/rnbd<N> device file, a /sys/block/rnbd_client/rnbd<N>/ + directory and an entry in /sys/class/rnbd-client/ctl/devices + will be created. + + If 'dev_search_path' contains '%SESSNAME%', then each session can + have different devices namespace, e.g. server was configured with + the following parameter "dev_search_path=/run/rnbd-devs/%SESSNAME%", + client has this string "sessname=blya device_path=sda", then server + will try to open: /run/rnbd-devs/blya/sda. + + access_mode: the access_mode parameter specifies if the device is to be + mapped as "ro" read-only or "rw" read-write. The server allows + a device to be exported in rw mode only once. The "migration" + access mode has to be specified if a second mapping in read-write + mode is desired. + + By default "rw" is used. + + Exit Codes: + + If the device is already mapped it will fail with EEXIST. If the input + has an invalid format it will return EINVAL. If the device path cannot + be found on the server, it will fail with ENOENT. + + Finding device file after mapping + --------------------------------- + + After mapping, the device file can be found by: + o The symlink /sys/class/rnbd-client/ctl/devices/<device_id> + points to /sys/block/<dev-name>. The last part of the symlink destination + is the same as the device name. By extracting the last part of the + path the path to the device /dev/<dev-name> can be build. + + o /dev/block/$(cat /sys/class/rnbd-client/ctl/devices/<device_id>/dev) + + How to find the <device_id> of the device is described on the next + section. + +What: /sys/class/rnbd-client/ctl/devices/ +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: For each device mapped on the client a new symbolic link is created as + /sys/class/rnbd-client/ctl/devices/<device_id>, which points + to the block device created by rnbd (/sys/block/rnbd<N>/). + The <device_id> of each device is created as follows: + + - If the 'device_path' provided during mapping contains slashes ("/"), + they are replaced by exclamation mark ("!") and used as as the + <device_id>. Otherwise, the <device_id> will be the same as the + "device_path" provided. diff --git a/Documentation/ABI/testing/sysfs-class-rnbd-server b/Documentation/ABI/testing/sysfs-class-rnbd-server new file mode 100644 index 000000000000..ba60a90c0e45 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-rnbd-server @@ -0,0 +1,50 @@ +What: /sys/class/rnbd-server +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: provide information about RNBD-server. + +What: /sys/class/rnbd-server/ctl/ +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: When a client maps a device, a directory entry with the name of the + block device is created under /sys/class/rnbd-server/ctl/devices/. + +What: /sys/class/rnbd-server/ctl/devices/<device_name>/block_dev +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Is a symlink to the sysfs entry of the exported device. + + Example: + block_dev -> ../../../../class/block/ram0 + +What: /sys/class/rnbd-server/ctl/devices/<device_name>/sessions/ +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: For each client a particular device is exported to, following directory will be + created: + + /sys/class/rnbd-server/ctl/devices/<device_name>/sessions/<session-name>/ + + When the device is unmapped by that client, the directory will be removed. + +What: /sys/class/rnbd-server/ctl/devices/<device_name>/sessions/<session-name>/read_only +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Contains '1' if device is mapped read-only, otherwise '0'. + +What: /sys/class/rnbd-server/ctl/devices/<device_name>/sessions/<session-name>/mapping_path +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Contains the relative device path provided by the user during mapping. + +What: /sys/class/rnbd-server/ctl/devices/<device_name>/sessions/<session-name>/access_mode +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Contains the device access mode: ro, rw or migration. diff --git a/Documentation/ABI/testing/sysfs-class-rtrs-client b/Documentation/ABI/testing/sysfs-class-rtrs-client new file mode 100644 index 000000000000..e7e718db8941 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-rtrs-client @@ -0,0 +1,131 @@ +What: /sys/class/rtrs-client +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: When a user of RTRS API creates a new session, a directory entry with + the name of that session is created under /sys/class/rtrs-client/<session-name>/ + +What: /sys/class/rtrs-client/<session-name>/add_path +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: RW, adds a new path (connection) to an existing session. Expected format is the + following: + + <[source addr,]destination addr> + *addr ::= [ ip:<ipv4|ipv6> | gid:<gid> ] + +What: /sys/class/rtrs-client/<session-name>/max_reconnect_attempts +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Maximum number reconnect attempts the client should make before giving up + after connection breaks unexpectedly. + +What: /sys/class/rtrs-client/<session-name>/mp_policy +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Multipath policy specifies which path should be selected on each IO: + + round-robin (0): + select path in per CPU round-robin manner. + + min-inflight (1): + select path with minimum inflights. + +What: /sys/class/rtrs-client/<session-name>/paths/ +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Each path belonging to a given session is listed here by its source and + destination address. When a new path is added to a session by writing to + the "add_path" entry, a directory <src@dst> is created. + +What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/state +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: RO, Contains "connected" if the session is connected to the peer and fully + functional. Otherwise the file contains "disconnected" + +What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/reconnect +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Write "1" to the file in order to reconnect the path. + Operation is blocking and returns 0 if reconnect was successful. + +What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/disconnect +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Write "1" to the file in order to disconnect the path. + Operation blocks until RTRS path is disconnected. + +What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/remove_path +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Write "1" to the file in order to disconnected and remove the path + from the session. Operation blocks until the path is disconnected + and removed from the session. + +What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/hca_name +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: RO, Contains the the name of HCA the connection established on. + +What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/hca_port +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: RO, Contains the port number of active port traffic is going through. + +What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/src_addr +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: RO, Contains the source address of the path + +What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/dst_addr +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: RO, Contains the destination address of the path + +What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/stats/reset_all +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: RW, Read will return usage help, write 0 will clear all the statistics. + +What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/stats/cpu_migration +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: RTRS expects that each HCA IRQ is pinned to a separate CPU. If it's + not the case, the processing of an I/O response could be processed on a + different CPU than where it was originally submitted. This file shows + how many interrupts where generated on a non expected CPU. + "from:" is the CPU on which the IRQ was expected, but not generated. + "to:" is the CPU on which the IRQ was generated, but not expected. + +What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/stats/reconnects +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Contains 2 unsigned int values, the first one records number of successful + reconnects in the path lifetime, the second one records number of failed + reconnects in the path lifetime. + +What: /sys/class/rtrs-client/<session-name>/paths/<src@dst>/stats/rdma +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Contains statistics regarding rdma operations and inflight operations. + The output consists of 6 values: + + <read-count> <read-total-size> <write-count> <write-total-size> \ + <inflights> <failovered> diff --git a/Documentation/ABI/testing/sysfs-class-rtrs-server b/Documentation/ABI/testing/sysfs-class-rtrs-server new file mode 100644 index 000000000000..3b6d5b067df0 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-rtrs-server @@ -0,0 +1,53 @@ +What: /sys/class/rtrs-server +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: When a user of RTRS API creates a new session on a client side, a + directory entry with the name of that session is created in here. + +What: /sys/class/rtrs-server/<session-name>/paths/ +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: When new path is created by writing to "add_path" entry on client side, + a directory entry named as <source address>@<destination address> is created + on server. + +What: /sys/class/rtrs-server/<session-name>/paths/<src@dst>/disconnect +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: When "1" is written to the file, the RTRS session is being disconnected. + Operations is non-blocking and returns control immediately to the caller. + +What: /sys/class/rtrs-server/<session-name>/paths/<src@dst>/hca_name +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: RO, Contains the the name of HCA the connection established on. + +What: /sys/class/rtrs-server/<session-name>/paths/<src@dst>/hca_port +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: RO, Contains the port number of active port traffic is going through. + +What: /sys/class/rtrs-server/<session-name>/paths/<src@dst>/src_addr +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: RO, Contains the source address of the path + +What: /sys/class/rtrs-server/<session-name>/paths/<src@dst>/dst_addr +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: RO, Contains the destination address of the path + +What: /sys/class/rtrs-server/<session-name>/paths/<src@dst>/stats/rdma +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Contains statistics regarding rdma operations and inflight operations. + The output consists of 5 values: + <read-count> <read-total-size> <write-count> <write-total-size> <inflights> |