| Message ID | 20161201101446.wl2bvzlrzk775kij@grep.be (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
01.12.2016 13:14, Wouter Verhelst wrote: > Here's another update. > > Changes since previous version: > - Rename "allocation context" to "metadata context" > - Stop making metadata context 0 be special; instead, name it > "BASE:allocation" and allow it to be selected like all other contexts. > - Clarify in a bit more detail when a server MAY omit metadata > information on a particular metadata context (i.e., only if another > metadata context that we actually got information for implies it can't > have meaning). This was always meant that way, but the spec could have > been a bit more explicit about it. > - Change one SHOULD to a MUST, where it should not have been a SHOULD > in the first place. > > (This applies on top of my previous patch) > > Applied and visible at the usual place. > > diff --git a/doc/proto.md b/doc/proto.md > index fe7ae53..9c0981f 100644 > --- a/doc/proto.md > +++ b/doc/proto.md > @@ -869,16 +869,16 @@ of the newstyle negotiation. > > Defined by the experimental `INFO` [extension](https://github.com/NetworkBlockDevice/nbd/blob/extension-info/doc/proto.md). > > -- `NBD_OPT_ALLOC_CONTEXT` (10) > +- `NBD_OPT_META_CONTEXT` (10) > > - Return a list of `NBD_REP_ALLOC_CONTEXT` replies, one per context, > + Return a list of `NBD_REP_META_CONTEXT` replies, one per context, > followed by an `NBD_REP_ACK`. If a server replies to such a request > with no error message, clients MAY send NBD_CMD_BLOCK_STATUS > commands during the transmission phase. > > If the query string is syntactically invalid, the server SHOULD send > `NBD_REP_ERR_INVALID`. If the query string is syntactically valid > - but finds no allocation contexts, the server MUST send a single > + but finds no metadata contexts, the server MUST send a single > reply of type `NBD_REP_ACK`. > > This option MUST NOT be requested unless structured replies have > @@ -887,9 +887,9 @@ of the newstyle negotiation. > > Data: > - 32 bits, type > - - String, query to select a subset of the available allocation > + - String, query to select a subset of the available metadata > contexts. If this is not specified (i.e., length is 4 and no > - command is sent), then the server MUST send all the allocation > + command is sent), then the server MUST send all the metadata > contexts it knows about. If specified, this query string MUST > start with a name that uniquely identifies a server > implementation; e.g., the reference implementation that > @@ -897,18 +897,22 @@ of the newstyle negotiation. > with 'nbd-server:' > > The type may be one of: > - - `NBD_ALLOC_LIST_CONTEXT` (1): the list of allocation contexts > + - `NBD_META_LIST_CONTEXT` (1): the list of metadata contexts > selected by the query string is returned to the client without > - changing any state (i.e., this does not add allocation contexts > + changing any state (i.e., this does not add metadata contexts > for further usage). > - - `NBD_ALLOC_ADD_CONTEXT` (2): the list of allocation contexts > + - `NBD_META_ADD_CONTEXT` (2): the list of metadata contexts > selected by the query string is added to the list of existing If I understand correctly, it should be not 'existing', but 'exporting'. So there are several contexts, server knows about. They are definitely exists. Some of them may be selected (by client) for export (to client, through get_block_status). so, what about 'list of metadata contexts to export' or something like this? > - allocation contexts. > - - `NBD_ALLOC_DEL_CONTEXT` (3): the list of allocation contexts > + metadata contexts. > + - `NBD_META_DEL_CONTEXT` (3): the list of metadata contexts > selected by the query string is removed from the list of used > - allocation contexts. Servers SHOULD NOT reuse existing allocation > + metadata contexts. Servers SHOULD NOT reuse existing metadata > context IDs. > > + The syntax of the query string is not specified, except that > + implementations MUST support adding and removing individual metadata > + contexts by simply listing their names. > + > #### Option reply types > > These values are used in the "reply type" field, sent by the server > @@ -920,7 +924,7 @@ during option haggling in the fixed newstyle negotiation. > information is available, or when sending data related to the option > (in the case of `NBD_OPT_LIST`) has finished. No data. > > -* `NBD_REP_SERVER` (2) > +- `NBD_REP_SERVER` (2) > > A description of an export. Data: > > @@ -935,21 +939,20 @@ during option haggling in the fixed newstyle negotiation. > particular client request, this field is defined to be a string > suitable for direct display to a human being. > > -* `NBD_REP_INFO` (3) > +- `NBD_REP_INFO` (3) > > Defined by the experimental `INFO` [extension](https://github.com/NetworkBlockDevice/nbd/blob/extension-info/doc/proto.md). > > -- `NBD_REP_ALLOC_CONTEXT` (4) > +- `NBD_REP_META_CONTEXT` (4) > > - A description of an allocation context. Data: > + A description of a metadata context. Data: > > - - 32 bits, NBD allocation context ID. If the request was NOT of type > - `NBD_ALLOC_LIST_CONTEXT`, this field MUST NOT be zero. > - - String, name of the allocation context. This is not required to be > + - 32 bits, NBD metadata context ID. > + - String, name of the metadata context. This is not required to be > a human-readable string, but it MUST be valid UTF-8 data. > > - Allocation context ID 0 is implied, and always exists. It cannot be > - removed. > + This specification declares one metadata context. It is called > + "BASE:allocation" and contains the basic "exists at all" context. > > There are a number of error reply types, all of which are denoted by > having bit 31 set. All error replies MAY have some data set, in which > @@ -997,36 +1000,37 @@ case that data is an error message string suitable for display to the user. > > Defined by the experimental `INFO` [extension](https://github.com/NetworkBlockDevice/nbd/blob/extension-info/doc/proto.md). > > -##### Allocation contexts > +##### Metadata contexts > > -Allocation context 0 is the basic "exists at all" allocation context. If > -an extent is not allocated at allocation context 0, it MUST NOT be > -listed as allocated at another allocation context. This supports sparse > -file semantics on the server side. If a server has only one allocation > -context (the default), then writing to an extent which is allocated in > -that allocation context 0 MUST NOT fail with ENOSPC. > +The "BASE:allocation" metadata context is the basic "exists at all" > +metadata context. If an extent is marked with `NBD_STATE_HOLE` at that > +context, this means that the given extent is not allocated in the > +backend storage, and that writing to the extent MAY result in the ENOSPC > +error. This supports sparse file semantics on the server side. If a > +server has only one metadata context (the default), then writing to an > +extent which has `NBD_STATE_HOLE` clear MUST NOT fail with ENOSPC. this dependence looks strange. user defined metadata, why it affects allocation? At least, 'only one' is not descriptive, it would be better to mention 'BASE:allocation' name. (I hope, I can ask server to export only dirty_bitmap context, not exporting allocation? In that case this 'only one' would be dirty_bitmap) > > For all other cases, this specification requires no specific semantics what are 'other cases'? For all other metadata contexts? Or for all cases when we have more than one context? > -of allocation contexts. Implementations could support allocation > +of metadata contexts. Implementations could support metadata > contexts with semantics like the following: > > -- Incremental snapshots; if a block is allocated in one allocation > +- Incremental snapshots; if a block is allocated in one metadata > context, that implies that it is also allocated in the next level up. > - Various bits of data about the backend of the storage; e.g., if the > - storage is written on a RAID array, an allocation context could > + storage is written on a RAID array, a metadata context could > return information about the redundancy level of a given extent > - If the backend implements a write-through cache of some sort, or > - synchronises with other servers, an allocation context could state > - that an extent is "allocated" once it has reached permanent storage > + synchronises with other servers, a metadata context could state > + that an extent is "active" once it has reached permanent storage > and/or is synchronized with other servers. Incremental snapshots sounds strange for me. Snapshots are just snapshots.. Backup may be incremental, but it is not about snapshots.. I think this example may be safely deleted from the spec. > > -The only requirement of an allocation context is that it MUST be > +The only requirement of a metadata context is that it MUST be > representable with the flags as defined for `NBD_CMD_BLOCK_STATUS`. > > Likewise, the syntax of query strings is not specified by this document. > > Server implementations SHOULD document their syntax for query strings > -and semantics for resulting allocation contexts in a document like this > +and semantics for resulting metadata contexts in a document like this > one. > > ### Transmission phase > @@ -1066,7 +1070,7 @@ valid may depend on negotiation during the handshake phase. > flags include `NBD_FLAG_SEND_DF`. Use of this flag MAY trigger an > `EOVERFLOW` error chunk, if the request length is too large. > - bit 3, `NBD_CMD_FLAG_REQ_ONE`; valid during `NBD_CMD_BLOCK_STATUS`. If > - set, the client is interested in only one extent per allocation > + set, the client is interested in only one extent per metadata > context. > > ##### Structured reply flags > @@ -1462,17 +1466,22 @@ unless the client also negotiates the `STRUCTURED_REPLY` extension. > represents a series of consecutive block descriptors where the sum > of the lengths of the descriptors MUST not be greater than the > length of the original request. This chunk type MUST appear at most > - once per allocation ID in a structured reply. Valid as a reply to > + once per metadata ID in a structured reply. Valid as a reply to > `NBD_CMD_BLOCK_STATUS`. > > Servers MUST return an `NBD_REPLY_TYPE_BLOCK_STATUS` chunk for every > - allocation context ID, except if the semantics of particular > - allocation contexts mean that the information for one allocation > - context is implied by the information for another. > + metadata context ID, except if the semantics of particular > + metadata contexts mean that the information for one active metadata > + context is implied by the information for another; e.g., if a > + particular metadata context can only have meaning for extents where > + the `NBD_STATE_HOLE` flag is cleared on the "BASE:allocation" > + context, servers MAY omit the relevant chunks for that context if > + they already sent an extent with the `NBD_STATE_HOLE` flag set in > + reply to the same `NBD_CMD_BLOCK_STATUS` command. Hmm stop. Are you saying that server may omit some status descriptors for some context? But how? We have not field 'offset' in status descriptor.. Or we can omit _context_, if _all_ descriptors of allocation context are holes? Anyway, I'm still against this paragraph. These 8 lines actually say "server may omit contexts if he wants". I always can explain that semantics of some context means that metadata is implied (actually, I can just introduce such semantics).., but it not differs with "I want to omit this". In this spec there is no way to negotiate context semantics, so actually client doesn't know it. We just hope, that both client and server are managed by some layer, which knows what is it all about. Also. If it all is about "metadata", name NBD_CMD_BLOCK_STATUS becomes not very descriptive... May be we should move to something like just NBD_CMD_GET_METADATA ) > > The payload starts with: > > - * 32 bits, allocation context ID > + * 32 bits, metadata context ID > > and is followed by a list of one or more descriptors, each with this > layout: > @@ -1493,7 +1502,7 @@ unless the client also negotiates the `STRUCTURED_REPLY` extension. > * `NBD_CMD_BLOCK_STATUS` > > A block status query request. Length and offset define the range of > - interest. Clients SHOULD NOT use this request unless allocation > + interest. Clients MUST NOT use this request unless metadata > contexts have been negotiated, which in turn requires the client to > first negotiate structured replies. For a successful return, the > server MUST use a structured reply, containing at least one chunk of > @@ -1533,7 +1542,7 @@ unless the client also negotiates the `STRUCTURED_REPLY` extension. > or the server could not otherwise determine its status. Note > that the use of `NBD_CMD_TRIM` is related to this status, but > that the server MAY report a hole even where trim has not been > - requested, and also that a server MAY report allocation even > + requested, and also that a server MAY report metadata even > where a trim has been requested. > - `NBD_STATE_ZERO` (bit 1): if set, the block contents read as > all zeroes; if clear, the block contents are not known. Note > @@ -1547,25 +1556,25 @@ unless the client also negotiates the `STRUCTURED_REPLY` extension. > been written; if clear, the block represents a portion of the > file that is dirty, or where the server could not otherwise > determine its status. The server MUST NOT set this bit for > - allocation context 0, where it has no meaning. > + the "BASE:allocation" context, where it has no meaning. > - `NBD_STATE_ACTIVE` (bit 3): if set, the block represents a > - portion of the file that is "active" in the given allocation > - context. The server MUST NOT set this bit for allocation context > - 0, where it has no meaning. > + portion of the file that is "active" in the given metadata > + context. The server MUST NOT set this bit for the > + "BASE:allocation" context, where it has no meaning. > > The exact semantics of what it means for a block to be "clean" or > - "active" at a given allocation context is not defined by this > + "active" at a given metadata context is not defined by this > specification, except that the default in both cases should be to > - clear the bit. That is, when the allocation context does not have > + clear the bit. That is, when the metadata context does not have > knowledge of the relevant status for the given extent, or when the > - allocation context does not assign any meaning to it, the bits > + metadata context does not assign any meaning to it, the bits > should be cleared. And again. If we said that it is user-defined metadata, and it is not defined in this spec, why to define not-defined flags? I propose to remove from here all tries to define internals of user-defined-metadata, and than, when we finish up with clean and simple spec of the feature, we can add separate paragraph, which will define metadata context for dirty bitmaps like this: ==== Metadata contexts for NBD_CMD_.... , with names not started with "BASE:", are defined by third-party tools, but to avoid conflicts and to have common documentation it is recommended to publish their names and short descriptions here. QEMU_DIRTY_BITMAP:<name> - contexts family of dirty bitmaps, defined by Qemu. Dirty bitmap is ...., It is used for ..., by some-company. status extent flags: bit 0: 0 - means dirty [If you want, but I prefer 0 - clean, 1 - dirty] 1 - means clean bits 1-31: reserved, always zero. RANDOM_DATA - just random data status extent flags: all 32 bits: random data ... ==== > > A client SHOULD NOT read from an area that has both `NBD_STATE_HOLE` > set and `NBD_STATE_ZERO` clear. > > A client MAY close the connection if it detects that the server has > -sent an invalid chunks (such as lengths in the > +sent an invalid chunk (such as lengths in the > `NBD_REPLY_TYPE_BLOCK_STATUS` not summing up to the requested length). > The server SHOULD return `EINVAL` if it receives a `BLOCK_STATUS` > request including one or more sectors beyond the size of the device. > @@ -1574,7 +1583,7 @@ The extension adds the following new command flag: > > - `NBD_CMD_FLAG_REQ_ONE`; valid during `NBD_CMD_BLOCK_STATUS`. > SHOULD be set to 1 if the client wants to request information for only > - one extent per allocation context. > + one extent per metadata context. > > ## About this file > >
Hi Vladimir, On Thu, Dec 01, 2016 at 02:26:28PM +0300, Vladimir Sementsov-Ogievskiy wrote: > 01.12.2016 13:14, Wouter Verhelst wrote: [...] > > - - `NBD_ALLOC_ADD_CONTEXT` (2): the list of allocation contexts > > + - `NBD_META_ADD_CONTEXT` (2): the list of metadata contexts > > selected by the query string is added to the list of existing > > - allocation contexts. > > If I understand correctly, it should be not 'existing', but 'exporting'. > So there are several contexts, server knows about. They are definitely > exists. Some of them may be selected (by client) for export (to client, > through get_block_status). > > so, what about 'list of metadata contexts to export' or something like this? Yes, good idea. Thanks. [...] > > +The "BASE:allocation" metadata context is the basic "exists at all" > > +metadata context. If an extent is marked with `NBD_STATE_HOLE` at that > > +context, this means that the given extent is not allocated in the > > +backend storage, and that writing to the extent MAY result in the ENOSPC > > +error. This supports sparse file semantics on the server side. If a > > +server has only one metadata context (the default), then writing to an > > +extent which has `NBD_STATE_HOLE` clear MUST NOT fail with ENOSPC. > > this dependence looks strange. user defined metadata, why it affects > allocation? The reference nbd-server implementation (i.e., the one that accompanies this document) has a "copy-on-write" mode in which modifications are written to a separate file. This separate file can easily be a sparse file. Let's say you have an export which is fully allocated; the BASE:allocation state would have STATE_HOLE cleared. However, when writing to a particular block that has not yet been written to during that session, the copy-on-write mode would have to allocate a new block in the copy-on-write file, which may fail with ENOSPC. Perhaps the above paragraph could be updated in the sense that it SHOULD NOT fail in other cases, but that it may depend on the semantics of the other metadata contexts, whether active (i.e., selected with NBD_OPT_META_CONTEXT) or not. Side note: that does mean that some metadata contexts may be specific to particular exports (e.g., you may have a list of named snapshots to select, and which ones would exist would depend on the specific export chosen). I guess that means the metadata contexts should have the name of the export, too. > At least, 'only one' is not descriptive, it would be better to mention > 'BASE:allocation' name. Yes, that would make things clearer, indeed. > (I hope, I can ask server to export only dirty_bitmap context, not > exporting allocation? That was the point of naming that context and making it selectable :-) > In that case this 'only one' would be dirty_bitmap) > > > For all other cases, this specification requires no specific semantics > > what are 'other cases'? For all other metadata contexts? Or for all > cases when we have more than one context? Other metadata contexts. I'll rephrease it in that sense. > > -of allocation contexts. Implementations could support allocation > > +of metadata contexts. Implementations could support metadata > > contexts with semantics like the following: > > > > -- Incremental snapshots; if a block is allocated in one allocation > > +- Incremental snapshots; if a block is allocated in one metadata > > context, that implies that it is also allocated in the next level up. > > - Various bits of data about the backend of the storage; e.g., if the > > - storage is written on a RAID array, an allocation context could > > + storage is written on a RAID array, a metadata context could > > return information about the redundancy level of a given extent > > - If the backend implements a write-through cache of some sort, or > > - synchronises with other servers, an allocation context could state > > - that an extent is "allocated" once it has reached permanent storage > > + synchronises with other servers, a metadata context could state > > + that an extent is "active" once it has reached permanent storage > > and/or is synchronized with other servers. > > Incremental snapshots sounds strange for me. Snapshots are just > snapshots.. Backup may be incremental, but it is not about snapshots.. I > think this example may be safely deleted from the spec. Yeah, I'll just remove all the examples; they're not really critical, anyway, and might indeed confuse people. [...] > > Servers MUST return an `NBD_REPLY_TYPE_BLOCK_STATUS` chunk for every > > - allocation context ID, except if the semantics of particular > > - allocation contexts mean that the information for one allocation > > - context is implied by the information for another. > > + metadata context ID, except if the semantics of particular > > + metadata contexts mean that the information for one active metadata > > + context is implied by the information for another; e.g., if a > > + particular metadata context can only have meaning for extents where > > + the `NBD_STATE_HOLE` flag is cleared on the "BASE:allocation" > > + context, servers MAY omit the relevant chunks for that context if > > + they already sent an extent with the `NBD_STATE_HOLE` flag set in > > + reply to the same `NBD_CMD_BLOCK_STATUS` command. > > Hmm stop. Are you saying that server may omit some status descriptors > for some context? But how? We have not field 'offset' in status > descriptor.. Ah. Yes. I'm an idiot :-) > Or we can omit _context_, if _all_ descriptors of allocation context > are holes? > > Anyway, I'm still against this paragraph. These 8 lines actually say > "server may omit contexts if he wants". I always can explain that > semantics of some context means that metadata is implied (actually, I > can just introduce such semantics).., but it not differs with "I want to > omit this". In this spec there is no way to negotiate context semantics, > so actually client doesn't know it. We just hope, that both client and > server are managed by some layer, which knows what is it all about. Yes, I suppose you're right. I'll remove it. It never hurts to send too much information, and otherwise clients might have to become "too smart" to understand things properly. > Also. If it all is about "metadata", name NBD_CMD_BLOCK_STATUS becomes > not very descriptive... May be we should move to something like just > NBD_CMD_GET_METADATA ) I don't think that's critical (and I'd rather not rename the branch ;-P ) [...] > > The exact semantics of what it means for a block to be "clean" or > > - "active" at a given allocation context is not defined by this > > + "active" at a given metadata context is not defined by this > > specification, except that the default in both cases should be to > > - clear the bit. That is, when the allocation context does not have > > + clear the bit. That is, when the metadata context does not have > > knowledge of the relevant status for the given extent, or when the > > - allocation context does not assign any meaning to it, the bits > > + metadata context does not assign any meaning to it, the bits > > should be cleared. > > And again. If we said that it is user-defined metadata, and it is not > defined in this spec, why to define not-defined flags? I propose to > remove from here all tries to define internals of user-defined-metadata, > and than, when we finish up with clean and simple spec of the feature, > we can add separate paragraph, which will define metadata context for > dirty bitmaps like this: Good point. I'll leave the "bits should be cleared" bit in there, though. > ==== > Metadata contexts for NBD_CMD_.... , with names not started with > "BASE:", are defined by third-party tools, but to avoid conflicts and to > have common documentation it is recommended to publish their names and > short descriptions here. > > QEMU_DIRTY_BITMAP:<name> - contexts family of dirty bitmaps, defined by > Qemu. Dirty bitmap is ...., It is used for ..., by some-company. > status extent flags: > bit 0: 0 - means dirty [If you want, > but I prefer 0 - clean, 1 - dirty] > 1 - means clean > bits 1-31: reserved, always zero. > RANDOM_DATA - just random data > status extent flags: > all 32 bits: random data > .... > ==== I don't think semantics of third-party implementations' metadata modes should be part of this document, but I would be happy to add a link to a document describing such semantics. Thanks for your review!
diff --git a/doc/proto.md b/doc/proto.md index fe7ae53..9c0981f 100644 --- a/doc/proto.md +++ b/doc/proto.md @@ -869,16 +869,16 @@ of the newstyle negotiation. Defined by the experimental `INFO` [extension](https://github.com/NetworkBlockDevice/nbd/blob/extension-info/doc/proto.md). -- `NBD_OPT_ALLOC_CONTEXT` (10) +- `NBD_OPT_META_CONTEXT` (10) - Return a list of `NBD_REP_ALLOC_CONTEXT` replies, one per context, + Return a list of `NBD_REP_META_CONTEXT` replies, one per context, followed by an `NBD_REP_ACK`. If a server replies to such a request with no error message, clients MAY send NBD_CMD_BLOCK_STATUS commands during the transmission phase. If the query string is syntactically invalid, the server SHOULD send `NBD_REP_ERR_INVALID`. If the query string is syntactically valid - but finds no allocation contexts, the server MUST send a single + but finds no metadata contexts, the server MUST send a single reply of type `NBD_REP_ACK`. This option MUST NOT be requested unless structured replies have @@ -887,9 +887,9 @@ of the newstyle negotiation. Data: - 32 bits, type - - String, query to select a subset of the available allocation + - String, query to select a subset of the available metadata contexts. If this is not specified (i.e., length is 4 and no - command is sent), then the server MUST send all the allocation + command is sent), then the server MUST send all the metadata contexts it knows about. If specified, this query string MUST start with a name that uniquely identifies a server implementation; e.g., the reference implementation that @@ -897,18 +897,22 @@ of the newstyle negotiation. with 'nbd-server:' The type may be one of: - - `NBD_ALLOC_LIST_CONTEXT` (1): the list of allocation contexts + - `NBD_META_LIST_CONTEXT` (1): the list of metadata contexts selected by the query string is returned to the client without - changing any state (i.e., this does not add allocation contexts + changing any state (i.e., this does not add metadata contexts for further usage). - - `NBD_ALLOC_ADD_CONTEXT` (2): the list of allocation contexts + - `NBD_META_ADD_CONTEXT` (2): the list of metadata contexts selected by the query string is added to the list of existing - allocation contexts. - - `NBD_ALLOC_DEL_CONTEXT` (3): the list of allocation contexts + metadata contexts. + - `NBD_META_DEL_CONTEXT` (3): the list of metadata contexts selected by the query string is removed from the list of used - allocation contexts. Servers SHOULD NOT reuse existing allocation + metadata contexts. Servers SHOULD NOT reuse existing metadata context IDs. + The syntax of the query string is not specified, except that + implementations MUST support adding and removing individual metadata + contexts by simply listing their names. + #### Option reply types These values are used in the "reply type" field, sent by the server @@ -920,7 +924,7 @@ during option haggling in the fixed newstyle negotiation. information is available, or when sending data related to the option (in the case of `NBD_OPT_LIST`) has finished. No data. -* `NBD_REP_SERVER` (2) +- `NBD_REP_SERVER` (2) A description of an export. Data: @@ -935,21 +939,20 @@ during option haggling in the fixed newstyle negotiation. particular client request, this field is defined to be a string suitable for direct display to a human being. -* `NBD_REP_INFO` (3) +- `NBD_REP_INFO` (3) Defined by the experimental `INFO` [extension](https://github.com/NetworkBlockDevice/nbd/blob/extension-info/doc/proto.md). -- `NBD_REP_ALLOC_CONTEXT` (4) +- `NBD_REP_META_CONTEXT` (4) - A description of an allocation context. Data: + A description of a metadata context. Data: - - 32 bits, NBD allocation context ID. If the request was NOT of type - `NBD_ALLOC_LIST_CONTEXT`, this field MUST NOT be zero. - - String, name of the allocation context. This is not required to be + - 32 bits, NBD metadata context ID. + - String, name of the metadata context. This is not required to be a human-readable string, but it MUST be valid UTF-8 data. - Allocation context ID 0 is implied, and always exists. It cannot be - removed. + This specification declares one metadata context. It is called + "BASE:allocation" and contains the basic "exists at all" context. There are a number of error reply types, all of which are denoted by having bit 31 set. All error replies MAY have some data set, in which @@ -997,36 +1000,37 @@ case that data is an error message string suitable for display to the user. Defined by the experimental `INFO` [extension](https://github.com/NetworkBlockDevice/nbd/blob/extension-info/doc/proto.md). -##### Allocation contexts +##### Metadata contexts -Allocation context 0 is the basic "exists at all" allocation context. If -an extent is not allocated at allocation context 0, it MUST NOT be -listed as allocated at another allocation context. This supports sparse -file semantics on the server side. If a server has only one allocation -context (the default), then writing to an extent which is allocated in -that allocation context 0 MUST NOT fail with ENOSPC. +The "BASE:allocation" metadata context is the basic "exists at all" +metadata context. If an extent is marked with `NBD_STATE_HOLE` at that +context, this means that the given extent is not allocated in the +backend storage, and that writing to the extent MAY result in the ENOSPC +error. This supports sparse file semantics on the server side. If a +server has only one metadata context (the default), then writing to an +extent which has `NBD_STATE_HOLE` clear MUST NOT fail with ENOSPC. For all other cases, this specification requires no specific semantics -of allocation contexts. Implementations could support allocation +of metadata contexts. Implementations could support metadata contexts with semantics like the following: -- Incremental snapshots; if a block is allocated in one allocation +- Incremental snapshots; if a block is allocated in one metadata context, that implies that it is also allocated in the next level up. - Various bits of data about the backend of the storage; e.g., if the - storage is written on a RAID array, an allocation context could + storage is written on a RAID array, a metadata context could return information about the redundancy level of a given extent - If the backend implements a write-through cache of some sort, or - synchronises with other servers, an allocation context could state - that an extent is "allocated" once it has reached permanent storage + synchronises with other servers, a metadata context could state + that an extent is "active" once it has reached permanent storage and/or is synchronized with other servers. -The only requirement of an allocation context is that it MUST be +The only requirement of a metadata context is that it MUST be representable with the flags as defined for `NBD_CMD_BLOCK_STATUS`. Likewise, the syntax of query strings is not specified by this document. Server implementations SHOULD document their syntax for query strings -and semantics for resulting allocation contexts in a document like this +and semantics for resulting metadata contexts in a document like this one. ### Transmission phase @@ -1066,7 +1070,7 @@ valid may depend on negotiation during the handshake phase. flags include `NBD_FLAG_SEND_DF`. Use of this flag MAY trigger an `EOVERFLOW` error chunk, if the request length is too large. - bit 3, `NBD_CMD_FLAG_REQ_ONE`; valid during `NBD_CMD_BLOCK_STATUS`. If - set, the client is interested in only one extent per allocation + set, the client is interested in only one extent per metadata context. ##### Structured reply flags @@ -1462,17 +1466,22 @@ unless the client also negotiates the `STRUCTURED_REPLY` extension. represents a series of consecutive block descriptors where the sum of the lengths of the descriptors MUST not be greater than the length of the original request. This chunk type MUST appear at most - once per allocation ID in a structured reply. Valid as a reply to + once per metadata ID in a structured reply. Valid as a reply to `NBD_CMD_BLOCK_STATUS`. Servers MUST return an `NBD_REPLY_TYPE_BLOCK_STATUS` chunk for every - allocation context ID, except if the semantics of particular - allocation contexts mean that the information for one allocation - context is implied by the information for another. + metadata context ID, except if the semantics of particular + metadata contexts mean that the information for one active metadata + context is implied by the information for another; e.g., if a + particular metadata context can only have meaning for extents where + the `NBD_STATE_HOLE` flag is cleared on the "BASE:allocation" + context, servers MAY omit the relevant chunks for that context if + they already sent an extent with the `NBD_STATE_HOLE` flag set in + reply to the same `NBD_CMD_BLOCK_STATUS` command. The payload starts with: - * 32 bits, allocation context ID + * 32 bits, metadata context ID and is followed by a list of one or more descriptors, each with this layout: @@ -1493,7 +1502,7 @@ unless the client also negotiates the `STRUCTURED_REPLY` extension. * `NBD_CMD_BLOCK_STATUS` A block status query request. Length and offset define the range of - interest. Clients SHOULD NOT use this request unless allocation + interest. Clients MUST NOT use this request unless metadata contexts have been negotiated, which in turn requires the client to first negotiate structured replies. For a successful return, the server MUST use a structured reply, containing at least one chunk of @@ -1533,7 +1542,7 @@ unless the client also negotiates the `STRUCTURED_REPLY` extension. or the server could not otherwise determine its status. Note that the use of `NBD_CMD_TRIM` is related to this status, but that the server MAY report a hole even where trim has not been - requested, and also that a server MAY report allocation even + requested, and also that a server MAY report metadata even where a trim has been requested. - `NBD_STATE_ZERO` (bit 1): if set, the block contents read as all zeroes; if clear, the block contents are not known. Note @@ -1547,25 +1556,25 @@ unless the client also negotiates the `STRUCTURED_REPLY` extension. been written; if clear, the block represents a portion of the file that is dirty, or where the server could not otherwise determine its status. The server MUST NOT set this bit for - allocation context 0, where it has no meaning. + the "BASE:allocation" context, where it has no meaning. - `NBD_STATE_ACTIVE` (bit 3): if set, the block represents a - portion of the file that is "active" in the given allocation - context. The server MUST NOT set this bit for allocation context - 0, where it has no meaning. + portion of the file that is "active" in the given metadata + context. The server MUST NOT set this bit for the + "BASE:allocation" context, where it has no meaning. The exact semantics of what it means for a block to be "clean" or - "active" at a given allocation context is not defined by this + "active" at a given metadata context is not defined by this specification, except that the default in both cases should be to - clear the bit. That is, when the allocation context does not have + clear the bit. That is, when the metadata context does not have knowledge of the relevant status for the given extent, or when the - allocation context does not assign any meaning to it, the bits + metadata context does not assign any meaning to it, the bits should be cleared. A client SHOULD NOT read from an area that has both `NBD_STATE_HOLE` set and `NBD_STATE_ZERO` clear. A client MAY close the connection if it detects that the server has -sent an invalid chunks (such as lengths in the +sent an invalid chunk (such as lengths in the `NBD_REPLY_TYPE_BLOCK_STATUS` not summing up to the requested length). The server SHOULD return `EINVAL` if it receives a `BLOCK_STATUS` request including one or more sectors beyond the size of the device. @@ -1574,7 +1583,7 @@ The extension adds the following new command flag: - `NBD_CMD_FLAG_REQ_ONE`; valid during `NBD_CMD_BLOCK_STATUS`. SHOULD be set to 1 if the client wants to request information for only - one extent per allocation context. + one extent per metadata context. ## About this file