// SPDX-License-Identifier: GPL-2.0

cxl-create-region(1)
====================

NAME
----
cxl-create-region - Assemble a CXL region by setting up attributes of its
constituent CXL memdevs.

SYNOPSIS
--------
[verse]
'cxl create-region [<options>]'

include::region-description.txt[]

For create-region, a size can optionally be specified, but if not, the maximum
possible size for each memdev will be used up to the available decode capacity
in the system for the given memory type. For persistent regions a UUID can
optionally be specified, but if not, one will be generated.

If the region-creation operation is successful, a region object will be
emitted on stdout in JSON format (see examples). If the specified arguments
cannot be satisfied with a legal configuration, then an appropriate error will
be emitted on stderr.

EXAMPLE
-------
----
#cxl create-region -m -d decoder0.1 -w 2 -g 1024 mem0 mem1
{
  "region":"region0",
  "resource":"0xc90000000",
  "size":"512.00 MiB (536.87 MB)",
  "interleave_ways":2,
  "interleave_granularity":1024,
  "mappings":[
    {
      "position":1,
      "decoder":"decoder4.0"
    },
    {
      "position":0,
      "decoder":"decoder3.0"
    }
  ]
}
created 1 region
----

OPTIONS
-------
<target(s)>::
The CXL targets that should be used to form the region. The number of
'target' arguments must match the '--ways' option (if provided).

include::bus-option.txt[]

-m::
--memdevs::
	Indicate that the non-option arguments for 'target(s)' refer to memdev
	device names. If this option is omitted and no targets are specified
	then create-region uses the equivalent of 'cxl list -M -d $decoder'
	internally as the target list. Note that depending on the topology, for
	example with switches, the automatic target list ordering may not be
	valid and manual specification of the target list is required.

-s::
--size=::
	Specify the total size for the new region. This is optional, and by
	default, the maximum possible size will be used. The maximum possible
	size is gated by both the contiguous free HPA space remaining in the
	root decoder, and the available DPA space in the component memdevs.

-t::
--type=::
	Specify the region type - 'pmem' or 'ram'. Default to root decoder
	capability, and if that is ambiguous, default to 'pmem'.

-U::
--uuid=::
	Specify a UUID for the new region. This shouldn't usually need to be
	specified, as one will be generated by default. Only applicable to
	pmem regions.

-w::
--ways=::
	The number of interleave ways for the new region's interleave. This
	should be equal to the number of memdevs specified in --memdevs, if
	--memdevs is being supplied. If --ways is not specified, it will be
	determined based on the number of memdev targets provided.

-g::
--granularity=::
	The interleave granularity for the new region. Must match the selected
	root decoder's (if provided) granularity. If the root decoder is
	interleaved across more than one host-bridge then this value must match
	that granularity. Otherwise, for non-interleaved decode windows, any
	granularity can be specified as long as all devices support that setting.

-d::
--decoder=::
	The root decoder that the region should be created under. If not
	supplied, the first cross-host bridge (if available), decoder that
	supports the largest interleave will be chosen.

include::human-option.txt[]

include::debug-option.txt[]

include::../copyright.txt[]

SEE ALSO
--------
linkcxl:cxl-list[1],
