1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2022 Oxide Computer Company 13.\" 14.Dd April 12, 2022 15.Dt BITSET64 9F 16.Os 17.Sh NAME 18.Nm bitset8 , 19.Nm bitset16 , 20.Nm bitset32 , 21.Nm bitset64 22.Nd set bitfield values in an integer 23.Sh SYNOPSIS 24.In sys/bitext.h 25.Ft uint8_t 26.Fo bitset8 27.Fa "uint8_t base" 28.Fa "uint_t high" 29.Fa "uint_t low" 30.Fa "uint8_t value" 31.Fc 32.Ft uint16_t 33.Fo bitset16 34.Fa "uint16_t base" 35.Fa "uint_t high" 36.Fa "uint_t low" 37.Fa "uint16_t value" 38.Fc 39.Ft uint32_t 40.Fo bitset32 41.Fa "uint32_t base" 42.Fa "uint_t high" 43.Fa "uint_t low" 44.Fa "uint32_t value" 45.Fc 46.Ft uint64_t 47.Fo bitset64 48.Fa "uint64_t base" 49.Fa "uint_t high" 50.Fa "uint_t low" 51.Fa "uint64_t value" 52.Fc 53.Sh INTERFACE LEVEL 54.Sy Volatile - 55This interface is still evolving in illumos. 56API and ABI stability is not guaranteed. 57.Sh PARAMETERS 58.Bl -tag -width Fa 59.It Fa base 60The starting integer that will have a value ORed into it. 61.It Fa high 62The high end, inclusive, of the bit range to insert 63.Fa value 64into 65.Fa base . 66.It Fa low 67The low end, inclusive, of the bit range to extract from 68.Fa value . 69.It Fa value 70A value to insert into 71.Fa base . 72.El 73.Sh DESCRIPTION 74The 75.Fn bitset8 , 76.Fn bitset16 , 77.Fn bitset32 , 78and 79.Fn bitset64 80functions are used to logically bitwise-OR in the integer 81.Fa value 82into a specified bit position in 83.Fa base . 84Effectively, the function zeros out the bit range in 85.Fa base , 86described by 87.Fa high 88and 89.Fa low 90and then performs a bitwise-OR of 91.Fa base 92which has been adjusted to start at 93.Fa low . 94.Pp 95The 96.Fa high 97and 98.Fa low 99arguments describe an inclusive bit range 100.Po 101.Pf [ Fa low , 102.Fa high ] 103.Pc 104which describes where 105.Fa value 106should be inserted. 107It is illegal 108for 109.Fa low 110to be greater than 111.Fa high , 112for 113.Fa low 114or 115.Fa high 116to exceed the integer's bit range 117.Po 118e.g. neither can be greater than 7 for 119.Fn bitset8 120.Pc , 121and 122.Fa value 123must not exceed the described bit range. 124That is, if 125.Fa high 126was 2 127and 128.Fa low 129was 1, 130.Fa value 131could not be larger than a 2-bit value. 132.Pp 133Note, these functions do not modify either 134.Fa base 135or 136.Fa value . 137.Sh RETURN VALUES 138Upon successful completion, the 139.Fn bitset8 , 140.Fn bitset16 , 141.Fn bitset32 , 142and 143.Fn bitset64 144functions all return a new value that has first cleared the specified 145bit range from 146.Fa base 147and then replaced it with 148.Fa value . 149.Sh EXAMPLES 150.Sy Example 1 - 151Using the 152.Fn bitset32 153function to build up a register value. 154.Pp 155A common use case for these functions is to help deal with registers 156that are defined as a series of bit values. 157The following example shows a register's bit definitions and then how 158they are used to construct a value to write. 159.Bd -literal 160/* 161 * This represents a token register definition. It is normally a 162 * uint32_t. 163 */ 164#define DF_IO_BASE_V2_SET_BASE(r, v) bitx32(r, 24, 12, v) 165#define DF_IO_BASE_V2_SET_IE(r, v) bitset32(r, 5, 5, v) 166#define DF_IO_BASE_V2_SET_WE(r, v) bitset32(r, 1, 1, v) 167#define DF_IO_BASE_V2_SET_RE(r, v) bitset32(r, 0, 0, v) 168 169void 170setup_register(uint32_t base) 171{ 172 uint32_t reg = 0; 173 174 /* 175 * Set read enable, write enable, and the base. Then write the 176 * hardware register. 177 */ 178 reg = DF_IO_BASE_V2_SET_RE(reg, 1); 179 reg = DF_IO_BASE_V2_SET_WE(reg, 1); 180 reg = DF_IO_BASE_V2_SET_BASE(reg, base); 181 write_register(XXX, reg); 182} 183.Ed 184.Sh SEE ALSO 185.Xr bitdel64 9F , 186.Xr bitx64 9F 187