reg(1) BSD General Commands Manual reg(1)
reg -- hardware register and address space access
reg [--verbose[=BOOL]] list [THING]
reg [--verbose[=BOOL]] info [THING]
reg [--verbose[=BOOL]] [--format FORMAT] read THING
reg [--verbose[=BOOL]] [--format FORMAT] [--verify-writes[=BOOL]] write THING=VALUE
reg provides access to the registers and memory within the machine, ranging from CPU registers to those in chipsets and PCI devices, to phys-
ical memory and I/O space. It is strictly a developer and engineering tool, and is not for the feint of heart - misuse can very easily panic
your machine, or potentially even do permanent, physical damage.
You can run reg as any user, but results may be suboptimal, and you will not be able to read or write anything. In general you will always
needs to run reg as root, typically via sudo(1).
There are a handful of optional flags you may use, documented below. All flags may be specified, regardless of which commands you subse-
quently use, excepting the special flags --help and --version which exit immediately after being processed.
Note that command line arguments are processed strictly in order. That is, any flags you specify affect only subsequent commands, and only
until overridden by a second use of those flags. Since you may in fact use multiple commands in a single invocation, this can be very useful
as you may specify different formats or options for differant commands.
Specifies the format(s) to display values in. This is a comma-separated list, where each entry is a format type, one of:
default Use the default format for the item.
raw Print the raw bytes straight to stdout.
Print the mnemonic of the value. May be used at any time, but only the values of register fields may have mnemonics asso-
ciated with them. Prints an empty line if no mnemonic is known.
name Print the name of the value. May be used at any time, but only the values of register fields may have names associated
with them. Prints an empty line if no name is known.
data Prints the value as 'data', that is each byte's value, in order, in hex. A '@' suffix is included before the value to
denote this particular format. You may optionally append a number after the word 'data', indicating how many bits of data
to display between spaces. e.g. 'data32' will print the data in four byte chunks such as '@0020ffee dd6590a1 0030dde0d'.
ASCII Prints the value as an ASCII string. Characters which are not valid ASCII will be printed as periods.
UTF8 Prints the value as a UTF-8 string. Characters which are not valid UTF-8 will be printed as periods.
UTF16 Prints the value as a UTF-16 string. Characters which are not valid UTF-8 will be printed as periods.
string Prints the value as a string, using whatever encoding reg determines is most appropriate. Characters which are not valid
in the encoding chosen will be printed as periods.
float Prints the value as a number (or numbers, if the value is longer than the word size) in the specified type. You may abbre-
viated the types to just 'u', 's' or 'f', respectively. You may also use '-' or '+' to indicate signed.
You may use an 'e' prefix before 'float' (or, abbreviated, just 'e' by itself) to specify use of scientific notation.
As unsigned is the default mode you may leave it out entirely.
Following the number type you may specify the base, using any of 'hexadecimal'/'hex'/'h', 'decimal'/'dec'/'d',
'octal'/'oct'/'o' or 'binary'/'bin'/'b''unsigned' and simply specify the base.
Lastly, after the base you may specify the word width in bits, as a number. This can be used to divide up large values
(e.g. a whole section of memory) into individual words, each one presented individually with appropriate markup (e.g. '0x'
prefixes) and with space between them.
Note that characters in the output, such as in prefixes or the letters A through F used in hexadecimal numbers, are by
default lowercase unless the first character of either the number type or the number's base is uppercase. e.g. 'uhex32'
implies lowercase, 'Uhex32' or 'uHex32' implies uppercase.
Note that each separate use of the --format option completely overrides any previous specifications. Since argument ordering is
strictly obeyed, this is useful as it lets you specify different formats for different commands.
--help Prints brief usage information and exits.
If used with no argument, enables verbose mode. Otherwise enables or disables verbose mode based on BOOL, which may be any typical
boolean specifier, e.g. 'off', 'true', '0', 'yes', etc.
In verbose mode additional information may be provided, or existing information provided in a more verbose fashion (e.g. with addi-
tional whitespace and other formatting niceties). The most obvious example is the descriptions of things - by default only sum-
maries are provided, if any, while in verbose mode the full description is shown if available.
If used with no argument, turns on write verification. Otherwise enables or disables write verification based on BOOL, which may be
any typical boolean specifier, e.g. 'off', 'true', '0', 'yes', etc.
Write verification means that any values written are then immediately read back and compared, the write operation considered failed
if the values differ in any way. This can be useful in certain scenarios, though in general it's not something you want to use
unequivocally - some registers simply don't read back the same as written, or intentionally change shortly after a write, or just
generally over time, etc. Also be aware that reads may have side-effects and so enabling verification may have unintended conse-
quences for some registers.
Prints version information and exits.
There are four commands you can use to perform actions with reg:
list Lists all things matching THING (or, if THING is not specified, all devices and address spaces in the current system). Listing is
intended for perusing the contents of things and discovering what is available, not for providing specific information about items.
For that, use the 'info' command.
info Provides detailed information about all things matching THING. This information may include things like defined settings (if THING
specifies register fields), names and mnemonics, descriptions or summaries (depending on verbosity settings), etc.
Like the 'list' command, 'info' may be used without a THING parameter. However, in that case it provides information about the sys-
tem itself, not all the devices and address spaces within it.
read Prints the value(s) of all things matching THING, whether registers, register fields or sections of address spaces. The value(s)
are printed according to the format(s) specified by the most recent preceeding --format flag, or using the default format if not
explicitly defined. The default format may vary based on many factors. As such, if you are using reg programmatically you should
always specify the desired format explicitly, regardless of whether the default happens to be what you want at the current time.
write Sets the value of all things matching THING to VALUE . The values set will be printed to stdout in a similar way to reading values
using the 'read' command. If write verification has been enabled using --verify-writes, any verification failures will result in
the actual value being printed immediately after the value that was (supposedly) written.
You may specify multiple commands, optionally interspersed with option flags, that will be executed in left to right order. Note however
that reg will stop and exit upon the first failure - including failures related to printing of results or interpretation of input, not just
the raw hardware access itself - so be wary of sequences which might leave hardware in a bad state if aborted midway.
The THING argument specifies what hardware to perform the operation on. It is a potentially complex pattern that can match multiple enti-
ties, but always homogenously - that is, you can select some number of devices, or some number of registers, but not both devices and regis-
ters at once. As such, there are actually only several key modes:
System This is a special case that applies only to the 'info' command when you do not in fact provide a THING argument - in that case the
target is assumed as the system as a whole, and information such as its manufacturer, model name and number, etc provided.
Devices You may select devices in any of three ways:
1. Select all devices using an asterisk, i.e. '*', or - for the 'list' command only - by not providing a THING argument.
2. Select a particular category of devices, listed below.
3. Select devices with names matching the provided argument, in which you may use asterisks, '*', as wildcards.
When requesting a specific category of devices you can optionally specify particular devices within those categories by providing
further matching information in square brackets. The form of this information varies by category, as detailed in the category list
Known categories are:
cpus Logical processor cores. You may use brackets to specify the logical core index of the particular processor core of inter-
pci PCI devices. You may use the brackets to specify the vendor ID, device ID, segment number, bus number, device number and
function number, in that order. Each number should be separated by a delimiter such as a comma, a slash, a hyphen, a ver-
tical bar or a colon. You may intermingle delimiter styles however you wish. You are also not required to provide all six
values - any not specified will simply be treated as if you'd specified '*', meaning of course to match any value for that
e.g. pci[0x1048:0xa13, */*/3/5]
os Operating systems. Today there will naturally be just one operating system, so the use of brackets is not supported with
memory Physical memory. Today there is just one physical memory space, so the use of brackets is not supported with this cate-
io I/O space. Today there is just one I/O space, so the use of brackets is not supported with this category.
models Models of arbitrary devices. This allows you to look at any known type of device - that is, use the 'list' and 'info' com-
mands. Models are abstract - even if there are instances of that device in the current machine - and so cannot be used
with the 'read' or 'write' commands. You may specify the model of interest within square brackets.
e.g. model[Core 2]
model[Mac OS X 10.6]
Note that you can only model devices, not address spaces - address spaces are a very low level abstraction and as such do
not have any meaningful information in the abstract.
You may select one or more registers within one or more devices by providing a device specifier as above, and then appending to
that, separated by a period, the name of the register(s) of interest. The name is in fact a glob pattern - that is, you may use an
asterisk, '*', as a wildcard that matches any zero or more characters.
You may also optionally select a specific bit range in square brackets. Eventually this will mean the read or write operation
applies only to that bit range, though today this does not work correctly. It does however filter the fields that will match - only
those fields that intersect the selected range will be considered for further matching against the mnemonic/name pattern provided,
You may also enclose the pattern in double (or single) quotes in order to use spaces or prevent misinterpretation by your shell, as
shown in the examples below.
e.g. model[Core 2 (Penryn)].*
Fields In the same way as selected registers within a device, you may select fields within a register. The same glob pattern semantics
apply for matching names or mnemonics, and again you may wish to quote the pattern to prevent misinterpretation by your shell.
Note also that, as documented in the Registers section above, you may restrict to set of fields matched to only those intersect a
given bit range within the register.
You may access the raw address spaces of a device or address space by using a colon, '': followed by the address range of interest.
There are two types of address space - flat ones, like physical memory, and indexed ones, like register address spaces underlying
processors. You can think of flat address spaces as one-dimensional: the range 0 to 10 selects 11 bytes. Indexed address spaces
are in this sense two-dimensional: the range 0 to 10 selects 11 entries in the address space, where each entry is one or more bytes
deep, such that the total is at least 11 bytes and likely much more.
As such you need to be aware which you are using, as they behave slightly differently. A flat address space will read (or write) as
one big stream of bytes. An indexed address space will read as multiple individual values, and when written to will use the same
VALUE for each index independently.
You may specify the range of interest in a variety of formats, the most common two being via boundaries or via a location and length
pair. The former style sees the two end points separated by a delimiter such as a colon or a hyphen, while the later separates the
location and the length via a comma. i.e. '0x1000-0x10ff', '0x1000:0x10ff' and '0x1000,0x100' are all equivalent. You may also
select just a single index by providing just one number. You may also use formal range notation using square brackets and parenthe-
While some address spaces can be accessed explicitly (memory, io) others can only be accessed implicitly via their corresponding devices
(e.g. pci, cpu). If those devices are missing, or not all such address spaces are covered by a device, there is no way to access those
orphaned address spaces.
Input does not pay any attention to the current format options (though in any case you should use appropriate prefixes like '0x' or '@' to
You can provide raw input in an analagous way to raw output. In a more general sense, you cannot provide input via stdin rather than a com-
mand line argument.
Darwin October 13, 2009 Darwin