@k13engineering/linux-dmabuf 0.0.2 → 0.0.3

package/dist/lib/cached-mapper.d.ts

@@ -0,0 +1,12 @@
+import type { TMemoryMappedBuffer } from "@k13engineering/po6-mmap";
+type TRefcountedBufferMapping = Uint8Array & {
+    release: () => void;
+};
+declare const createCachedMapper: ({ map, }: {
+    map: () => TMemoryMappedBuffer;
+}) => {
+    maybeMap: () => TRefcountedBufferMapping;
+    mapped: () => boolean;
+    close: () => void;
+};
+export { createCachedMapper };

package/dist/lib/cached-mapper.js

@@ -0,0 +1,74 @@
+/*import type { TMemoryMappedBuffer } from "@k13engineering/po6-mmap";*/
+
+/*type TRefcountedBufferMapping = Uint8Array & {
+  release: () => void;
+};*/
+
+const createCachedMapper = ({
+  map,
+}/*: {
+  map: () => TMemoryMappedBuffer;
+}*/) => {
+
+  let refcount = 0;
+  let mappedBuffer/*: TMemoryMappedBuffer | undefined*/ = undefined;
+
+  const maybeMap = ()/*: TRefcountedBufferMapping*/ => {
+    if (mappedBuffer === undefined) {
+      mappedBuffer = map();
+    }
+
+    refcount += 1;
+    let released = false;
+
+    // eslint-disable-next-line complexity
+    const release = () => {
+      if (released) {
+        throw Error("handle already released");
+      }
+
+      if (refcount <= 0) {
+        throw Error("BUG: release called when refcount is <= 0");
+      }
+
+      if (mappedBuffer === undefined) {
+        throw Error("BUG: release called but mappedBuffer is undefined");
+      }
+
+      refcount -= 1;
+
+      if (refcount === 0) {
+        mappedBuffer.unmap();
+        mappedBuffer = undefined;
+      }
+
+      released = true;
+    };
+
+    const bufferView = new Uint8Array(mappedBuffer.buffer, mappedBuffer.byteOffset, mappedBuffer.byteLength);
+    const cachedMappedBuffer = bufferView /*as TRefcountedBufferMapping*/;
+
+    // monkey-patch mappingId and release method
+    cachedMappedBuffer.release = release;
+
+    return cachedMappedBuffer;
+  };
+
+  const mapped = () => {
+    return mappedBuffer !== undefined;
+  };
+
+  const close = () => {
+
+  };
+
+  return {
+    maybeMap,
+    mapped,
+    close
+  };
+};
+
+export {
+  createCachedMapper
+};

package/dist/lib/dmabuf-handle.d.ts

@@ -0,0 +1,44 @@
+import { type TDmabufMapping, type TDmabufMappingAccess } from "./dmabuf-mapping.js";
+import type { TLinuxDmabufInterface } from "./linux-interface.js";
+type TDmabufInfo = {
+    inode: number;
+    size: number;
+};
+type TDmabufSync = {
+    end: () => void;
+};
+type TSyncReadOrWrite = {
+    read: true;
+    write: false;
+} | {
+    read: false;
+    write: true;
+} | {
+    read: true;
+    write: true;
+};
+type TDmabufHandle = {
+    exportAndDupAsDmabufFd: () => {
+        dmabufFd: number;
+    };
+    info: () => TDmabufInfo;
+    map: (args: {
+        iKnowWhatImDoing: boolean;
+        access: TDmabufMappingAccess;
+    }) => TDmabufMapping;
+    sync: (args: {
+        iKnowWhatImDoing: boolean;
+    } & TSyncReadOrWrite) => TDmabufSync;
+    close: () => void;
+};
+declare const createHandleImporter: ({ linuxInterface }: {
+    linuxInterface: TLinuxDmabufInterface;
+}) => {
+    importAndDupDmabuf: ({ dmabufFd: providedDmabufFd }: {
+        dmabufFd: number;
+    }) => TDmabufHandle;
+};
+type THandleImporter = ReturnType<typeof createHandleImporter>;
+type TImportAndDupDmabufFunc = THandleImporter["importAndDupDmabuf"];
+export { createHandleImporter };
+export type { TDmabufHandle, TSyncReadOrWrite, TDmabufSync, TImportAndDupDmabufFunc };

package/dist/lib/dmabuf-handle.js

@@ -0,0 +1,282 @@
+
+import { /*type TMemoryProtectionFlags */} from "@k13engineering/po6-mmap";
+import { createMappingHelper, /*type TDmabufMapping, *//*type TDmabufMappingAccess */} from "./dmabuf-mapping.js";
+import { createDefaultGarbageCollectedWithoutReleaseError, createGarbageCollectionGuard } from "./snippets/gc-guard.js";
+/*import type { TLinuxDmabufInterface } from "./linux-interface.ts";*/
+
+/*type TDmabufInfo = {
+  inode: number;
+  size: number;
+};*/
+
+/*type TDmabufSync = {
+  end: () => void;
+};*/
+
+/*type TSyncReadOrWrite = {
+  read: true;
+  write: false;
+} | {
+  read: false;
+  write: true;
+} | {
+  read: true;
+  write: true;
+};*/
+
+/*type TDmabufHandleInfo = {
+  handleId: number;
+  inode: number;
+  size: number;
+};*/
+
+/*type TDmabufHandle = {
+  exportAndDupAsDmabufFd: () => { dmabufFd: number };
+  info: () => TDmabufInfo;
+  map: (args: { iKnowWhatImDoing: boolean, access: TDmabufMappingAccess }) => TDmabufMapping;
+  sync: (args: { iKnowWhatImDoing: boolean } & TSyncReadOrWrite) => TDmabufSync;
+  close: () => void;
+};*/
+
+const dmabufGarbageCollectionGuard = createGarbageCollectionGuard({
+  createError: ({ info }/*: { info: TDmabufHandleInfo }*/) => {
+    return createDefaultGarbageCollectedWithoutReleaseError({
+      name: "DmabufMappingGarbageCollectedWithoutReleaseError",
+      info: `dma buffer handle with handleId=${info.handleId} inode=${info.inode} size=${info.size}`,
+      releaseFunctionName: "release",
+      resourcesName: "dma buffer handles",
+    });
+  }
+});
+
+let handleIdCounter = 0;
+
+
+const createHandleImporter = ({
+  linuxInterface
+}/*: {
+  linuxInterface: TLinuxDmabufInterface
+}*/) => {
+
+
+  // eslint-disable-next-line max-statements
+  const importAndDupDmabuf = ({ dmabufFd: providedDmabufFd }/*: { dmabufFd: number }*/)/*: TDmabufHandle*/ => {
+
+    const assertIsADmaBuf = ({ dmabufFd }/*: { dmabufFd: number }*/)/*: void*/ => {
+      if (dmabufFd < 0) {
+        throw Error(`invalid dmabuf fd ${dmabufFd}`);
+      }
+
+      try {
+        linuxInterface.fstat({ fd: dmabufFd });
+      } catch (ex) {
+        throw Error(`invalid dmabuf fd ${dmabufFd}, fstat failed`, { cause: ex /*as Error*/ });
+      }
+
+      try {
+        linuxInterface.dmabufIoctlSyncStart({ dmabufFd, read: true, write: false });
+        linuxInterface.dmabufIoctlSyncEnd({ dmabufFd, read: true, write: false });
+      } catch (ex) {
+        throw Error(`fd ${dmabufFd} is not a valid dmabuf fd, ioctl check failed`, { cause: ex /*as Error*/ });
+      }
+    };
+
+    assertIsADmaBuf({ dmabufFd: providedDmabufFd });
+    const dmabufFd = linuxInterface.dup({ fd: providedDmabufFd });
+
+    let closed = false;
+
+    const st = linuxInterface.fstat({ fd: dmabufFd });
+    const inode = st.inode;
+
+    const assertNotClosed = () => {
+      if (closed) {
+        throw Error(`dmabuf handle already closed`);
+      }
+    };
+
+    const assertFdIsUnchanged = () => {
+      // try {
+      //   assertIsADmaBuf({ dmabufFd });
+      // } catch (e) {
+      //   let message = `internal dmabuf handle ${dmabufFd} (inode ${inode}) is no longer a valid dmabuf fd,`;
+      //   message += ` probably someone closed a wrong file descriptor`;
+      //   message += ` - your program is probably in an inconsistent state`;
+      //   throw Error(message, { cause: e as Error });
+      // }
+
+      const currentSt = linuxInterface.fstat({ fd: dmabufFd });
+      if (currentSt.inode !== inode) {
+        let message = `internal dmabuf handle ${dmabufFd} (inode ${inode}) fd's inode has changed to ${currentSt.inode},`;
+        message += ` probably someone closed a wrong file descriptor and the OS reused the fd for a different file`;
+        message += ` - your program is probably in an inconsistent state`;
+        throw Error(message);
+      }
+    };
+
+    const exportAndDupAsDmabufFd/*: TDmabufHandle["exportAndDupAsDmabufFd"]*/ = () => {
+      assertNotClosed();
+      assertFdIsUnchanged();
+
+      const newFd = linuxInterface.dup({ fd: dmabufFd });
+
+      return {
+        dmabufFd: newFd
+      };
+    };
+
+    const info/*: TDmabufHandle["info"]*/ = () => {
+      assertNotClosed();
+      assertFdIsUnchanged();
+
+      const stat = linuxInterface.fstat({ fd: dmabufFd });
+
+      const dmabufInfo/*: TDmabufInfo*/ = {
+        inode: stat.inode,
+        size: stat.size
+      };
+
+      return dmabufInfo;
+    };
+
+    // type TMapping = {
+    //   buffer: TMemoryMappedBuffer;
+    //   access: TMapAccess;
+    // };
+
+    const mapAsserted = ({ memoryProtectionFlags }/*: { memoryProtectionFlags: TMemoryProtectionFlags }*/) => {
+      const { size } = info();
+
+      const { errno, buffer } = linuxInterface.mmapFd({
+        fd: dmabufFd,
+        mappingVisibility: "MAP_SHARED",
+        memoryProtectionFlags,
+        genericFlags: {},
+        offsetInFd: 0,
+        length: size
+      });
+
+      if (errno !== undefined) {
+        throw Error(`dmabuf mmap failed with errno ${errno}`);
+      }
+
+      return buffer;
+    };
+
+    const mappingHelper = createMappingHelper({
+      mapAsserted
+    });
+
+    const map/*: TDmabufHandle["map"]*/ = ({ iKnowWhatImDoing, access }) => {
+      if (!iKnowWhatImDoing) {
+        let message = `mapping dmabufs is for internal or advanced usage only:`;
+        message += ` dmabuf accesses need proper synchronization;`;
+        message += ` accessing the mapped memory after close can cause program crashes or data corruption`;
+        message += ` if you really want to do this, please set iKnowWhatImDoing to true`;
+
+        throw Error(message);
+      }
+
+      assertNotClosed();
+      assertFdIsUnchanged();
+
+      const mapping = mappingHelper.map({ access });
+
+      return mapping;
+    };
+
+    let syncStarted = false;
+
+    const sync/*: TDmabufHandle["sync"]*/ = ({ iKnowWhatImDoing, read, write }) => {
+      if (!iKnowWhatImDoing) {
+        let message = `creating dmabuf sync is for internal or advanced usage only:`;
+        message += ` start / end calls must be properly paired;`;
+        message += ` if you really want to do this, please set iKnowWhatImDoing to true`;
+
+        throw Error(message);
+      }
+
+      assertNotClosed();
+      assertFdIsUnchanged();
+
+      if (syncStarted) {
+        throw Error(`dmabuf sync already started, make sure to call end() before starting a new sync`);
+      }
+
+      linuxInterface.dmabufIoctlSyncStart({ dmabufFd, read, write });
+      syncStarted = true;
+
+      let stale = false;
+
+      const end = () => {
+        assertNotClosed();
+        assertFdIsUnchanged();
+
+        if (stale) {
+          throw Error(`stale sync instance, end() already called`);
+        }
+
+        linuxInterface.dmabufIoctlSyncEnd({ dmabufFd, read: true, write: true });
+        syncStarted = false;
+        stale = true;
+      };
+
+      return {
+        end
+      };
+    };
+
+    const close/*: TDmabufHandle["close"]*/ = () => {
+      assertNotClosed();
+      assertFdIsUnchanged();
+
+      if (syncStarted) {
+        throw Error(`dmabuf sync started but not ended, please end sync before closing the handle`);
+      }
+
+      linuxInterface.close({ fd: dmabufFd });
+      closed = true;
+    };
+
+    const handleId = handleIdCounter;
+    handleIdCounter += 1;
+
+    const { release: protectedClose } = dmabufGarbageCollectionGuard.protect({
+      release: () => {
+        close();
+      },
+
+      info: {
+        handleId,
+        inode,
+        size: info().size
+      }
+    });
+
+    return {
+      exportAndDupAsDmabufFd,
+      info,
+      map,
+      sync,
+      close: protectedClose
+    };
+  };
+
+  return {
+    importAndDupDmabuf
+  };
+};
+
+/*type THandleImporter = ReturnType<typeof createHandleImporter>;*/
+/*type TImportAndDupDmabufFunc = THandleImporter["importAndDupDmabuf"];*/
+
+export {
+  createHandleImporter
+};
+
+/*export type {
+  TDmabufHandle,
+  TSyncReadOrWrite,
+  TDmabufSync,
+  TImportAndDupDmabufFunc
+};*/

package/dist/lib/dmabuf-ioctl.d.ts

@@ -0,0 +1,11 @@
+declare const dmabufIoctlSyncStart: ({ dmabufFd, read, write }: {
+    dmabufFd: number;
+    read: boolean;
+    write: boolean;
+}) => void;
+declare const dmabufIoctlSyncEnd: ({ dmabufFd, read, write }: {
+    dmabufFd: number;
+    read: boolean;
+    write: boolean;
+}) => void;
+export { dmabufIoctlSyncStart, dmabufIoctlSyncEnd };

package/dist/lib/dmabuf-ioctl.js

@@ -0,0 +1,67 @@
+import { ioctl } from "@k13engineering/po6-ioctl";
+import nodeOs from "node:os";
+
+const endianness = nodeOs.endianness();
+
+const flagsToFlagsBuffer = ({ flags }/*: { flags: bigint }*/) => {
+  const flagBuffer = Buffer.alloc(8);
+  if (endianness === "LE") {
+    flagBuffer.writeBigUInt64LE(flags, 0);
+  } else {
+    flagBuffer.writeBigUInt64BE(flags, 0);
+  }
+  return flagBuffer;
+};
+
+const DMA_BUF_IOCTL_SYNC = BigInt(0x40086200);
+
+const DMA_BUF_SYNC_READ = BigInt(0x1);
+const DMA_BUF_SYNC_WRITE = BigInt(0x2);
+const DMA_BUF_SYNC_START = BigInt(0x00);
+const DMA_BUF_SYNC_END = BigInt(0x4);
+
+const dmabufIoctlSync = ({ dmabufFd, flags }/*: { dmabufFd: number, flags: bigint }*/) => {
+
+  const flagBuffer = flagsToFlagsBuffer({ flags });
+
+  const { errno } = ioctl({
+    fd: dmabufFd,
+    request: DMA_BUF_IOCTL_SYNC,
+    arg: flagBuffer
+  });
+
+  if (errno !== undefined) {
+    throw Error(`dmabuf ioctl sync start failed with errno ${errno}`);
+  }
+};
+
+const dmabufIoctlSyncStart = ({ dmabufFd, read, write }/*: { dmabufFd: number, read: boolean; write: boolean }*/) => {
+
+  let flags = DMA_BUF_SYNC_START;
+  if (read) {
+    flags |= DMA_BUF_SYNC_READ;
+  }
+  if (write) {
+    flags |= DMA_BUF_SYNC_WRITE;
+  }
+
+  dmabufIoctlSync({ dmabufFd, flags });
+};
+
+const dmabufIoctlSyncEnd = ({ dmabufFd, read, write }/*: { dmabufFd: number, read: boolean; write: boolean }*/) => {
+
+  let flags = DMA_BUF_SYNC_END;
+  if (read) {
+    flags |= DMA_BUF_SYNC_READ;
+  }
+  if (write) {
+    flags |= DMA_BUF_SYNC_WRITE;
+  }
+
+  dmabufIoctlSync({ dmabufFd, flags });
+};
+
+export {
+  dmabufIoctlSyncStart,
+  dmabufIoctlSyncEnd
+};

package/dist/lib/dmabuf-mapping.d.ts

@@ -0,0 +1,23 @@
+import type { TMemoryMappedBuffer } from "@k13engineering/po6-mmap";
+import { type TMemoryProtectionFlags } from "@k13engineering/po6-mmap/dist/lib/convenience-api.js";
+type TDmabufMappingPolicy = "forbidden" | "required" | "optional";
+type TDmabufMappingAccess = {
+    read: TDmabufMappingPolicy;
+    write: TDmabufMappingPolicy;
+};
+type TDmabufMapping = Uint8Array & {
+    mappingId: number;
+    release: () => void;
+};
+declare const createMappingHelper: ({ mapAsserted }: {
+    mapAsserted: (args: {
+        memoryProtectionFlags: TMemoryProtectionFlags;
+    }) => TMemoryMappedBuffer;
+}) => {
+    map: ({ access }: {
+        access: TDmabufMappingAccess;
+    }) => TDmabufMapping;
+    close: () => void;
+};
+export { createMappingHelper, };
+export type { TDmabufMapping, TDmabufMappingAccess, TDmabufMappingPolicy };

package/dist/lib/dmabuf-mapping.js

@@ -0,0 +1,141 @@
+/*import type { TMemoryMappedBuffer } from "@k13engineering/po6-mmap";*/
+import { /*type TMemoryProtectionFlags */} from "@k13engineering/po6-mmap/dist/lib/convenience-api.js";
+import { createDefaultGarbageCollectedWithoutReleaseError, createGarbageCollectionGuard } from "./snippets/gc-guard.js";
+import { createCachedMapper } from "./cached-mapper.js";
+
+/*type TDmabufMappingPolicy = "forbidden" | "required" | "optional";*/
+
+/*type TDmabufMappingAccess = {
+  read: TDmabufMappingPolicy;
+  write: TDmabufMappingPolicy;
+};*/
+
+/*type TDmabufMapping = Uint8Array & {
+  mappingId: number;
+  release: () => void;
+};*/
+
+/*type TDmabufMappingInfo = {
+  mappingId: number;
+};*/
+
+const createMappingHelper = ({
+  mapAsserted
+}/*: {
+  mapAsserted: (args: { memoryProtectionFlags: TMemoryProtectionFlags }) => TMemoryMappedBuffer;
+}*/) => {
+
+  const readOnlyCachedMapper = createCachedMapper({
+    map: () => {
+      return mapAsserted({
+        memoryProtectionFlags: {
+          PROT_READ: true,
+          PROT_WRITE: false,
+          PROT_EXEC: false
+        },
+      });
+    },
+  });
+
+  const writeOnlyCachedMapper = createCachedMapper({
+    map: () => {
+      return mapAsserted({
+        memoryProtectionFlags: {
+          PROT_READ: false,
+          PROT_WRITE: true,
+          PROT_EXEC: false
+        },
+      });
+    },
+  });
+
+  const readWriteCachedMapper = createCachedMapper({
+    map: () => {
+      return mapAsserted({
+        memoryProtectionFlags: {
+          PROT_READ: true,
+          PROT_WRITE: true,
+          PROT_EXEC: false
+        },
+      });
+    },
+  });
+
+  const dmabufMappingGarbageCollectionGuard = createGarbageCollectionGuard({
+    createError: ({ info }/*: { info: TDmabufMappingInfo }*/) => {
+      return createDefaultGarbageCollectedWithoutReleaseError({
+        info: `dma buffer mapping with mappingId=${info.mappingId}`,
+        name: "DmabufMappingGarbageCollectedWithoutReleaseError",
+        releaseFunctionName: "release",
+        resourcesName: "dma buffer mappings",
+      });
+    },
+  });
+
+  let mappingIdCounter = 0;
+
+  // eslint-disable-next-line max-statements,complexity
+  const map = ({ access }/*: { access: TDmabufMappingAccess }*/)/*: TDmabufMapping*/ => {
+
+    const mappingId = mappingIdCounter;
+    mappingIdCounter += 1;
+    // naive approach for now
+
+    let mapperToUse/*: typeof readOnlyCachedMapper*/;
+
+    if (access.read === "forbidden" && access.write === "forbidden") {
+      throw Error(`invalid mapping access: read and write cannot both be forbidden`);
+    }
+
+    if (access.read === "required" && access.write === "required") {
+      mapperToUse = readWriteCachedMapper;
+    } else if (access.write === "required" || access.read === "forbidden") {
+      mapperToUse = writeOnlyCachedMapper;
+    } else {
+      mapperToUse = readOnlyCachedMapper;
+    }
+
+    const mappedBuffer = mapperToUse.maybeMap();
+
+    const mappingInfo/*: TDmabufMappingInfo*/ = {
+      mappingId
+    };
+
+    const { release } = dmabufMappingGarbageCollectionGuard.protect({
+      release: () => {
+        mappedBuffer.release();
+      },
+
+      info: mappingInfo
+    });
+
+    const bufferView = new Uint8Array(mappedBuffer.buffer, mappedBuffer.byteOffset, mappedBuffer.byteLength);
+    const mapping = bufferView /*as TDmabufMapping*/;
+
+    mapping.mappingId = mappingId;
+    mapping.release = release;
+
+    return mapping;
+  };
+
+  const close = () => {
+    readOnlyCachedMapper.close();
+    writeOnlyCachedMapper.close();
+    readWriteCachedMapper.close();
+  };
+
+  return {
+    map,
+    close
+  };
+};
+
+export {
+  createMappingHelper,
+};
+
+/*export type {
+  TDmabufMapping,
+  TDmabufMappingAccess,
+  TDmabufMappingPolicy
+};*/

package/dist/lib/dmabuf-transaction.d.ts

@@ -0,0 +1,20 @@
+import type { TDmabufHandle } from "./dmabuf-handle.js";
+type TTransactionFunctionArgs = {
+    use: (args: {
+        handle: TDmabufHandle;
+        access: TDmabufUseAccess;
+    }) => Uint8Array;
+};
+type TTransactionFunction<T> = (args: TTransactionFunctionArgs) => T;
+type TDmabufUseAccess = {
+    read: "required";
+    write: "required";
+} | {
+    read: "required";
+    write: "crash-process-on-write";
+} | {
+    read: "crash-process-on-read";
+    write: "required";
+};
+declare const dmabufTransaction: <T>(fn: TTransactionFunction<T>) => T;
+export { dmabufTransaction };

package/dist/lib/dmabuf-transaction.js

@@ -0,0 +1,114 @@
+/*import type { TDmabufMapping } from "./dmabuf-mapping.ts";*/
+/*import type { TDmabufHandle, TDmabufSync } from "./dmabuf-handle.ts";*/
+
+/*type TTransactionFunctionArgs = {
+  use: (args: {
+    handle: TDmabufHandle;
+    access: TDmabufUseAccess
+  }) => Uint8Array;
+};*/
+
+/*type TTransactionFunction<T> = (args: TTransactionFunctionArgs) => T;*/
+
+/*type TDmabufUseAccess = {
+  read: "required",
+  write: "required"
+} | {
+  read: "required",
+  write: "crash-process-on-write"
+} | {
+  read: "crash-process-on-read",
+  write: "required"
+};*/
+
+// type TDmabufReadUseAccess = TDmabufUseAccess["read"];
+// type TDmabufWriteUseAccess = TDmabufUseAccess["write"];
+
+/*type TUseInternal = {
+  handle: TDmabufHandle;
+  sync: TDmabufSync;
+  mapping: TDmabufMapping;
+};*/
+
+let transactionEntered = false;
+
+const dmabufTransaction = /*<T>*/(fn/*: TTransactionFunction<T>*/) => {
+
+  if (transactionEntered) {
+    throw Error("nested transactions are not allowed");
+  }
+
+  let internalUses/*: TUseInternal[]*/ = [];
+
+  const assertHandleNotAlreadyUsed = ({ handle }/*: { handle: TDmabufHandle }*/) => {
+    const existingUses = internalUses.filter((internalUse) => {
+      return internalUse.handle === handle;
+    });
+
+    if (existingUses.length > 0) {
+      throw Error(`dmabuf handle (inode ${handle.info().inode}) is already used in this transaction`);
+    }
+  };
+
+  const use = ({
+    handle,
+    access,
+  }/*: {
+    handle: TDmabufHandle;
+    access: TDmabufUseAccess
+  }*/) => {
+    assertHandleNotAlreadyUsed({ handle });
+
+    const mapping = handle.map({
+      iKnowWhatImDoing: true,
+      access: {
+        read: access.read === "required" ? "required" : "forbidden",
+        write: access.write === "required" ? "required" : "forbidden"
+      }
+    });
+
+    // @ts-expect-error 2345 - TypeScript does not get this right
+    const sync = handle.sync({
+      iKnowWhatImDoing: true,
+      read: access.read === "required",
+      write: access.write === "required"
+    });
+
+    const internalHandle/*: TUseInternal*/ = {
+      handle,
+      sync,
+      mapping
+    };
+
+    internalUses = [
+      ...internalUses,
+      internalHandle
+    ];
+
+    const buffer = new Uint8Array(mapping.buffer, mapping.byteOffset, mapping.byteLength);
+    return buffer;
+  };
+
+  transactionEntered = true;
+
+  let result/*: T*/;
+
+  try {
+    result = fn({
+      use
+    });
+  } finally {
+    transactionEntered = false;
+  }
+
+  internalUses.forEach(({ sync, mapping }) => {
+    sync.end();
+    mapping.release();
+  });
+
+  return result;
+};
+
+export {
+  dmabufTransaction
+};

package/dist/lib/index.d.ts

@@ -0,0 +1,6 @@
+import { dmabufTransaction } from "./dmabuf-transaction.js";
+import type { TDmabufHandle, TImportAndDupDmabufFunc } from "./dmabuf-handle.js";
+import type { TDmabufMapping } from "./dmabuf-mapping.js";
+declare const importAndDupDmabuf: TImportAndDupDmabufFunc;
+export { dmabufTransaction, importAndDupDmabuf };
+export type { TDmabufHandle, TDmabufMapping, };

package/dist/lib/index.js

@@ -1 +1,24 @@
 
+import { dmabufTransaction } from "./dmabuf-transaction.js";
+import { createHandleImporter } from "./dmabuf-handle.js";
+/*import type { TDmabufHandle, TImportAndDupDmabufFunc } from "./dmabuf-handle.ts";*/
+/*import type { TDmabufMapping } from "./dmabuf-mapping.ts";*/
+import { createLinuxHostInterface } from "./linux-interface-impl.js";
+
+const linuxInterface = createLinuxHostInterface();
+
+const handleImporter = createHandleImporter({
+  linuxInterface
+});
+
+const importAndDupDmabuf = handleImporter.importAndDupDmabuf /*as TImportAndDupDmabufFunc*/;
+
+export {
+  dmabufTransaction,
+  importAndDupDmabuf
+};
+
+/*export type {
+  TDmabufHandle,
+  TDmabufMapping,
+};*/

package/dist/lib/linux-interface-impl.d.ts

@@ -0,0 +1,3 @@
+import type { TLinuxDmabufInterface } from "./linux-interface.js";
+declare const createLinuxHostInterface: () => TLinuxDmabufInterface;
+export { createLinuxHostInterface };

package/dist/lib/linux-interface-impl.js

@@ -0,0 +1,44 @@
+/*import type { TLinuxDmabufInterface } from "./linux-interface.ts";*/
+import { mmapFd } from "@k13engineering/po6-mmap";
+import { dmabufIoctlSyncStart, dmabufIoctlSyncEnd } from "./dmabuf-ioctl.js";
+import { syscall, syscallNumbers } from "syscall-napi";
+import nodeFs from "node:fs";
+
+const dup = ({ fd }/*: { fd: number }*/)/*: number*/ => {
+  const { errno, ret: newFd } = syscall({
+    syscallNumber: syscallNumbers.dup,
+    args: [
+      BigInt(fd)
+    ]
+  });
+
+  if (errno !== undefined) {
+    throw Error(`dup failed with errno ${errno}`);
+  }
+
+  return Number(newFd);
+};
+
+const fstat = ({ fd }/*: { fd: number }*/) => {
+  const st = nodeFs.fstatSync(fd);
+  return { inode: st.ino, size: st.size };
+};
+
+const close = ({ fd }/*: { fd: number }*/) => {
+  nodeFs.closeSync(fd);
+};
+
+const createLinuxHostInterface = ()/*: TLinuxDmabufInterface*/ => {
+  return {
+    mmapFd,
+    dmabufIoctlSyncEnd,
+    dmabufIoctlSyncStart,
+    dup,
+    fstat,
+    close
+  };
+};
+
+export {
+  createLinuxHostInterface
+};

package/dist/lib/linux-interface.d.ts

@@ -0,0 +1,23 @@
+import type { dmabufIoctlSyncEnd, dmabufIoctlSyncStart } from "./dmabuf-ioctl.js";
+import type { mmapFd } from "@k13engineering/po6-mmap";
+type TDmabufIoctlSyncEndFunc = typeof dmabufIoctlSyncEnd;
+type TDmabufIoctlSyncStartFunc = typeof dmabufIoctlSyncStart;
+type TMmapFdFunc = typeof mmapFd;
+type TLinuxDmabufInterface = {
+    mmapFd: TMmapFdFunc;
+    dmabufIoctlSyncEnd: TDmabufIoctlSyncEndFunc;
+    dmabufIoctlSyncStart: TDmabufIoctlSyncStartFunc;
+    dup: (args: {
+        fd: number;
+    }) => number;
+    fstat: (args: {
+        fd: number;
+    }) => {
+        inode: number;
+        size: number;
+    };
+    close: (args: {
+        fd: number;
+    }) => void;
+};
+export type { TLinuxDmabufInterface };

package/dist/lib/linux-interface.js

@@ -0,0 +1,24 @@
+/* c8 ignore start */
+/*import type {
+  dmabufIoctlSyncEnd,
+  dmabufIoctlSyncStart,
+} from "./dmabuf-ioctl.ts";*/
+/*import type { mmapFd } from "@k13engineering/po6-mmap";*/
+
+/*type TDmabufIoctlSyncEndFunc = typeof dmabufIoctlSyncEnd;*/
+/*type TDmabufIoctlSyncStartFunc = typeof dmabufIoctlSyncStart;*/
+/*type TMmapFdFunc = typeof mmapFd;*/
+
+/*type TLinuxDmabufInterface = {
+  mmapFd: TMmapFdFunc;
+  dmabufIoctlSyncEnd: TDmabufIoctlSyncEndFunc;
+  dmabufIoctlSyncStart: TDmabufIoctlSyncStartFunc;
+  dup: (args: { fd: number }) => number;
+  fstat: (args: { fd: number }) => { inode: number; size: number };
+  close: (args: { fd: number }) => void;
+};*/
+
+/*export type {
+  TLinuxDmabufInterface
+};*/
+/* c8 ignore end */

package/dist/lib/snippets/gc-guard.d.ts

@@ -0,0 +1,20 @@
+type TInstance = {
+    release: () => void;
+};
+declare const createGarbageCollectionGuard: <T>({ createError, }: {
+    createError: (args: {
+        info: T;
+    }) => Error;
+}) => {
+    protect: ({ release: providedRelease, info }: {
+        release: () => void;
+        info: T;
+    }) => TInstance;
+};
+declare const createDefaultGarbageCollectedWithoutReleaseError: ({ name, info, releaseFunctionName, resourcesName, }: {
+    name: string;
+    info: string;
+    releaseFunctionName: string;
+    resourcesName: string;
+}) => any;
+export { createGarbageCollectionGuard, createDefaultGarbageCollectedWithoutReleaseError };

package/dist/lib/snippets/gc-guard.js

@@ -0,0 +1,65 @@
+/*type TInstance = {
+  release: () => void;
+};*/
+
+const createGarbageCollectionGuard = /*<T>*/({
+  createError,
+}/*: {
+  createError: (args: { info: T }) => Error,
+}*/) => {
+
+  const instanceFinalizationRegistry = new FinalizationRegistry((info/*: T*/) => {
+    // this callback is called when a instance is garbage collected without release being called
+    throw createError({ info });
+  });
+
+  const protect = ({
+    release: providedRelease,
+    info
+  }/*: { release: () => void; info: T }*/)/*: TInstance*/ => {
+    const release = () => {
+      providedRelease();
+      instanceFinalizationRegistry.unregister(release);
+    };
+
+    instanceFinalizationRegistry.register(release, info, release);
+
+    return {
+      release
+    };
+  };
+
+  return {
+    protect
+  };
+};
+
+const createDefaultGarbageCollectedWithoutReleaseError = ({
+  name,
+  info,
+  releaseFunctionName,
+  resourcesName,
+}/*: {
+  name: string,
+  info: string,
+  releaseFunctionName: string,
+  resourcesName: string,
+}*/) => {
+
+  let message = `${info} was garbage collected without calling release().`;
+  message += ` This would cause a memory leak -`;
+  message += ` therefore this raises an uncaught exception.`;
+  message += ` Please make sure to call ${releaseFunctionName}() on all ${resourcesName} when you are done with them.`;
+  message += ` Underlying resources should have still be cleaned up in case you are catching uncaught exceptions -`;
+  message += ` however, do not rely on this behavior (specifically for production code).`;
+
+  const error = Error(message);
+  error.name = name;
+
+  return error;
+};
+
+export {
+  createGarbageCollectionGuard,
+  createDefaultGarbageCollectedWithoutReleaseError
+};

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.2",
+  "version": "0.0.3",
   "name": "@k13engineering/linux-dmabuf",
   "type": "module",
   "description": "DMA buffer utilities for Node.js",
@@ -9,18 +9,24 @@
   "main": "dist/lib/index.js",
   "scripts": {
     "build": "rm -rf dist/ && deno-node-build --root . --out dist/ --entry lib/index.ts",
-    "test": "c8 --reporter lcov --reporter html --reporter text --all --src lib/ node test/index.ts",
+    "test": "c8 --reporter lcov --reporter html --reporter text --all --src lib/ --exclude lib/snippets --exclude test/ mocha test/**/*.ts",
     "lint": "eslint ."
   },
   "devDependencies": {
     "@eslint/js": "^9.17.0",
     "@k13engineering/releasetool": "^0.0.5",
+    "@types/mocha": "^10.0.10",
     "@types/node": "^22.10.5",
     "c8": "^10.1.3",
     "deno-node": "^0.0.12",
+    "mocha": "^11.7.5",
     "typescript-eslint": "^8.19.0"
   },
-  "dependencies": {},
+  "dependencies": {
+    "@k13engineering/po6-ioctl": "^0.0.2",
+    "@k13engineering/po6-mmap": "^0.0.6",
+    "syscall-napi": "^0.1.5"
+  },
   "publishConfig": {
     "access": "public"
   },