github.com/SagerNet/gvisor@v0.0.0-20210707092255-7731c139d75c/pkg/sentry/fsimpl/ext/disklayout/disklayout.go (about)

     1  // Copyright 2019 The gVisor Authors.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  // Package disklayout provides Linux ext file system's disk level structures
    16  // which can be directly read into from the underlying device. Structs aim to
    17  // emulate structures `exactly` how they are layed out on disk.
    18  //
    19  // This library aims to be compatible with all ext(2/3/4) systems so it
    20  // provides a generic interface for all major structures and various
    21  // implementations (for different versions). The user code is responsible for
    22  // using appropriate implementations based on the underlying device.
    23  //
    24  // Interfacing all major structures here serves a few purposes:
    25  //   - Abstracts away the complexity of the underlying structure from client
    26  //     code. The client only has to figure out versioning on set up and then
    27  //     can use these as black boxes and pass it higher up the stack.
    28  //   - Having pointer receivers forces the user to use pointers to these
    29  //     heavy structs. Hence, prevents the client code from unintentionally
    30  //     copying these by value while passing the interface around.
    31  //   - Version-based implementation selection is resolved on set up hence
    32  //     avoiding per call overhead of choosing implementation.
    33  //   - All interface methods are pretty light weight (do not take in any
    34  //     parameters by design). Passing pointer arguments to interface methods
    35  //     can lead to heap allocation as the compiler won't be able to perform
    36  //     escape analysis on an unknown implementation at compile time.
    37  //
    38  // Notes:
    39  //   - All structures on disk are in little-endian order. Only jbd2 (journal)
    40  //     structures are in big-endian order.
    41  //   - All OS dependent fields in these structures will be interpretted using
    42  //     the Linux version of that field.
    43  //   - The suffix `Lo` in field names stands for lower bits of that field.
    44  //   - The suffix `Hi` in field names stands for upper bits of that field.
    45  //   - The suffix `Raw` has been added to indicate that the field is not split
    46  //     into Lo and Hi fields and also to resolve name collision with the
    47  //     respective interface.
    48  package disklayout