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