Welcome to the Reiser4 Wiki, the Wiki for users and developers of the ReiserFS and Reiser4 filesystems.

For now, most of the documentation is just a snapshot of the old Namesys site (archive.org, 2007-09-29).

There was also a Reiser4 Wiki (archive.org, 2007-07-06) once on pub.namesys.com.

Reiser4 development model

From Reiser4 FS Wiki
(Difference between revisions)
Jump to: navigation, search
(Added section "Why to track compatibility?")
m
 
(8 intermediate revisions by one user not shown)
Line 1: Line 1:
                1. Why to track compatibility?
+
= Why worry about compatibility? =
  
  
 
Reiser4 is in permanent development. New plugins managing new disk
 
Reiser4 is in permanent development. New plugins managing new disk
objects are added systematically. And the common problem is that old
+
objects get added systematically. And the common problem is that old
 
software is unaware of new objects. The biggest concern is old fsck
 
software is unaware of new objects. The biggest concern is old fsck
 
utilities, which treat the new "unknown" objects as corruption.
 
utilities, which treat the new "unknown" objects as corruption.
Line 9: Line 9:
 
objects for old software.
 
objects for old software.
  
 +
= Reiser4 development policy =
  
                2. Reiser4 development policy
 
  
 
+
Here we discuss things needed to keep a track of compatibility.
Here we discuss things needed to keep a track of compatibility,
+
Software upgrades, which are fully backward and forward compatible
so we don't consider upgrades, which are fully backward and forward
+
(like adding discard/TRIM support) is not a concern.
compatible (like adding discard/TRIM support).
+
  
 
Other upgrades of reiser4 kernel module (reiser4progs) always look
 
Other upgrades of reiser4 kernel module (reiser4progs) always look
Line 26: Line 25:
 
kernel module and reiser4progs.
 
kernel module and reiser4progs.
  
 +
= Software Framework Release Numbers =
  
                3. Software Format Release Numbers
 
  
 
+
Any reiser4 kernel module (reiser4progs package) has a software framework
Any reiser4 kernel module (reiser4progs package) has a software format
+
 
release number (SFRN) 4.X.Y, where X and Y are major and minor SFRN
 
release number (SFRN) 4.X.Y, where X and Y are major and minor SFRN
 
respectively.
 
respectively.
Line 53: Line 51:
  
  
                4. Compatibility of software upgrades
+
= Compatibility of software upgrades =
  
  
Line 72: Line 70:
  
  
                5. Disk format version numbers
+
= Disk format version numbers =
  
  
Line 78: Line 76:
 
where A and B are respectively major and minor DFVN.
 
where A and B are respectively major and minor DFVN.
  
Major DFVN is defined as the serial number of disk format plugin
+
Major DFVN is defined as disk format plugin id specified when formatting
specified when formatting the partition. Major DFVN never changes.
+
the partition. Major DFVN never changes.
  
Minor DFVN is defined as the minimal version of the plugin library
+
Minor DFVN is defined as the minimal SFRN of reiser4 kernel module (and
fully compatible with this partition. Initially every partition gets
+
reiser4progs), which is fully compatible with this partition. Initially
minor DFVN equal to minor SFRN of the mkfs.reiser4 utility when
+
every partition gets minor DFVN equal to minor SFRN of the mkfs.reiser4
formatting the partition. Further minor DFVN can be upgraded.
+
utility when formatting the partition. Further minor DFVN can be upgraded.
  
 
Any partition 4.A.B can be correctly handled only by reiser4progs 4.U.V,
 
Any partition 4.A.B can be correctly handled only by reiser4progs 4.U.V,
Line 114: Line 112:
 
"reiser4: found disk format 4.A.B"). DFVN is also reported by
 
"reiser4: found disk format 4.A.B"). DFVN is also reported by
 
debugfs.reiser4 utility in default mode.
 
debugfs.reiser4 utility in default mode.
 +
 +
[[category:Reiser4]]

Latest revision as of 12:51, 28 September 2017

Contents

[edit] Why worry about compatibility?

Reiser4 is in permanent development. New plugins managing new disk objects get added systematically. And the common problem is that old software is unaware of new objects. The biggest concern is old fsck utilities, which treat the new "unknown" objects as corruption. So we need a mechanism to restrict, or even prevent access to new objects for old software.

[edit] Reiser4 development policy

Here we discuss things needed to keep a track of compatibility. Software upgrades, which are fully backward and forward compatible (like adding discard/TRIM support) is not a concern.

Other upgrades of reiser4 kernel module (reiser4progs) always look like adding a plugin or a set of plugins of existing, or new interfaces. Hence, such upgrades are always backward compatible.

With every such upgrade developer has to increment plugin library version number of both, reiser4 kernel module and reiser4progs. See definition of the macro PLUGIN_LIBRARY_VERSION in reiser4 kernel module and reiser4progs.

[edit] Software Framework Release Numbers

Any reiser4 kernel module (reiser4progs package) has a software framework release number (SFRN) 4.X.Y, where X and Y are major and minor SFRN respectively.

Major SFRN of reiser4 module (reiser4progs) is defined as the maximal serial number of supported disk format plugin (see definition of the struct disk_format_plugin).

Minor SFRN of reiser4 module (reiser4progs) is defined as version number of the plugin library.

SFRN of reiser4 kernel module is reported by kernel (look for the string "Loading Reiser4 (format release: 4.X.Y)" in kernel messages.

SFRN of reiser4progs is reported by every utility provided by this package when specifying option -V (Look for the string "Format release 4.X.Y").

Don't confuse SFRN and the version number of reiser4progs package! The last one takes into account all software changes (including fully compatible ones).


[edit] Compatibility of software upgrades

Every upgrade of reiser4 kernel module and reiser4progs performed in accordance with the development model (section 1) is automatically backward compatible.

Every upgrade of reiser4progs SFRN is forward incompatible. That is, reiser4progs will refuse to with any partition with greater DFVN. This is for more reliability: fsck treats any "unknown" objects as a corruption.

"Major" upgrades of reiser4 kernel module (4.X.Y) -> (4.X+1.Y) are fully forward incompatible.

"Minor" upgrades of reiser4 kernel module (4.X.Y) -> (4.X.Y+1) are partially forward compatible.


[edit] Disk format version numbers

Any reiser4 partition has a disk format versions number (DFVN) 4.A.B, where A and B are respectively major and minor DFVN.

Major DFVN is defined as disk format plugin id specified when formatting the partition. Major DFVN never changes.

Minor DFVN is defined as the minimal SFRN of reiser4 kernel module (and reiser4progs), which is fully compatible with this partition. Initially every partition gets minor DFVN equal to minor SFRN of the mkfs.reiser4 utility when formatting the partition. Further minor DFVN can be upgraded.

Any partition 4.A.B can be correctly handled only by reiser4progs 4.U.V, where A <= U and B <= V. Otherwise, reiser4progs will refuse to work with such partition (user will be suggested to upgrade reiser4progs).

Any partition 4.A.B can be fully mounted only by kernel module 4.U.B, where A <= U.

If A > U, then mount will fail with a kernel warning about forward incompatibility and a suggestion to upgrade the kernel.

When mounting a partition 4.A.B by kernel module 4.U.V, where A <= U, B != V, then 2 scenarios are possible:

If B > V, then mount will succeed, but kernel will warn about partial forward compatibility (it means that not all disk objects will be accessible in that mount session).

If B < V, then mount will succeed. Kernel will upgrade DFVN in the primary superblock with the suggestion to upgrade DFVN in the superblock replicas (backup blocks) by running fsck.reiser4 --fix.

DFVN can be fully upgraded by any reiser4.fsck utility of proper SFRN. Reiser4 kernel module upgrades DFVN only in the primary superblock. Downgrades of DFVN are not supported/planned.

DFVN is reported by kernel at mount time (look for the string: "reiser4: found disk format 4.A.B"). DFVN is also reported by debugfs.reiser4 utility in default mode.

Personal tools