Object.h

Go to the documentation of this file.

#pragma once

#include "TimeStamp.h"
#include "FileAttributes.h"
#include "Compression.h"
#include "UserRole.h"

namespace IFS
{
/*
 * Helper template function to get the next object pointer at (current + offset)
 * casting as required for the given return type.
 */
template <typename T> static T at_offset(const void* current, int offset)
{
    auto p = reinterpret_cast<const uint8_t*>(current) + offset;
    return reinterpret_cast<T>(p);
}

template <typename T> static T at_offset(void* current, int offset)
{
    auto p = reinterpret_cast<uint8_t*>(current) + offset;
    return reinterpret_cast<T>(p);
}

// Images start with a single word to identify this as a Firmware Filesystem image
#define FWFILESYS_START_MARKER 0x53465746 // "FWFS"

// Image end marker (reverse of magic)
#define FWFILESYS_END_MARKER 0x46574653 // "SFWF"

// Everything in this header must be portable (at least, with other little-endian systems) so byte-align and pack it
#pragma pack(1)

#define FWFS_OBJTYPE_MAP(XX)                                                                                           \
    XX(0, End, "The system image footer")                                                                              \
    XX(1, Data8, "Data, max 255 bytes")                                                                                \
    XX(2, ID32, "32-bit identifier")                                                                                   \
    XX(3, ObjAttr, "Object attributes")                                                                                \
    XX(4, Compression, "Compression descriptor")                                                                       \
    XX(5, ReadACE, "minimum UserRole for read access")                                                                 \
    XX(6, WriteACE, "minimum UserRole for write access")                                                               \
    XX(7, ObjectStore, "Identifier for object store")                                                                  \
    XX(8, Md5Hash, "MD5 Hash Value")                                                                                   \
    XX(32, Data16, "Data, max 64K - 1")                                                                                \
    XX(33, Volume, "Volume, top-level container object")                                                               \
    XX(34, MountPoint, "Root for another filesystem")                                                                  \
    XX(35, Directory, "Directory entry")                                                                               \
    XX(36, File, "File entry")                                                                                         \
    XX(64, Data24, "Data, max 16M - 1")

struct Object {
    uint8_t typeData; 

    using ID = uint16_t;

    enum class Type {
#define XX(value, tag, text) tag = value,
        FWFS_OBJTYPE_MAP(XX)
#undef XX
    };

    // Top bit of object type set to indicate a reference
    static constexpr uint8_t FWOBT_REF{0x80};

    enum class Attribute {
        ReadOnly,
        Archive,
        //
        MAX
    };

    using Attributes = BitSet<uint8_t, Attribute, size_t(Attribute::MAX)>;

    Type type() const
    {
        return static_cast<Type>(typeData & 0x7f);
    }

    bool isRef() const
    {
        return (typeData & FWOBT_REF) != 0;
    }

    bool isNamed() const
    {
        return type() >= Type::Volume && type() < Type::Data24;
    }

    bool isData() const
    {
        return type() == Type::Data8 || type() == Type::Data16 || type() == Type::Data24;
    }

    bool isDir() const
    {
        return type() == Type::Directory;
    }

    bool isMountPoint() const
    {
        return type() == Type::MountPoint;
    }

    union {
        // Data8 - 8-bit size, max. 255 bytes
        struct {
            uint8_t _contentSize;
            // uint8_t data[];

            unsigned contentOffset() const
            {
                return offsetof(Object, data8) + 1;
            }

            unsigned contentSize() const
            {
                return _contentSize;
            }

            union {
                // An object reference: the contents are stored externally (on the same volume)
                struct {
                    ID id;
                } ref;

                // ID32
                struct {
                    uint32_t value; 
                } id32;

                // Object attributes
                struct {
                    uint8_t attr; // Attributes
                } objectAttributes;

                // Compression descriptor
                struct {
                    Compression::Type type;
                    uint32_t originalSize;
                } compression;

                // ReadACE, WriteACE
                struct {
                    UserRole role;
                } ace;

                // Identifies an object store, contained in a mount point
                struct {
                    uint8_t storenum;
                } objectStore;

                // END - immediately followed by end marker
                struct {
                    uint32_t checksum;
                } end;
            };
        } data8;

        // Data16 - 16-bit size, max. (64KB - 1)
        struct {
            uint16_t _contentSize;
            // uint8_t data[];

            unsigned contentOffset() const
            {
                return offsetof(Object, data16) + 2;
            }

            uint32_t contentSize() const
            {
                return _contentSize;
            }

            uint32_t size() const
            {
                return contentOffset() + contentSize();
            }

            union {
                /*
                 * named object
                 *
                 * child objects can be contained or referenced (flag in _id)
                 * object attributes are optional so can be another object/attribute
                 * objects are word aligned
                 */
                struct {
                    uint8_t namelen; 
                    TimeStamp mtime; // Object modification time
                    // char name[namelen];
                    // Object children[];   // __aligned

                    // Offset to object name relative to content start
                    unsigned nameOffset() const
                    {
                        return sizeof(Object::data16.named);
                    }

                    // Offset to start of child object table
                    unsigned childTableOffset() const
                    {
                        return nameOffset() + ALIGNUP4(namelen);
                    }

                } named;
            };
        } data16;

        // Data24 - 24-bit size, max. (16MB - 1)
        struct {
            uint16_t _contentSize;  
            uint8_t _contentSizeHigh; 
            // uint8_t data[];

            size_t contentOffset() const
            {
                return offsetof(Object, data24) + 3;
            }

            uint32_t contentSize() const
            {
                return (_contentSizeHigh << 16) | _contentSize;
            }

            void setContentSize(uint32_t value)
            {
                _contentSize = value & 0xffff;
                _contentSizeHigh = value >> 16;
            }

            uint32_t size() const
            {
                return contentOffset() + contentSize();
            }
        } data24;
    };

    size_t contentOffset() const
    {
        if(isRef() || (type() < Type::Data16)) {
            return data8.contentOffset();
        } else if(type() < Type::Data24) {
            return data16.contentOffset();
        } else {
            return data24.contentOffset();
        }
    }

    uint32_t contentSize() const
    {
        if(isRef() || (type() < Type::Data16)) {
            return data8.contentSize();
        } else if(type() < Type::Data24) {
            return data16.contentSize();
        } else {
            return data24.contentSize();
        }
    }

    uint32_t childTableOffset() const
    {
        assert(isNamed());
        return data16.contentOffset() + data16.named.childTableOffset();
    }

    uint32_t childTableSize() const
    {
        assert(isNamed());
        return data16.contentSize() - data16.named.childTableOffset();
    }

    uint32_t size() const
    {
        return contentOffset() + contentSize();
    }

    uint32_t sizeAligned() const
    {
        return ALIGNUP4(size());
    }
};

static_assert(sizeof(Object) == 8, "Object alignment wrong!");

#pragma pack()

} // namespace IFS

String toString(IFS::Object::Type obt);