1*433d6423SLionel SambucDevelopment notes regarding libbdev, by David van Moolenbroek. 2*433d6423SLionel Sambuc 3*433d6423SLionel Sambuc 4*433d6423SLionel SambucGENERAL MODEL 5*433d6423SLionel Sambuc 6*433d6423SLionel SambucThis library is designed mainly for use by file servers. It essentially covers 7*433d6423SLionel Sambuctwo use cases: 1) use of the block device that contains the file system itself, 8*433d6423SLionel Sambucand 2) use of any block device for raw block I/O (on unmounted file systems) 9*433d6423SLionel Sambucperformed by the root file server. In the first case, the file server is 10*433d6423SLionel Sambucresponsible for opening and closing the block device, and recovery from a 11*433d6423SLionel Sambucdriver restart involves reopening those minor devices. Regular file systems 12*433d6423SLionel Sambucshould have one or at most two (for a separate journal) block devices open at 13*433d6423SLionel Sambucthe same time, which is why NR_OPEN_DEVS is set to a value that is quite low. 14*433d6423SLionel SambucIn the second case, VFS is responsible for opening and closing the block device 15*433d6423SLionel Sambuc(and performing IOCTLs), as well as reopening the block device on a driver 16*433d6423SLionel Sambucrestart -- the root file server only gets raw I/O (and flush) requests. 17*433d6423SLionel Sambuc 18*433d6423SLionel SambucAt this time, libbdev considers only clean crashes (a crash-only model), and 19*433d6423SLionel Sambucdoes not support recovery from behavioral errors. Protocol errors are passed to 20*433d6423SLionel Sambucthe user process, and generally do not have an effect on the overall state of 21*433d6423SLionel Sambucthe library. 22*433d6423SLionel Sambuc 23*433d6423SLionel Sambuc 24*433d6423SLionel SambucRETRY MODEL 25*433d6423SLionel Sambuc 26*433d6423SLionel SambucThe philosophy for recovering from driver restarts in libbdev can be formulated 27*433d6423SLionel Sambucas follows: we want to tolerate an unlimited number of driver restarts over a 28*433d6423SLionel Sambuclong time, but we do not want to keep retrying individual requests across 29*433d6423SLionel Sambucdriver restarts. As such, we do not keep track of driver restarts on a per- 30*433d6423SLionel Sambucdriver basis, because that would mean we put a hard limit on the number of 31*433d6423SLionel Sambucrestarts for that driver in total. Instead, there are two limits: a driver 32*433d6423SLionel Sambucrestart limit that is kept on a per-request basis, failing only that request 33*433d6423SLionel Sambucwhen the limit is reached, and a driver restart limit that is kept during 34*433d6423SLionel Sambucrecovery, limiting the number of restarts and eventually giving up on the 35*433d6423SLionel Sambucentire driver when even the recovery keeps failing (as no progress is made in 36*433d6423SLionel Sambucthat case). 37*433d6423SLionel Sambuc 38*433d6423SLionel SambucEach transfer request also has a transfer retry count. The assumption here is 39*433d6423SLionel Sambucthat when a transfer request returns EIO, it can be retried and possibly 40*433d6423SLionel Sambucsucceed upon repetition. The driver restart and transfer retry counts are 41*433d6423SLionel Sambuctracked independently and thus the first to hit the limit will fail the 42*433d6423SLionel Sambucrequest. The behavior should be the same for synchronous and asynchronous 43*433d6423SLionel Sambucrequests in this respect. 44*433d6423SLionel Sambuc 45*433d6423SLionel SambucIt could happen that a new driver gets loaded after we have decided that the 46*433d6423SLionel Sambuccurrent driver is unusable. This could be due to a race condition (VFS sends a 47*433d6423SLionel Sambucnew-driver request after we've given up) or due to user interaction (the user 48*433d6423SLionel Sambucloads a replacement driver). The latter case may occur legitimately with raw 49*433d6423SLionel SambucI/O on the root file server, so we must not mark the driver as unusable 50*433d6423SLionel Sambucforever. On the other hand, in the former case, we must not continue to send 51*433d6423SLionel SambucI/O without first reopening the minor devices. For this reason, we do not clean 52*433d6423SLionel Sambucup the record of the minor devices when we mark a driver as unusable. 53