File.h

/*
 * Copyright (c) 2008-2014, Pedigree Developers
 *
 * Please see the CONTRIB file in the root of the source tree for a full
 * list of contributors.
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */
 
#ifndef FILE_H
#define FILE_H
#include "pedigree/kernel/LockGuard.h"
#include "pedigree/kernel/compiler.h"
#include "pedigree/kernel/process/Event.h"
#include "pedigree/kernel/process/Mutex.h"
#include "pedigree/kernel/process/OperationBarrier.h"
#include "pedigree/kernel/process/Readiness.h"
#include "pedigree/kernel/processor/types.h"
#include "pedigree/kernel/time/Time.h"
#include "pedigree/kernel/utilities/Cache.h"
#include "pedigree/kernel/utilities/CacheConstants.h"
#include "pedigree/kernel/utilities/HashTable.h"
#include "pedigree/kernel/utilities/List.h"
#include "pedigree/kernel/utilities/Pointers.h"
#include "pedigree/kernel/utilities/StaticString.h"
#include "pedigree/kernel/utilities/String.h"
#include "pedigree/kernel/utilities/new"
 
#include <config.h>
 
#include "ExtendedAttributes.h"
#include "FileEvent.h"
#include "FileHandle.h"
 
class Filesystem;
class Thread;
 
// RWX for owner.
#define FILE_UR 0001
#define FILE_UW 0002
#define FILE_UX 0004
#define FILE_UMASK 0007
#define FILE_UBITS 0
// RWX for group.
#define FILE_GR 0010
#define FILE_GW 0020
#define FILE_GX 0040
#define FILE_GMASK 0070
#define FILE_GBITS 3
// RWX for others.
#define FILE_OR 0100
#define FILE_OW 0200
#define FILE_OX 0400
#define FILE_OMASK 0700
#define FILE_OBITS 6
// Ancillary file bits.
#define FILE_STICKY 01000
#define FILE_AMASK 07000
#define FILE_ABITS 9
 
#define FILE_BAD_BLOCK static_cast<uintptr_t>(-1)
 
class EXPORTED_PUBLIC File : public ReadinessSource, public FileEventSource {
  friend class Filesystem;
  friend class Directory;
#if defined(PEDIGREE_BUILDUTILS)
  friend class Ext2FillCacheTestPeer;
  friend class Ext2WritebackTestPeer;
#endif
 
 public:
  class ParentLease {
   public:
    ParentLease();
    ~ParentLease();
    File* get() const {
      return m_Parent;
    }
    void swap(ParentLease& other);
 
   private:
    friend class File;
    NOT_COPYABLE_OR_ASSIGNABLE(ParentLease);
    File* m_Parent;
    bool m_Retained;
#if THREADS && !defined(STANDALONE_MUTEXES)
    TerminationDeferral m_TerminationDeferral;
#endif
  };
 
  class WriteGuard {
   public:
    ~WriteGuard();
 
    uint64_t write(uint64_t location, uint64_t size, uintptr_t buffer, bool bCanBlock = true,
                   bool publishMetadata = true);
    uint64_t append(uint64_t size, uintptr_t buffer, uint64_t& location, bool bCanBlock = true,
                    bool publishMetadata = true);
 
   private:
    friend class File;
 
    explicit WriteGuard(File& file);
 
    File& m_File;
    LockGuard<Mutex> m_Guard;
    bool m_MetadataPending = false;
  };
 
  File();
 
 private:
  File(const File& file);
  File& operator=(const File&);
 
 public:
  File(const String& name, Time::Timestamp accessedTime, Time::Timestamp modifiedTime,
       Time::Timestamp creationTime, uintptr_t inode, class Filesystem* pFs, size_t size,
       File* pParent);
  virtual ~File();
 
  virtual uint64_t read(uint64_t location, uint64_t size, uintptr_t buffer,
                        bool bCanBlock = true) final;
  size_t readCached(uint64_t location, size_t size, uintptr_t buffer,
                    bool (*prepare)(uintptr_t, size_t) = nullptr);
  virtual uint64_t write(uint64_t location, uint64_t size, uintptr_t buffer,
                         bool bCanBlock = true) final;
 
  uint64_t append(uint64_t size, uintptr_t buffer, uint64_t& location, bool bCanBlock = true);
 
  WriteGuard lockWrites();
 
  virtual physical_uintptr_t getPhysicalPage(size_t offset);
  virtual bool isDirectPhysicalMapping() const {
    return false;
  }
  size_t physicalMappingFlags() const {
    return m_PhysicalMappingFlags;
  }
 
  virtual void returnPhysicalPage(size_t offset);
  virtual bool tryBeginMappingRelease();
  void endMappingRelease();
 
  bool syncAndReturnPhysicalPage(size_t offset, bool async);
 
  virtual bool sync();
 
  bool syncRange(size_t offset, size_t length);
 
  virtual bool sync(size_t offset, bool async);
 
  virtual bool syncPages(const uint64_t* offsets, size_t count);
 
  Time::Timestamp getCreationTime();
  void setCreationTime(Time::Timestamp t);
 
  Time::Timestamp getAccessedTime();
  void setAccessedTime(Time::Timestamp t);
 
  Time::Timestamp getModifiedTime();
  void setModifiedTime(Time::Timestamp t);
 
  void setTimes(Time::Timestamp accessed, Time::Timestamp modified, bool changeAccessed,
                bool changeModified);
 
  struct Attributes {
    Time::Timestamp accessed = 0;
    Time::Timestamp modified = 0;
    Time::Timestamp changed = 0;
    size_t uid = 0;
    size_t gid = 0;
    uint32_t permissions = 0;
    size_t size = 0;
    size_t links = 1;
    uint64_t blocks = 0;
    // Filesystems with mutable storage identifiers may supply a stable public inode.
    uint64_t inode = 0;
  };
 
  enum AttributeMask : uint32_t {
    AccessTime = 1U << 0,
    ModifyTime = 1U << 1,
    ChangeTime = 1U << 2,
    Owner = 1U << 3,
    Group = 1U << 4,
    Permissions = 1U << 5
  };
 
  virtual Attributes getAttributes() const;
 
  virtual XattrStatus getExtendedAttribute(const StringView& name, void* buffer, size_t capacity,
                                           size_t& required);
  virtual XattrStatus listExtendedAttributes(void* buffer, size_t capacity, size_t& required);
  virtual XattrStatus setExtendedAttribute(const StringView& name, const void* value, size_t length,
                                           unsigned flags);
  virtual XattrStatus removeExtendedAttribute(const StringView& name);
 
  virtual bool prepareSharedMapping(size_t offset, size_t length);
 
  String getName() const;
  void getName(String& s) const;
 
  virtual void getFullPath(String& result, bool bWithMount = true);
 
  virtual String getFullPath(bool bWithMount = true);
 
  virtual void truncate();
 
  bool resize(size_t size);
 
  struct ShrinkContext {
    size_t oldSize;
    size_t newSize;
    const Cache::DiscardReference* mappingLoans;
    size_t mappingLoanCount;
  };
 
  class PreparedShrink {
   public:
    virtual ~PreparedShrink() = default;
    virtual void commit() = 0;
  };
 
  virtual size_t getSize();
  void setSize(size_t sz);
 
  virtual bool isSymlink();
 
  virtual bool isDirectory();
  virtual bool isBlockDevice() const {
    return false;
  }
  virtual uint64_t deviceNumber() const {
    return 0;
  }
 
  virtual bool isPipe() const;
 
  virtual bool isFifo() const;
 
  virtual bool isSocket() const;
 
  virtual bool isSeekable() const;
 
  bool supportsRegularFileOperations();
  virtual bool isCharacterDevice() const {
    return false;
  }
  virtual bool isConsole() const {
    return false;
  }
 
  virtual uint64_t maximumFileSize() const;
 
  virtual bool allowMapping(bool shared, bool writeRequested, bool& mayWrite);
 
  bool acquireMappingUse(bool executable, bool sharedWrite);
  void releaseMappingUse(bool executable, bool sharedWrite);
 
  uintptr_t getInode() const;
  virtual void setInode(uintptr_t inode);
 
  virtual uintptr_t futexIdentity();
 
  Filesystem* getFilesystem() const;
  void setFilesystem(Filesystem* pFs);
 
  virtual void fileAttributeChanged();
 
  void publishEvent(FileEventMask mask, const StringView& name = StringView(),
                    bool targetIsDirectory = false);
 
  virtual FileHandleStatus subscribeInodeEvents(FileEventMask mask,
                                                const SharedPointer<FileEventObserver>& observer,
                                                FileEventSubscription& subscription);
  virtual void finishInodeRetirement();
 
  virtual void increaseRefCount(bool bIsWriter);
  virtual void decreaseRefCount(bool bIsWriter);
 
  virtual bool retainVfsReference();
 
  virtual void releaseVfsReference();
 
  virtual bool isStableVfsRoot() const;
 
  void setPermissions(uint32_t perms);
  uint32_t getPermissions() const;
 
  bool setOwnership(size_t uid, size_t gid, bool changeUid, bool changeGid);
  void setUid(size_t uid);
  size_t getUid() const;
 
  void setGid(size_t gid);
  size_t getGid() const;
 
  File* getParent() const;
 
  void getNamespace(ParentLease& parent, String& name) const;
 
  virtual int select(bool bWriting = false, int timeout = 0);
 
  virtual ReadyMask queryReady(bool reading, bool writing);
 
  virtual bool supportsReadinessNotifications() const;
 
  void monitor(Thread* pThread, Event* pEvent);
 
  void cullMonitorTargets(Thread* pThread);
 
  void cullMonitorTargets(Event* pEvent);
 
  virtual bool supports(const size_t command) const;
 
  virtual int command(const size_t command, void* buffer);
 
  virtual size_t getBlockSize() const;
 
  void markPageExternallyWritable(size_t offset);
 
  static constexpr size_t MaxReadPages = 32;
  size_t populateRange(size_t offset, size_t length);
 
  void enableDirect();
 
  void disableDirect();
 
  virtual void preallocate(size_t expectedSize, bool zero = true);
 
  bool allocateRange(size_t offset, size_t length, bool keepSize = false);
 
  virtual File* open();
 
  virtual File* openForDescriptor(RetainedFile& owner);
 
 protected:
  bool tryAcquireFilesystemOperation(OperationBarrier::Lease& operation) const;
  virtual void updateAttributes(const Attributes& attributes, uint32_t mask);
  virtual bool changeOwnership(size_t uid, size_t gid, bool changeUid, bool changeGid);
  virtual bool allowPhysicalPage() const {
    return true;
  }
  virtual bool prepareWrite(uint64_t location, uint64_t size);
  virtual bool allowResize(size_t oldSize, size_t newSize);
  virtual bool prepareShrink(const ShrinkContext& context, UniquePointer<PreparedShrink>& prepared);
  virtual bool resizeFile(size_t size);
  virtual bool allocateFileRange(size_t offset, size_t length);
  virtual Mutex& writeSerializationLock();
  virtual Mutex& dataMutationLock();
  virtual size_t& physicalPageLoans();
  bool clearDataCache();
  virtual bool isBytewise() const;
 
  virtual uint64_t readBytewise(uint64_t location, uint64_t size, uintptr_t buffer,
                                bool bCanBlock = true);
  virtual uint64_t writeBytewise(uint64_t location, uint64_t size, uintptr_t buffer,
                                 bool bCanBlock = true);
 
  virtual uintptr_t readBlock(uint64_t location);
  virtual bool readPage(uint64_t location, uintptr_t destination);
  struct ReadPage {
    uint64_t offset;
    uintptr_t buffer;
    bool complete;
  };
  virtual bool readPages(ReadPage* pages, size_t count);
 
  virtual void writeBlock(uint64_t location, uintptr_t addr);
 
  virtual void writeBlocks(uint64_t location, uintptr_t addr, size_t length);
 
  virtual void extend(size_t newSize);
 
  virtual void extend(size_t newSize, uint64_t location, uint64_t size);
 
  virtual void publishInodeEvent(const FileEvent& event);
 
  void dataChanged();
 
  void getFilesystemLabel(HugeStaticString& s);
 
  static bool writeCallback(CacheConstants::CallbackCause cause, uintptr_t loc, uintptr_t page,
                            void* meta);
 
  static bool fillCacheCallback(CacheConstants::CallbackCause cause, uintptr_t loc, uintptr_t page,
                                void* meta);
 
  void enableFillCacheWriteback();
  void shutdownFillCacheWriteback();
 
  bool syncFillCache(size_t offset, bool async, bool& present);
 
  virtual bool useFillCache() const;
 
  MUST_USE_RESULT virtual bool pinBlock(uint64_t location);
 
  MUST_USE_RESULT virtual uintptr_t acquireCachedBlock(uint64_t location, bool retryChanged);
 
  virtual void unpinBlock(uint64_t location);
 
  void evict(uint64_t location);
 
  void setPermissionsOnly(uint32_t perms);
 
  void setUidOnly(size_t uid);
 
  void setGidOnly(size_t gid);
 
  void retainDetachedParent();
 
  void moveNamespace(const String& name, File* parent);
 
  bool snapshotNamespace(ParentLease& parent, String& name, FileEventMask interest) const;
 
  String m_Name;
  Time::Timestamp m_AccessedTime;
  Time::Timestamp m_ModifiedTime;
  Time::Timestamp m_CreationTime;
  uintptr_t m_Inode;
  uintptr_t m_FutexIdentity = 0;
 
  class Filesystem* m_pFilesystem;
  size_t m_Size;
 
  File* m_pParent;
  mutable Mutex m_MetadataLock;
 
  File* m_pDetachedParent;
  bool m_bDetachedParentHandled;
 
  size_t m_nWriters, m_nReaders;
 
  size_t m_Uid;
  size_t m_Gid;
  uint32_t m_Permissions;
 
 public:
  class DataCacheKey {
   public:
    DataCacheKey() = default;
    DataCacheKey(size_t block) : m_Block(block) {}
    ~DataCacheKey() = default;
 
    size_t hash() const {
      return m_Block;
    }
 
    bool operator==(const DataCacheKey& other) const {
      return m_Block == other.m_Block;
    }
 
   private:
    size_t m_Block = ~static_cast<size_t>(0);
  };
 
  struct CacheState {
    CacheState();
    HashTable<DataCacheKey, uintptr_t> data;
    Mutex indexLock;
    Cache fill;
    Mutex fillLock;
    // Aliases share these counts and serialize admission with data mutation.
    size_t executableMappings = 0;
    size_t sharedWriteMappings = 0;
  };
 
 protected:
  virtual CacheState& cacheState();
  CacheState m_CacheState;
 
  bool m_bDirect;
#if defined(PEDIGREE_BUILDUTILS)
  bool m_bForceFillCache = false;
#endif
 
  Mutex m_WriteLock;
  Mutex m_DataMutationLock;
  size_t m_PhysicalPageLoans = 0;
  size_t m_PhysicalMappingFlags = 0;
 
  void setPhysicalMappingFlags(size_t flags) {
    m_PhysicalMappingFlags = flags;
  }
 
  Mutex m_Lock;
 
  struct MonitorTarget {
    MonitorTarget(Thread* pT, Event* pE, Event::SendLease registration)
        : pThread(pT), pEvent(pE), eventRegistration(pedigree_std::move(registration)) {}
    Thread* pThread;
    Event* pEvent;
    Event::SendLease eventRegistration;
  };
 
  List<MonitorTarget*> m_MonitorTargets;
 
 private:
  void publishWriteMetadata();
 
  uint64_t writeUnlocked(uint64_t location, uint64_t size, uintptr_t buffer, bool bCanBlock);
 
  uintptr_t getCachedPage(size_t block, bool locked = true);
 
  void setCachedPage(size_t block, uintptr_t value, bool locked = true);
 
  uintptr_t readIntoCache(uintptr_t block, bool overwriteWholePage = false,
                          size_t readAheadBytes = 0);
  size_t populateRangeLocked(size_t offset, size_t length);
 
  void releaseReadReference(uintptr_t block);
};
 
#endif