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

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.

packages

Mikey has made some debian/ubuntu packages for bitfield. Just add this to your sources.list:

deb http://neuling.org/devel/bitfield ./

usage

To decode a register value, give the register name and value:

[jk@pokey ~]$ bitfield SPU_Status 0x20000082
decoding as Cell SPU Status
0x20000082 [536871042]
      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 printed.

The -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 -s <pattern>:

[jk@pokey ~]$ bitfield -s status
        SPU_Status : Cell SPU Status

configuration

The bitfield decoder is configured by the following files (in order):

  1. /etc/bitfield.conf
  2. All *.conf files under /etc/bitfield.d
  3. $HOME/.bitfield.conf
  4. All *.conf files under $HOME/.bitfield.d

These files contain definitions for each register that can be decoded.

The examples here are available in this file: bitfield.conf.sample.

register definitions

As an example, I'll use the Cell page table entry - a 64-bit value, represented like this:

IOC_PTE register

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 table entry" is provided for the list of available fields (using -l), and for searching for a register name (using -s).

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)

specific values

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 [13258597302999712540]
   Page protection: 0x2 [write]
Coherence required: 0x1
  Storage ordering: 0x3 [reads & writes]
               RPN: 0x1400
              IOID: 0x31c

aliases

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

sharing configurations

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.

extras

bash completion

The bitfield-completions.sh script shipped in the tarball provides tab-completion for the bitfield program. It's installed (by default) into $sysconfdir/bash_completion.d/bitfield.

For more details on bash completions, see the document on bash completion.

vim syntax highlighting

The bitfield.vim file in the tarball provides syntax-highlighting rules for the vim editor. It's installed into $prefix/share/vim/addons/syntax/bitfield.vim.

While editing a bitfield configuration file in vim, you can enable syntax highlighting with the following command: 

:set syntax=bitfield

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.