I/O: igt-gpu-tools Reference Manual

## I/O I/O — Register access and sideband I/O library |

## Functions

void | intel_mmio_use_pci_bar ()
void | intel_mmio_unmap_pci_bar ()
void | intel_mmio_use_dump_file ()
void | intel_mmio_unmap_dump_file ()
int | intel_register_access_init ()
void | intel_register_access_fini ()
uint32_t | intel_register_read ()
void | intel_register_write ()
int | intel_register_access_needs_fakewake ()
uint32_t | intel_dpio_reg_read ()
void | intel_dpio_reg_write ()
uint32_t | intel_flisdsi_reg_read ()
void | intel_flisdsi_reg_write ()
uint32_t | intel_iosf_sb_read ()
void | intel_iosf_sb_write ()
int | intel_punit_read ()
int | intel_punit_write ()
int | intel_nc_read ()
int | intel_nc_write ()

## Types and Values

extern void * | igt_global_mmio
struct | intel_register_range
struct | intel_register_map
struct | intel_mmio_data

## Includes

    #include <igt.h>

## Description

This library provides register I/O helpers in both a basic version and a more fancy version which also handles forcewake and can optionally check registers against a white-list. All register function are compatible. Hence the same code can be used to decode registers with either of them, or also from a dump file using `intel_mmio_use_dump_file()`.

Furthermore this library also provides helper functions for accessing the various sideband interfaces found on Valleyview/Baytrail based platforms.

## Functions

### intel_mmio_use_pci_bar ()

    void
    intel_mmio_use_pci_bar (struct intel_mmio_data *mmio_data,
                            struct pci_device *pci_dev);

Fill a mmio_data stucture with igt_mmio to point at the mmio bar.

`pci_dev` can be obtained from `intel_get_pci_device()`.

Users are expected to call `intel_mmio_unmap_pci_bar()` after use.

#### Parameters

mmio_data | mmio structure for IO operations |
pci_dev | intel gracphis pci device |

### intel_mmio_unmap_pci_bar ()

    void
    intel_mmio_unmap_pci_bar (struct intel_mmio_data *mmio_data);

Unmaps a PCI BAR region mmapped with `intel_mmio_use_pci_bar()`

#### Parameters

mmio_data | mmio structure initialized with `intel_mmio_use_pci_bar()` |

### intel_mmio_use_dump_file ()

    void
    intel_mmio_use_dump_file (struct intel_mmio_data *mmio_data,
                              char *file);

Sets also up mmio_data->igt_mmio to point at the data contained in `file` . This allows the same code to get reused for dumping and decoding from running hardware as from register dumps.

Users are expected to call `intel_mmio_unmap_dump_file()` after use.

#### Parameters

mmio_data | mmio structure for IO operations |
file | name of the register dump file to open |

### intel_mmio_unmap_dump_file ()

    void
    intel_mmio_unmap_dump_file (struct intel_mmio_data *mmio_data);

Unmaps a dump file mmapped with `intel_mmio_use_dump_file()`

#### Parameters

mmio_data | mmio structure initialized with `intel_mmio_use_dump_file()` |

### intel_register_access_init ()

    int
    intel_register_access_init (struct intel_mmio_data *mmio_data,
                                struct pci_device *pci_dev,
                                int safe,
                                int fd);

This initializes the new register access library, which supports forcewake handling and also allows register access to be checked with an explicit whitelist.

It also initializes mmio_data->igt_mmio like `intel_mmio_use_pci_bar()`.

`pci_dev` can be obtained from `intel_get_pci_device()`.

Users are expected to call `intel_register_access_fini()` after use.

#### Parameters

mmio_data | mmio structure for IO operations |
pci_dev | intel graphics pci device |
safe | use safe register access tables |

### intel_register_access_fini ()

    void
    intel_register_access_fini (struct intel_mmio_data *mmio_data);

Clean up the register access helper initialized with `intel_register_access_init()`.

#### Parameters

mmio_data | mmio structure initialized with `intel_register_access_init()` |

### intel_register_read ()

    uint32_t
    intel_register_read (struct intel_mmio_data *mmio_data,
                         uint32_t reg);

32-bit read of the register at `offset` . This function only works when the new register access helper is initialized with `intel_register_access_init()`.

Compared to `INREG()` it can do optional checking with the register access white lists.

#### Parameters

mmio_data | mmio structure for IO operations |
reg | register offset |

#### Returns

The value read from the register.

### intel_register_write ()

    void
    intel_register_write (struct intel_mmio_data *mmio_data,
                          uint32_t reg,
                          uint32_t val);

32-bit write to the register at `offset` . This function only works when the new register access helper is initialized with `intel_register_access_init()`.

Compared to `OUTREG()` it can do optional checking with the register access white lists.

#### Parameters

mmio_data | mmio structure for IO operations |
reg | register offset |
val | value to write |

### intel_register_access_needs_fakewake ()

    int
    intel_register_access_needs_fakewake (struct intel_mmio_data *mmio_data);

#### Parameters

mmio_data | mmio structure for IO operations |

#### Returns

Non-zero when forcewake initialization failed.

### intel_dpio_reg_read ()

    uint32_t
    intel_dpio_reg_read (struct intel_mmio_data *mmio_data,
                         uint32_t reg,
                         int phy);

32-bit read of the register at `offset` through the DPIO sideband port.

#### Parameters

reg | register offset |
phy | DPIO PHY to use |

#### Returns

The value read from the register.

### intel_dpio_reg_write ()

    void
    intel_dpio_reg_write (struct intel_mmio_data *mmio_data,
                          uint32_t reg,
                          uint32_t val,
                          int phy);

32-bit write of the register at `offset` through the DPIO sideband port.

#### Parameters

reg | register offset |
val | value to write |
phy | dpio PHY to use |

### intel_flisdsi_reg_read ()

    uint32_t
    intel_flisdsi_reg_read (struct intel_mmio_data *mmio_data,
                            uint32_t reg);

### intel_flisdsi_reg_write ()

    void
    intel_flisdsi_reg_write (struct intel_mmio_data *mmio_data,
                             uint32_t reg,
                             uint32_t val);

### intel_iosf_sb_read ()

    uint32_t
    intel_iosf_sb_read (struct intel_mmio_data *mmio_data,
                        uint32_t port,
                        uint32_t reg);

### intel_iosf_sb_write ()

    void
    intel_iosf_sb_write (struct intel_mmio_data *mmio_data,
                         uint32_t port,
                         uint32_t reg,
                         uint32_t val);

### intel_punit_read ()

    int
    intel_punit_read (struct intel_mmio_data *mmio_data,
                      uint32_t addr,
                      uint32_t *val);

32-bit read of the register at `offset` through the P-Unit sideband port.

#### Parameters

addr | register offset |
val | pointer to store the read result |

#### Returns

0 when the register access succeeded, negative errno code on failure.

### intel_punit_write ()

    int
    intel_punit_write (struct intel_mmio_data *mmio_data,
                       uint32_t addr,
                       uint32_t val);

32-bit write of the register at `offset` through the P-Unit sideband port.

#### Parameters

addr | register offset |
val | value to write |

#### Returns

0 when the register access succeeded, negative errno code on failure.

### intel_nc_read ()

    int
    intel_nc_read (struct intel_mmio_data *mmio_data,
                   uint32_t addr,
                   uint32_t *val);

32-bit read of the register at `offset` through the NC sideband port.

#### Parameters

addr | register offset |
val | pointer to starge for the read result |

#### Returns

0 when the register access succeeded, negative errno code on failure.

### intel_nc_write ()

    int
    intel_nc_write (struct intel_mmio_data *mmio_data,
                    uint32_t addr,
                    uint32_t val);

32-bit write of the register at `offset` through the NC sideband port.

#### Parameters

addr | register offset |
val | value to write |

#### Returns

0 when the register access succeeded, negative errno code on failure.

## Types and Values

### igt_global_mmio

    extern void *igt_global_mmio;

Pointer to the register range, initialized using `intel_register_access_init()` or `intel_mmio_use_dump_file()`. It is not recommended to use this directly. This pointer is valid only for one drm device.

### struct intel_register_range

    struct intel_register_range {
    	uint32_t base;
    	uint32_t size;
    	uint32_t flags;
    };

### struct intel_register_map

    struct intel_register_map {
    	struct intel_register_range *map;
    	uint32_t top;
    	uint32_t alignment_mask;
    };

### struct intel_mmio_data

    struct intel_mmio_data {
    	void *igt_mmio;
    	size_t mmio_size;
    	struct pci_device *dev;
    	struct intel_register_map map;
    	uint32_t pci_device_id;
    	int key;
    	bool safe;
    };