diff --git a/CHANGELOG.md b/CHANGELOG.md
index 47df1ca2e..6b184cb24 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -51,7 +51,7 @@ A new structure spdk_mem_map_ops has been introduced to hold memory map related
 callbacks. This structure is now passed as the second argument of spdk_mem_map_alloc
 in lieu of the notify callback.
 
-### iscsi
+### iscsi target
 
 Parameter names of `set_iscsi_options` and `get_iscsi_global_params` RPC
 method for CHAP authentication in discovery sessions have been changed to
@@ -69,6 +69,12 @@ specified. This default has been removed. Users must now explicitly specify
 the location of this file to load CHAP shared secrets from a file, or use
 the related iSCSI RPC methods to add them at runtime.
 
+### iscsi initiator
+
+The SPDK iSCSI initiator is no longer perceived experimental and becomes
+a first-class citizen among bdev modules. The basic usage has been briefly
+described in the bdev user guide: [iSCSI bdev](https://spdk.io/doc/bdev.html#bdev_config_iscsi)
+
 ### Miscellaneous
 
 The ReactorMask config file parameter has been deprecated.  Users should
diff --git a/doc/bdev.md b/doc/bdev.md
index a739befbb..b40e0b135 100644
--- a/doc/bdev.md
+++ b/doc/bdev.md
@@ -198,6 +198,19 @@ rpc.py stop_nbd_disk /dev/nbd0
 # Nvme0n1p1 in SPDK applications.
 ~~~
 
+# iSCSI bdev {#bdev_config_iscsi}
+
+The SPDK iSCSI bdev driver depends on libiscsi and hence is not enabled by default.
+In order to use it, build SPDK with an extra `--with-iscsi-initiator` configure option.
+
+The following command creates an `iSCSI0` bdev from a single LUN exposed at given iSCSI URL
+with `iqn.2016-06.io.spdk:init` as the reported initiator IQN.
+
+`rpc.py construct_iscsi_bdev -b iSCSI0 -i iqn.2016-06.io.spdk:init --url iscsi://127.0.0.1/iqn.2016-06.io.spdk:disk1/0`
+
+The URL is in the following format:
+`iscsi://[<username>[%<password>]@]<host>[:<port>]/<target-iqn>/<lun>`
+
 # Linux AIO bdev {#bdev_config_aio}
 
 The SPDK AIO bdev driver provides SPDK block layer access to Linux kernel block
diff --git a/lib/bdev/iscsi/README b/lib/bdev/iscsi/README
deleted file mode 100644
index d8c96b411..000000000
--- a/lib/bdev/iscsi/README
+++ /dev/null
@@ -1,26 +0,0 @@
-This is a very rough initial cut at an SPDK iSCSI initiator bdev module.  It
-only performs operations (connect, login, read cap, read/write).
-But this passes basic verify tests with bdevperf and with fio.
-
-Be sure to build SPDK using --with-iscsi-initiator configure option.
-
-Configuration file for iSCSI initiator is in the following format.
-Note that the "/0" at the end means "LUN 0".
-
-[iSCSI_Initiator]
-  URL iscsi://127.0.0.1/iqn.2016-06.io.spdk:disk1/0 iSCSI0
-
-To Do Items
-===========
-1) Create RPCs.
-2) Use asynchronous polling for connect/login/disconnect.  Read/write is already
-   using libiscsi event framework.
-3) Choose initiator name as part of RPC configuration.  Currently this is hardcoded
-   with g_initiator string.
-4) Implement reset path.
-5) Implement unmap path.
-6) Use REPORT_LUNS to dynamically find all of the block devices attached to the
-   iSCSI target node instead of hard-coding LUN 0.  This will need some extra
-   investigation in libiscsi.  Currently the full URL is used which includes the LUN.
-   Not sure yet how we can login to target node and then submit IO to different
-   LUNs.  Let's treat this as low priority for now.