From nobody Mon Feb 9 17:23:54 2026 Received: from mail-oi1-f193.google.com (mail-oi1-f193.google.com [209.85.167.193]) (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 087C9397ABA for ; Wed, 7 Jan 2026 15:34:40 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.167.193 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1767800083; cv=none; b=O4y83ISvL3vyeT89l52rPrAPuuKwGFm8/p+nGHNACQX6bbyTmXAc8lqIWQ4liYBCPN7BReZHHLgtD12JkiFPVNw1NY56fyZFNMS18BwSCyGDGTpqJxKP3B531cWV29r7xPzDNc76IvcwYJAz14xgUe+FHeKFLBTyd7AwW6o03/s= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1767800083; c=relaxed/simple; bh=+muXBvOeYTMbD8nIPUObSxhKcu4jsEupVVL6nK1rpsA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=PIcQolFl87fOsI1lT6M9hYW4aZbrzYUTe+mHbWI9ghWfdBf8gSQmu7wrzWXnlw6btdQPqMvQHPBXdec2RpUaMfnFuFiFB1VZs0x6SRwJNnxGxF12Ld234PQy4LVnAf73d1JIj3pnWeS0Z50C87SL8Qgu6qPHuB6b/XavN3jUO9w= 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.193 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-f193.google.com with SMTP id 5614622812f47-450b5338459so1353891b6e.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=v2V8enmwcF7cbFaQ7fC+mJuXcLMdcpZvbkj9CjGoaiDzd0u9jQ9DGLZ34tCXBf5D7w df6S1GG2Vnln+kGJM6NbgDd3QdzuWhGsqOXl7B9H2o+AojuVE03tvptQE1FIAdn0YKdy c7lL1Oel6ygAF3YVhuQx0OzahgZoOycyUVsbz5cwSXbc9xZ4ZLiZn8DHjJcTjoMzQmOz DEMfQWrLB+BYST+Sj/iOVJHlZyK5LbIV7saG9vlfMpC4C9QuxpN0a7cQ1Gn1J+TEi0hI WJqGYU+UXEYk2NuptjZJ/FySsYfbz4S92xKYZ+rNOfo0cqZSnz103lHubg7LEHenlvj2 y4fg== X-Forwarded-Encrypted: i=1; AJvYcCX23oK2LfDZj66kldAH/4dKm7v8GC9iDIEgofm8uN7t0ZimSarvFs4yO2Im2zh0/vC63NKmbgm9lp3Izzs=@vger.kernel.org X-Gm-Message-State: AOJu0Yyzx/5Lr/v8iBnePEp271MPM2KDDSuaAyfIL7rYl2a4DwpYmwLn 1uAaJSBbSzH93gK+4CZQYVmZfQ15rX68cbaNKiMWh9KbHzMORphtU44J X-Gm-Gg: AY/fxX4knFhX4cvf4njIEFX/F4K7Vw7g6BgnH2SW9yxk8+u6p5Kq5sjw/3wNiAzg3eY kD6sjdBMqBuRYcAvJvM72p6Wr/KAFcftqwhoAJGYpUK9CpT7Hf/DlQkQ4XE89afiYTjCSZ690sp TqDOV1wbTI7qws8kZbG4G8H3jpBna69W0M5hSIQITtbhCAB7gfki4wJ4CyOyzFf2VZ4DbWKIx1/ ySbpYTcEceFU5cICx+OjOq+4SwJFxXERT4y4J3Lr7RoHW9qRaTV4kP6u+Otl51OcpwYX6fpiJhG sE/SJ8VOwOGoJWRSsU2sldA4PjiXvcvA6Ra+jW1TZgRp2wrEE0cJruLgdf+BgTiIW4cp+mGzTlv DHNWYtRZ9kHL+CwkRkpR611jDS7smsj5VxQy1ZeSs78Zh2IeZqWqeroZ0wmpi+tOgOd+qNuVw11 GbI3ToBnIi8Ub8NPr2wHkUEPD0ppz1EEOJn8gy3bd1FXLT 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-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable 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 =20 +/* 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 devind= ex + * references a devdax device that must be retrievable via the GET_DAXDEV + * message/response. + * + * The extent list size must be >=3D 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 =3D 4 + * ie_chunk_size =3D 2MiB + * ie_nbytes =3D 24MiB + * + * =E2=94=8C=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94= =80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=90=E2=94=80=E2=94=80= =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2= =94=80=E2=94=80=E2=94=90=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94= =80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=90=E2=94=80= =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2= =94=80=E2=94=80=E2=94=80=E2=94=90 + * =E2=94=82Chunk =3D 0 =E2=94=82Chunk =3D 1 =E2=94=82Chunk =3D 2 = =E2=94=82Chunk =3D 3 =E2=94=82 + * =E2=94=82Strip =3D 0 =E2=94=82Strip =3D 1 =E2=94=82Strip =3D 2 = =E2=94=82Strip =3D 3 =E2=94=82 + * =E2=94=82Stripe =3D 0 =E2=94=82Stripe =3D 0 =E2=94=82Stripe =3D 0 = =E2=94=82Stripe =3D 0 =E2=94=82 + * =E2=94=82 =E2=94=82 =E2=94=82 =E2=94= =82 =E2=94=82 + * =E2=94=94=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94= =80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=98=E2=94=80=E2=94=80= =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2= =94=80=E2=94=80=E2=94=98=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94= =80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=98=E2=94=80= =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2= =94=80=E2=94=80=E2=94=80=E2=94=98 + * =E2=94=82Chunk =3D 4 =E2=94=82Chunk =3D 5 =E2=94=82Chunk =3D 6 = =E2=94=82Chunk =3D 7 =E2=94=82 + * =E2=94=82Strip =3D 0 =E2=94=82Strip =3D 1 =E2=94=82Strip =3D 2 = =E2=94=82Strip =3D 3 =E2=94=82 + * =E2=94=82Stripe =3D 1 =E2=94=82Stripe =3D 1 =E2=94=82Stripe =3D 1 = =E2=94=82Stripe =3D 1 =E2=94=82 + * =E2=94=82 =E2=94=82 =E2=94=82 =E2=94= =82 =E2=94=82 + * =E2=94=94=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94= =80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=98=E2=94=80=E2=94=80= =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2= =94=80=E2=94=80=E2=94=98=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94= =80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=98=E2=94=80= =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2= =94=80=E2=94=80=E2=94=80=E2=94=98 + * =E2=94=82Chunk =3D 8 =E2=94=82Chunk =3D 9 =E2=94=82Chunk =3D 10 = =E2=94=82Chunk =3D 11 =E2=94=82 + * =E2=94=82Strip =3D 0 =E2=94=82Strip =3D 1 =E2=94=82Strip =3D 2 = =E2=94=82Strip =3D 3 =E2=94=82 + * =E2=94=82Stripe =3D 2 =E2=94=82Stripe =3D 2 =E2=94=82Stripe =3D 2 = =E2=94=82Stripe =3D 2 =E2=94=82 + * =E2=94=82 =E2=94=82 =E2=94=82 =E2=94= =82 =E2=94=82 + * =E2=94=94=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94= =80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=98=E2=94=80=E2=94=80= =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2= =94=80=E2=94=80=E2=94=98=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94= =80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=98=E2=94=80= =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2= =94=80=E2=94=80=E2=94=80=E2=94=98 + * + * * 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_si= ze) + * (and obviously the last chunk could be partial) + * * The stripe_size =3D (nstrips * chunk_size) + * * chunk_num(offset) =3D offset / chunk_size //integer division + * * strip_num(offset) =3D chunk_num(offset) % nchunks + * * stripe_num(offset) =3D 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_exten= t, + * resolving a file offset to a strip offset within a single + * interleaved_ext is order 1. + * * If nstrips=3D=3D1, a list of interleaved_ext structures degenerates t= o 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 --=20 2.49.0