From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-oi1-f194.google.com (mail-oi1-f194.google.com [209.85.167.194]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 0927A397ABC for ; Wed, 7 Jan 2026 15:34:40 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.167.194 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1767800082; cv=none; b=TLh9QyD3GzrL7sdoOQg1w5rGOhD5zD5OqV3aLl+QuUNCuSFISfZzOPsLp8x8amND1y6m9KwrQwr0GYE05SxOKUN/KZcUn8YQkmKMeoJRmI1IbWuBp2iHR8011H8W8OO36tk53CsSb8OGIroZ+7oOb/zdkcBm9hyP2AJxLxDOuus= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1767800082; c=relaxed/simple; bh=+muXBvOeYTMbD8nIPUObSxhKcu4jsEupVVL6nK1rpsA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=i6fmZu80R438920xprdWs+A9uZJWQ118P/sto99kn5AAJEKjd+ClIZbXkYFHFdzejPN9aDN0pvF9TLk+0Dt5k8y/iDHlm9eaggHzxrdeMWvFRfd8hTbUKatopd/+fH+uI09P+7DgcBp/ZsFEjJhBzk5OZLHCIj1qvQ9OOh2PDLg= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=Groves.net; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=TZb+7stT; arc=none smtp.client-ip=209.85.167.194 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=Groves.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="TZb+7stT" Received: by mail-oi1-f194.google.com with SMTP id 5614622812f47-450b5338459so1353892b6e.2 for ; Wed, 07 Jan 2026 07:34:40 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1767800080; x=1768404880; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:sender:from:to:cc:subject:date :message-id:reply-to; bh=WDzXFW8FM/AL7CQLZ1rgjH5BjM6661IE1WdAgak/okg=; b=TZb+7stT7egIVn8Q3MNVj8NKFsrujsEIJMHdzd6hvTgqHjAf5LUoGkWcVXp0Qoq4GG GbSY1Xw+0kTxUCvB/aLPbMrp8COBJrZIOIACT1kNg8tqzbPGdouWHs3fWP3e578wM4nq 3sPwXMX9uxDIbixJmPfcEu6g+3NJ0/+/iXtDQUT9cHWUAA73m8v9QfSwegyfKPCff6Un 9bX/gX2kI41mrGklyKmpAvqp0yn4QRQRvNnBzFlMIt+SorvoUwl9nnPFWcxvmBRrujIM GaChvhPq8sDb8UZBhxQZWotgFGAZI57iNrSnOxVD3f/G8ShPLB7k3ZG1u5f1yQs4OxGL tMbg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1767800080; x=1768404880; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:sender:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=WDzXFW8FM/AL7CQLZ1rgjH5BjM6661IE1WdAgak/okg=; b=HrB2wEjJiHDh2dxFMRVrPoNsYOhB4P8YtaOwVfP4IDuwWE6Lg15plK7iCi6Agk54B2 e2XoSCe0odDYxUWS702+F5ruFCnYfq29bMElkBBy2G0gVDv4bIGGUXtrGzL7Cdra8kdW HA0ggTp7hHU2KQb1CmVOUoYczEGDnNsvg90+j0qekHpkTZCwqwRMFuxLoLqvakjouNdt DHBDFfa9NjfjvLpmRnijI1R1HRx58wyXg9iq56SYY+KHqZnINmskYS8DQnagaQTpQea1 zL5cNxkQlnLijoaepAXe9cjB76tQmKYOFaqWX/4SinuX7TbbqzFfQLUPyRVPAbOwkJtd Mz9Q== X-Forwarded-Encrypted: i=1; AJvYcCXaIAZ2eH0nIxsgWBIWY71fvwpj4gzGqmfTEylIFzqCqIAwWDsJgWKia4vy9o9nnpuTLFuAvUm9RK4=@vger.kernel.org X-Gm-Message-State: AOJu0YyLN3Q1Z6ZwcJOKw1McvyIlzUwgQHUwmcxEcrtBLbXeRIywUyL7 aVYhTy9iDOoqb/C+hPQRG0TmOiBfgejdSr3iPQ6AWzrYuuRVuowPTZIn X-Gm-Gg: AY/fxX774XKHIBLGPVpvFLXO/Gl3+HoxeoDZj186EsAZOwQTyNDAN+BEbcHtR9Tbhf6 76pWOjaEWO0ESg0a7WjhtIGr+wqCFIWMAfJrdPm/urVJVGssj4qGoglAmiM34HxYsHiWH9+PHgP v4Dzn/XZ6TGO3bXPgiL3HmfqTfr89z637wBV/GULq5pxbK5PgtF+w4eV70pbKIIp8nq+LX2YNY4 fr4dov9on4dZFgu0/xyMvvmfibpchv6tcMC/z7jJmf+9ADueTC8A8XyJ7AvUBf5atsBK0/3F/pX gAm7fLhyakfNMkePdnFHNozdVeTugTDfYgJN/9yDjxZgYhc9GqaayJ7aasL52h49Bo+G8fJ+fqG IlV5SFKCiZBJSv0sMbvXyAJGDgA93T6Z7PvzXdn8hocwmJ4oP7o1dW3ki9BKBUjGESGMtfBdIVf m5Jot2ghycvlmkGXidqDMyRLaFRKKh3zZzqeK5adXmNfTV X-Google-Smtp-Source: AGHT+IH4P/04LMtWqv8sSwu50eq+akkq0AyxmvD1PnTkrLfjOQ9ju3pd7rvqUnQ/LnpHTBBsjZ04Pw== X-Received: by 2002:a05:6808:309a:b0:450:3122:f0a2 with SMTP id 5614622812f47-45a6bccfa88mr1317344b6e.11.1767800079970; Wed, 07 Jan 2026 07:34:39 -0800 (PST) Received: from localhost.localdomain ([2603:8080:1500:3d89:a917:5124:7300:7cef]) by smtp.gmail.com with ESMTPSA id 5614622812f47-45a5e2f1de5sm2398106b6e.22.2026.01.07.07.34.38 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Wed, 07 Jan 2026 07:34:39 -0800 (PST) Sender: John Groves From: John Groves X-Google-Original-From: John Groves To: John Groves , Miklos Szeredi , Dan Williams , Bernd Schubert , Alison Schofield Cc: John Groves , Jonathan Corbet , Vishal Verma , Dave Jiang , Matthew Wilcox , Jan Kara , Alexander Viro , David Hildenbrand , Christian Brauner , "Darrick J . Wong" , Randy Dunlap , Jeff Layton , Amir Goldstein , Jonathan Cameron , Stefan Hajnoczi , Joanne Koong , Josef Bacik , Bagas Sanjaya , Chen Linxuan , James Morse , Fuad Tabba , Sean Christopherson , Shivank Garg , Ackerley Tng , Gregory Price , Aravind Ramesh , Ajay Joshi , venkataravis@micron.com, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, nvdimm@lists.linux.dev, linux-cxl@vger.kernel.org, linux-fsdevel@vger.kernel.org, John Groves Subject: [PATCH V3 20/21] famfs_fuse: Add famfs fmap metadata documentation Date: Wed, 7 Jan 2026 09:33:29 -0600 Message-ID: <20260107153332.64727-21-john@groves.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20260107153332.64727-1-john@groves.net> References: <20260107153244.64703-1-john@groves.net> <20260107153332.64727-1-john@groves.net> Precedence: bulk X-Mailing-List: linux-doc@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From: John Groves This describes the fmap metadata - both simple and interleaved Signed-off-by: John Groves --- fs/fuse/famfs_kfmap.h | 73 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/fs/fuse/famfs_kfmap.h b/fs/fuse/famfs_kfmap.h index 6a6420bdff48..ac5971d4c63a 100644 --- a/fs/fuse/famfs_kfmap.h +++ b/fs/fuse/famfs_kfmap.h @@ -7,6 +7,79 @@ #ifndef FAMFS_KFMAP_H #define FAMFS_KFMAP_H +/* KABI version 43 (aka v2) fmap structures + * + * The location of the memory backing for a famfs file is described by + * the response to the GET_FMAP fuse message (defined in + * include/uapi/linux/fuse.h + * + * There are currently two extent formats: Simple and Interleaved. + * + * Simple extents are just (devindex, offset, length) tuples, where devindex + * references a devdax device that must be retrievable via the GET_DAXDEV + * message/response. + * + * The extent list size must be >= file_size. + * + * Interleaved extents merit some additional explanation. Interleaved + * extents stripe data across a collection of strips. Each strip is a + * contiguous allocation from a single devdax device - and is described by + * a simple_extent structure. + * + * Interleaved_extent example: + * ie_nstrips = 4 + * ie_chunk_size = 2MiB + * ie_nbytes = 24MiB + * + * ┌────────────┐────────────┐────────────┐────────────┐ + * │Chunk = 0 │Chunk = 1 │Chunk = 2 │Chunk = 3 │ + * │Strip = 0 │Strip = 1 │Strip = 2 │Strip = 3 │ + * │Stripe = 0 │Stripe = 0 │Stripe = 0 │Stripe = 0 │ + * │ │ │ │ │ + * └────────────┘────────────┘────────────┘────────────┘ + * │Chunk = 4 │Chunk = 5 │Chunk = 6 │Chunk = 7 │ + * │Strip = 0 │Strip = 1 │Strip = 2 │Strip = 3 │ + * │Stripe = 1 │Stripe = 1 │Stripe = 1 │Stripe = 1 │ + * │ │ │ │ │ + * └────────────┘────────────┘────────────┘────────────┘ + * │Chunk = 8 │Chunk = 9 │Chunk = 10 │Chunk = 11 │ + * │Strip = 0 │Strip = 1 │Strip = 2 │Strip = 3 │ + * │Stripe = 2 │Stripe = 2 │Stripe = 2 │Stripe = 2 │ + * │ │ │ │ │ + * └────────────┘────────────┘────────────┘────────────┘ + * + * * Data is laid out across chunks in chunk # order + * * Columns are strips + * * Strips are contiguous devdax extents, normally each coming from a + * different memory device + * * Rows are stripes + * * The number of chunks is (int)((file_size + chunk_size - 1) / chunk_size) + * (and obviously the last chunk could be partial) + * * The stripe_size = (nstrips * chunk_size) + * * chunk_num(offset) = offset / chunk_size //integer division + * * strip_num(offset) = chunk_num(offset) % nchunks + * * stripe_num(offset) = offset / stripe_size //integer division + * * ...You get the idea - see the code for more details... + * + * Some concrete examples from the layout above: + * * Offset 0 in the file is offset 0 in chunk 0, which is offset 0 in + * strip 0 + * * Offset 4MiB in the file is offset 0 in chunk 2, which is offset 0 in + * strip 2 + * * Offset 15MiB in the file is offset 1MiB in chunk 7, which is offset + * 3MiB in strip 3 + * + * Notes about this metadata format: + * + * * For various reasons, chunk_size must be a multiple of the applicable + * PAGE_SIZE + * * Since chunk_size and nstrips are constant within an interleaved_extent, + * resolving a file offset to a strip offset within a single + * interleaved_ext is order 1. + * * If nstrips==1, a list of interleaved_ext structures degenerates to a + * regular extent list (albeit with some wasted struct space). + */ + /* * The structures below are the in-memory metadata format for famfs files. * Metadata retrieved via the GET_FMAP response is converted to this format -- 2.49.0