summaryrefslogtreecommitdiff
path: root/usr/src/man
diff options
context:
space:
mode:
authorDan McDonald <danmcd@mnx.io>2022-07-21 10:10:36 -0400
committerDan McDonald <danmcd@mnx.io>2022-07-21 10:10:36 -0400
commitb8fae1071872e31bf1856f020349f693ff574c8f (patch)
treeb7fcca90727c5d5529779a2c35a85f2cec8c5c44 /usr/src/man
parent56c7f1a1c7ca3aef7200fe9d148633070f0908dc (diff)
parent46b0ac2b8506d5f4ba5ae6bff508c343d0ab4830 (diff)
downloadillumos-joyent-b8fae1071872e31bf1856f020349f693ff574c8f.tar.gz
[illumos-gate merge]
commit 46b0ac2b8506d5f4ba5ae6bff508c343d0ab4830 14802 Remove system-library-processor.p5m package commit 5e897995316df4eaf44613326c4cc090d915778c 14748 loader: support for hiding the cursor on the console commit ba5ca68405ba4441c86a6cfc87f4ddcb3565c81d 14647 SMB: Kerberos and NTLM auth should do the same post-work commit a68304eb6e91ead0cd793eae3030b924ca68adb4 14810 pcieadm show-devs should use current values for type commit 71815ce76261aa773c97600750fdce92334d1990 14727 Want AMD Unified Memory Controller Driver commit 1bcd6a1a4eeaf2fd7a90ce8b8cebd4f34baf049f 14776 pcieadm typos bytes to byes Conflict: usr/src/boot/forth/menu.4th
Diffstat (limited to 'usr/src/man')
-rw-r--r--usr/src/man/man9f/Makefile17
-rw-r--r--usr/src/man/man9f/bitdel64.9f81
-rw-r--r--usr/src/man/man9f/bitset64.9f186
-rw-r--r--usr/src/man/man9f/bitx64.9f120
4 files changed, 404 insertions, 0 deletions
diff --git a/usr/src/man/man9f/Makefile b/usr/src/man/man9f/Makefile
index 40082cd72a..9bbb662981 100644
--- a/usr/src/man/man9f/Makefile
+++ b/usr/src/man/man9f/Makefile
@@ -16,6 +16,7 @@
# Copyright 2020-2021 Tintri by DDN, Inc. All rights reserved.
# Copyright 2016 Hans Rosenfeld <rosenfeld@grumpf.hope-2000.org>
# Copyright 2022 RackTop Systems, Inc.
+# Copyright 2022 Oxide Computer Company
#
include $(SRC)/Makefile.master
@@ -54,6 +55,9 @@ MANFILES= ASSERT.9f \
bioreset.9f \
biosize.9f \
biowait.9f \
+ bitdel64.9f \
+ bitset64.9f \
+ bitx64.9f \
bp_copyin.9f \
bp_copyout.9f \
bp_mapin.9f \
@@ -693,6 +697,12 @@ MANLINKS= AVL_NEXT.9f \
avl_remove.9f \
avl_swap.9f \
bcanputnext.9f \
+ bitset8.9f \
+ bitset16.9f \
+ bitset32.9f \
+ bitx8.9f \
+ bitx16.9f \
+ bitx32.9f \
crdup.9f \
crfree.9f \
crget.9f \
@@ -1418,6 +1428,13 @@ avl_swap.9f := LINKSRC = avl.9f
AVL_NEXT.9f := LINKSRC = avl.9f
AVL_PREV.9f := LINKSRC = avl.9f
+bitset8.9f := LINKSRC = bitset64.9f
+bitset16.9f := LINKSRC = bitset64.9f
+bitset32.9f := LINKSRC = bitset64.9f
+bitx8.9f := LINKSRC = bitx64.9f
+bitx16.9f := LINKSRC = bitx64.9f
+bitx32.9f := LINKSRC = bitx64.9f
+
dev_err.9f := LINKSRC = cmn_err.9f
vcmn_err.9f := LINKSRC = cmn_err.9f
vzcmn_err.9f := LINKSRC = cmn_err.9f
diff --git a/usr/src/man/man9f/bitdel64.9f b/usr/src/man/man9f/bitdel64.9f
new file mode 100644
index 0000000000..f4cd3705e8
--- /dev/null
+++ b/usr/src/man/man9f/bitdel64.9f
@@ -0,0 +1,81 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source. A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2022 Oxide Computer Company
+.\"
+.Dd April 12, 2022
+.Dt BITDEL64 9F
+.Os
+.Sh NAME
+.Nm bitdel64
+.Nd delete bits from an integer
+.Sh SYNOPSIS
+.In sys/bitext.h
+.Ft uint64_t
+.Fo bitdel64
+.Fa "uint64_t value"
+.Fa "uint_t high"
+.Fa "uint_t low"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+This interface is still evolving in illumos.
+API and ABI stability is not guaranteed.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa value
+.It Fa high
+The high end, inclusive, of the bit range to delete from
+.Fa value .
+.It Fa low
+The low end, inclusive, of the bit range to delete from
+.Fa value .
+.It Fa value
+An integer to remove bits from.
+.El
+.Sh DESCRIPTION
+The
+.Fn bitdel64
+function removes bits from an integer,
+.Fa value .
+The act of removing a bit range not only removes all the bits in the
+range specified by
+.Fa low
+and
+.Fa high ,
+but also causes all remaining bits to be shifted over to start at
+.Fa low .
+.Pp
+For example, consider the binary value 0b11_1101_0011
+.Pq 0x3d3 .
+If we deleted bits 4 through 7, the resulting value would be 0b11_0011
+.Pq 0x33 .
+.Pp
+.Fa high
+and
+.Fa low
+are an inclusive range
+.Po
+.Pf [ Fa low ,
+.Fa high ]
+.Pc
+and the value of
+.Fa low
+cannot be greater than
+.Fa high
+or 63.
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn bitdel64
+returns the modified integer with the appropriate bits removed.
+.Sh SEE ALSO
+.Xr bitset64 9F ,
+.Xr bitx64 9F
diff --git a/usr/src/man/man9f/bitset64.9f b/usr/src/man/man9f/bitset64.9f
new file mode 100644
index 0000000000..14bf0858c7
--- /dev/null
+++ b/usr/src/man/man9f/bitset64.9f
@@ -0,0 +1,186 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source. A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2022 Oxide Computer Company
+.\"
+.Dd April 12, 2022
+.Dt BITSET64 9F
+.Os
+.Sh NAME
+.Nm bitset8 ,
+.Nm bitset16 ,
+.Nm bitset32 ,
+.Nm bitset64
+.Nd set bitfield values in an integer
+.Sh SYNOPSIS
+.In sys/bitext.h
+.Ft uint8_t
+.Fo bitset8
+.Fa "uint8_t base"
+.Fa "uint_t high"
+.Fa "uint_t low"
+.Fa "uint8_t value"
+.Fc
+.Ft uint16_t
+.Fo bitset16
+.Fa "uint16_t base"
+.Fa "uint_t high"
+.Fa "uint_t low"
+.Fa "uint16_t value"
+.Fc
+.Ft uint32_t
+.Fo bitset32
+.Fa "uint32_t base"
+.Fa "uint_t high"
+.Fa "uint_t low"
+.Fa "uint32_t value"
+.Fc
+.Ft uint64_t
+.Fo bitset64
+.Fa "uint64_t base"
+.Fa "uint_t high"
+.Fa "uint_t low"
+.Fa "uint64_t value"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+This interface is still evolving in illumos.
+API and ABI stability is not guaranteed.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa base
+The starting integer that will have a value ORed into it.
+.It Fa high
+The high end, inclusive, of the bit range to insert
+.Fa value
+into
+.Fa base .
+.It Fa low
+The low end, inclusive, of the bit range to extract from
+.Fa value .
+.It Fa value
+A value to insert into
+.Fa base .
+.El
+.Sh DESCRIPTION
+The
+.Fn bitset8 ,
+.Fn bitset16 ,
+.Fn bitset32 ,
+and
+.Fn bitset64
+functions are used to logically bitwise-OR in the integer
+.Fa value
+into a specified bit position in
+.Fa base .
+Effectively, the function zeros out the bit range in
+.Fa base ,
+described by
+.Fa high
+and
+.Fa low
+and then performs a bitwise-OR of
+.Fa base
+which has been adjusted to start at
+.Fa low .
+.Pp
+The
+.Fa high
+and
+.Fa low
+arguments describe an inclusive bit range
+.Po
+.Pf [ Fa low ,
+.Fa high ]
+.Pc
+which describes where
+.Fa value
+should be inserted.
+It is illegal
+for
+.Fa low
+to be greater than
+.Fa high ,
+for
+.Fa low
+or
+.Fa high
+to exceed the integer's bit range
+.Po
+e.g. neither can be greater than 7 for
+.Fn bitset8
+.Pc ,
+and
+.Fa value
+must not exceed the described bit range.
+That is, if
+.Fa high
+was 2
+and
+.Fa low
+was 1,
+.Fa value
+could not be larger than a 2-bit value.
+.Pp
+Note, these functions do not modify either
+.Fa base
+or
+.Fa value .
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn bitset8 ,
+.Fn bitset16 ,
+.Fn bitset32 ,
+and
+.Fn bitset64
+functions all return a new value that has first cleared the specified
+bit range from
+.Fa base
+and then replaced it with
+.Fa value .
+.Sh EXAMPLES
+.Sy Example 1 -
+Using the
+.Fn bitset32
+function to build up a register value.
+.Pp
+A common use case for these functions is to help deal with registers
+that are defined as a series of bit values.
+The following example shows a register's bit definitions and then how
+they are used to construct a value to write.
+.Bd -literal
+/*
+ * This represents a token register definition. It is normally a
+ * uint32_t.
+ */
+#define DF_IO_BASE_V2_SET_BASE(r, v) bitx32(r, 24, 12, v)
+#define DF_IO_BASE_V2_SET_IE(r, v) bitset32(r, 5, 5, v)
+#define DF_IO_BASE_V2_SET_WE(r, v) bitset32(r, 1, 1, v)
+#define DF_IO_BASE_V2_SET_RE(r, v) bitset32(r, 0, 0, v)
+
+void
+setup_register(uint32_t base)
+{
+ uint32_t reg = 0;
+
+ /*
+ * Set read enable, write enable, and the base. Then write the
+ * hardware register.
+ */
+ reg = DF_IO_BASE_V2_SET_RE(reg, 1);
+ reg = DF_IO_BASE_V2_SET_WE(reg, 1);
+ reg = DF_IO_BASE_V2_SET_BASE(reg, base);
+ write_register(XXX, reg);
+}
+.Ed
+.Sh SEE ALSO
+.Xr bitdel64 9F ,
+.Xr bitx64 9F
diff --git a/usr/src/man/man9f/bitx64.9f b/usr/src/man/man9f/bitx64.9f
new file mode 100644
index 0000000000..bf15ec5ff7
--- /dev/null
+++ b/usr/src/man/man9f/bitx64.9f
@@ -0,0 +1,120 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source. A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2022 Oxide Computer Company
+.\"
+.Dd April 12, 2022
+.Dt BITX64 9F
+.Os
+.Sh NAME
+.Nm bitx8 ,
+.Nm bitx16 ,
+.Nm bitx32 ,
+.Nm bitx64
+.Nd extract bits from an integer
+.Sh SYNOPSIS
+.In sys/bitext.h
+.Ft uint8_t
+.Fo bitx8
+.Fa "uint8_t value"
+.Fa "uint_t high"
+.Fa "uint_t low"
+.Fc
+.Ft uint16_t
+.Fo bitx16
+.Fa "uint16_t value"
+.Fa "uint_t high"
+.Fa "uint_t low"
+.Fc
+.Ft uint32_t
+.Fo bitx32
+.Fa "uint32_t value"
+.Fa "uint_t high"
+.Fa "uint_t low"
+.Fc
+.Ft uint64_t
+.Fo bitx64
+.Fa "uint64_t value"
+.Fa "uint_t high"
+.Fa "uint_t low"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+This interface is still evolving in illumos.
+API and ABI stability is not guaranteed.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa value
+An integer to extract a value from.
+.It Fa high
+The high end, inclusive, of the bit range to extract from
+.Fa value .
+.It Fa low
+The low end, inclusive, of the bit range to extract from
+.Fa value .
+.El
+.Sh DESCRIPTION
+The
+.Fn bitx8 ,
+.Fn bitx16 ,
+.Fn bitx32 ,
+and
+.Fn bitx64
+functions are used to extract a range of bits from on an 8, 16, 32, and
+64-bit value respectively.
+These functions are all implementations of a classical application of a
+bitwise-AND of a mask and a logical right shift.
+More specifically, the arguments
+.Fa high
+and
+.Fa low
+describe an inclusive range of bits
+.Po
+.Pf [ Fa low ,
+.Fa high ]
+.Pc
+to extract from
+.Fa value .
+The extracted bits are all shifted right such that the resulting value
+starts at bit 0
+.Po that is, shifted over by
+.Fa low
+.Pc .
+.Pp
+Each of the variants here operates on a specifically sized integer.
+.Fa high
+and
+.Fa low
+must fit within the bit range that the integer implies.
+For example, the valid range for
+.Fa bitx32
+is from 0 to 31.
+.Fa high
+must not be less than
+.Fa low .
+.Sh CONTEXT
+These functions may be called in all contexts,
+.Sy user ,
+.Sy kernel ,
+and
+.Sy interrupt .
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn bitx8 ,
+.Fn bitx16 ,
+.Fn bitx32 ,
+and
+.Fn bitx64
+functions all return the indicated portion of
+.Fa val .
+.Sh SEE ALSO
+.Xr bitdel64 9F ,
+.Xr bitset64 9F