Checkpoint Sketch
=================
					NILFS team NTT

NILFS v1 supports file system snapshot.  All checkpoints act as file
system root, so you can mount any of them as a read-only file system.
However, there are numerous number of checkpoint in one file system,
it is hard to select desire version of checkpoint.  So, we want tags
or labels to each checkpoints as hint.  NILFS `checkpoint sketch'
provides data area and interfaces to store such informations.

NILFS v1 partial segment (write out unit) format is as follows.

 [segment summary]
    [data blocks]
       [data B-Tree]
          [inode blocks]
             [inode B-Tree]
                [checkpoint]

The checkpoint includes a checksum of the checkpoint itself. The
checkpoint accuracy means successfully writing the partial segment to
the disk.  The most important information in the checkpoint is the
root block number of the inode block B-tree.  The block number is
written out last, and the whole file system state is updated.

The size of the checkpoint is one block, on the other hand,
sizeof(struct nilfs_checkpoint) is only 44 bytes (NILFS 1.0.6).
There are 4052 bytes remains after valid checkpoint data typically.

The checkpoint sketch is an interface to using the unused area.
You can store any data as sketch of the segment.

There are two special files for NILFS checkpoint sketch.

Sysfs file shows maximum size of sketch file in bytes.
(See file tuning.txt)

	/sys/block/<drive>/nilfs/max_sketch_size

Another is readable/writeable file for accessing the sketch.

	<mountpoint>/.sketch 

Typical usage is as follows.

1. fetch maximum size information from sysfs file.
2. open .sketch in write mode.
3. write data.  size must be smaller or equal to max size.
   writing may repeat.
4. close the stream. 

The data will be stored the disk with next partial segment.
After storing the data, NILFS truncates .sketch file to empty.

You can use NILFS inspect tool to pull out sketch data in
any checkpoint.  The listcp sub command shows checkpoint number
and sketch size.  Then, "inspect -s number dev" writes the
specified sketch to stdout. If "-o filename" option is specified
with -s, data will stored the file.

The .sketch file on read-only mounted snapshot filesystem (mounted
with option -o ro,cp=number) presents sketch data of number checkpoint.

The .sketch file is not immutable, so, you can rename or change mode
of .sketch file.  If .sketch file was deleted, accessibility to
checkpoint sketch will be lost.  We plan to provide some tool.

We will use checkpoint sketch as memorandum of file status.  The
listcp sub command of NILFS inspect tools shows checkpoint create date
and time, it is the minimum information for selecting checkpoint that
includes desired version of files.  The sketch provides additional
information related to checkpoint.

*** sketch data format
A proposal for sketch data format.

A sketch contains several format data.
Each data consists of header and body.
Header is represented by ASCII printable characters, 
  case sensitive.
First character of the header shows header format,
  format '!' to format '~' in ASCII code order.
All headers must have body length (without header) field.

Header Format '!':
  Header length is 6 character (fixed).
  Second character describes body content type.
  3rd-6th characters describe body length in bytes.
    There are 4 digits decimal (0-9)
  Content types are as follows (tentative):
    'T' text
    'J' jpeg
    'G' gif
    'P' PNG
    'H' HTML
    'X' XML
    'U' URI
    'W' Wiki syntax
    'A' audio?
    'E' Executable (? Request for discussion)
    ...
    'O' other

Header Format '"':
  to be appeared.

================================================================
nilfs@osrg.net

---
sketch.txt,v 1.9 2006/02/15 06:06:37 amagai Exp
