[linux-block.git] / Documentation / riscv / uabi.rst

.. SPDX-License-Identifier: GPL-2.0

RISC-V Linux User ABI
=====================

ISA string ordering in /proc/cpuinfo
------------------------------------

The canonical order of ISA extension names in the ISA string is defined in
chapter 27 of the unprivileged specification.
The specification uses vague wording, such as should, when it comes to ordering,
so for our purposes the following rules apply:

#. Single-letter extensions come first, in canonical order.
   The canonical order is "IMAFDQLCBKJTPVH".

#. All multi-letter extensions will be separated from other extensions by an
   underscore.

#. Additional standard extensions (starting with 'Z') will be sorted after
   single-letter extensions and before any higher-privileged extensions.

#. For additional standard extensions, the first letter following the 'Z'
   conventionally indicates the most closely related alphabetical
   extension category. If multiple 'Z' extensions are named, they will be
   ordered first by category, in canonical order, as listed above, then
   alphabetically within a category.

#. Standard supervisor-level extensions (starting with 'S') will be listed
   after standard unprivileged extensions.  If multiple supervisor-level
   extensions are listed, they will be ordered alphabetically.

#. Standard machine-level extensions (starting with 'Zxm') will be listed
   after any lower-privileged, standard extensions. If multiple machine-level
   extensions are listed, they will be ordered alphabetically.

#. Non-standard extensions (starting with 'X') will be listed after all standard
   extensions. If multiple non-standard extensions are listed, they will be
   ordered alphabetically.

An example string following the order is::

   rv64imadc_zifoo_zigoo_zafoo_sbar_scar_zxmbaz_xqux_xrux

Misaligned accesses
-------------------

Misaligned accesses are supported in userspace, but they may perform poorly.
Commit	Line	Data
06267eb2 PD	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	RISC-V Linux User ABI
	4	=====================
	5
f07b2b3f CD	6	ISA string ordering in /proc/cpuinfo
	7	------------------------------------
	8
	9	The canonical order of ISA extension names in the ISA string is defined in
	10	chapter 27 of the unprivileged specification.
	11	The specification uses vague wording, such as should, when it comes to ordering,
	12	so for our purposes the following rules apply:
	13
	14	#. Single-letter extensions come first, in canonical order.
	15	The canonical order is "IMAFDQLCBKJTPVH".
	16
	17	#. All multi-letter extensions will be separated from other extensions by an
	18	underscore.
	19
	20	#. Additional standard extensions (starting with 'Z') will be sorted after
	21	single-letter extensions and before any higher-privileged extensions.
	22
	23	#. For additional standard extensions, the first letter following the 'Z'
2a5303b4 CD	24	conventionally indicates the most closely related alphabetical
	25	extension category. If multiple 'Z' extensions are named, they will be
	26	ordered first by category, in canonical order, as listed above, then
	27	alphabetically within a category.
f07b2b3f CD	28
	29	#. Standard supervisor-level extensions (starting with 'S') will be listed
	30	after standard unprivileged extensions. If multiple supervisor-level
	31	extensions are listed, they will be ordered alphabetically.
	32
	33	#. Standard machine-level extensions (starting with 'Zxm') will be listed
	34	after any lower-privileged, standard extensions. If multiple machine-level
	35	extensions are listed, they will be ordered alphabetically.
	36
	37	#. Non-standard extensions (starting with 'X') will be listed after all standard
	38	extensions. If multiple non-standard extensions are listed, they will be
	39	ordered alphabetically.
	40
	41	An example string following the order is::
	42
	43	rv64imadc_zifoo_zigoo_zafoo_sbar_scar_zxmbaz_xqux_xrux
	44
	45	Misaligned accesses
	46	-------------------
	47
06267eb2	48	Misaligned accesses are supported in userspace, but they may perform poorly.