When working on Linux device support, it's often handy to be able to easily decode register values. This is a simple tool to accurately inspect the individual fields of a register.
Download this archive: bitfield-0.2.tar.gz (tarball, 6.8 kB), and install:
[jk@pokey ~]$ tar -zxf bitfield-0.2.tar.gz [jk@pokey ~]$ cd bitfield-0.2 [jk@pokey ~]$ sudo make prefix=/usr sysconfdir=/etc install
There are some sample configuration files installed for powerpc and cell registers, but you will probably need to add configuration for your register(s). See the configuration section below for details.
This script requires a python interpreter (version 2.4 or later), and the pprint, pyparsing and getopt libraries
The bitfield utility is released under the GNU General Public License.
Mikey has made some
debian/ubuntu packages for bitfield. Just add this to your
deb http://neuling.org/devel/bitfield ./
To decode a register value, give the register name and value:
[jk@pokey ~]$ bitfield SPU_Status 0x20000082 decoding as Cell SPU Status 0x20000082  Stop-and-signal status: 0x2000 Isolate exit: 0x0 Isolate load: 0x0 Isolated mode: 0x1 Stopped: invalid instruction: 0x0 Stopped: single-step mode: 0x0 Waiting on blocked channel: 0x0 Stopped: halt instruction: 0x0 Stopped: stop-and-signal: 0x1 Running: 0x0
Multiple values can be given, or (if none are given on the command line) written to standard input.
If you give the
-n option, only non-zero fields are
-l option lists the registers that bitfield is
able to decode:
[jk@pokey ~]$ bitfield -l IOC_PTE : Cell IOMMU Page table entry IOC_STE : Cell IOMMU Segmentation table entry IOC_IOST_Origin : Cell IOMMU Segmentation table origin SPU_Status : Cell SPU Status MFC_SR1 : Cell MFC State Register 1
Register definitions can be searched with
[jk@pokey ~]$ bitfield -s status SPU_Status : Cell SPU Status
The bitfield decoder is configured by the following files (in order):
- All *.conf files under
- All *.conf files under
These files contain definitions for each register that can be decoded.
The examples here are available in this file: bitfield.conf.sample.
As an example, I'll use the Cell page table entry - a 64-bit value, represented like this:
So, we can add support for these page table entries with the following configuration:
01[IOC_PTE] 02name: Cell IOMMU Page table entry 03width: 64 04field: 0:1 Page protection 05field: 2 Coherence required 06field: 3:4 Storage ordering 07field: 5:51 RPN 08field: 52:63 IOID
This defines a register: IOC_PTE. It's 64-bits wide, and
contains 5 separate fields. The name of the register "Cell IOMMU Page
is provided for the list of available fields (using
and for searching for a register name (using
If the "width:" line is omitted, the register is given a default width of 64 bits.
Lines 4 through 8 define the fields. A field definition consists of a range of bit numbers (or a single number if the field is one bit wide), and a short description for the field. Bit numbers use the IBM convention - the most-significant bit is numbered 0. In this case, bits 0 through 15 (inclusive) of the register are the "Stop and Signal status" field, followed by a number of single-bit flags.
Bit fields can use non-contiguous bits, by specifying a list of fields separated by commas:
01[MSR_64] 02name: PowerPC Machine State Register 03field: 0 64-bit mode (SF) .. 16field: 52,55 Floating-Point Exception Mode (FE)
The configuration can specify special meanings for values of a field, using the "value:" directive. The previous IOC_PTE example can be expanded to show descriptions of the "Page protection" and "Storage ordering" fields:
01[IOC_PTE] 02name: Cell IOMMU Page table entry 03field: 0:1 Page protection 04value: 0 no access 05value: 1 read 06value: 2 write 07value: 3 read & write 08field: 2 Coherence required 09field: 3:4 Storage ordering 10value: 0 none 11value: 1 reserved 12value: 2 writes 13value: 3 reads & writes 14field: 5:51 RPN 15field: 52:63 IOID
When a field is decoded, the matching value is printed:
[jk@pokey ~]$ bitfield IOC_PTE 0xb80000000140031c decoding as Cell IOMMU Page table entry 0xb80000000140031c  Page protection: 0x2 [write] Coherence required: 0x1 Storage ordering: 0x3 [reads & writes] RPN: 0x1400 IOID: 0x31c
If you'd like to assign a new name to an existing register, define a new register with the alias directive. For example, to make 'MSR' a reference to the 'MSR_64' register definition:
01[MSR] 02alias: MSR_64
If you create any register definitions that would be useful to others, email them to me. If there's enough interest, I can put together a collection of common configurations.
bitfield-completions.sh script shipped in the
tarball provides tab-completion for the bitfield program. It's
installed (by default) into
For more details on bash completions, see the document on bash completion.
vim syntax highlighting
bitfield.vim file in the tarball provides
syntax-highlighting rules for the vim
editor. It's installed into
While editing a bitfield configuration file in vim, you can enable syntax highlighting with the following command:
bleeding edge sources
The bitfield project is kept in a git repository. If you'd like to try the (possibly broken) bleeding-edge version:
[jk@pokey ~]$ git clone git://git.ozlabs.org/home/jk/git/bitfield/
Altenatively, browse the gitweb interface.