24.2 Bus Resources

24.2.1 Base Address Registers

To do anything particularly useful with a PCI device you will need to obtain the Base Address Registers (BARs) from the PCI Configuration space. The PCI-specific details of obtaining the BAR is abstracted in the bus_alloc_resource() function.

For example, a typical driver might have something similar to this in the attach() function:

        sc->bar0id = 0x10;
        sc->bar0res = bus_alloc_resource(dev, SYS_RES_MEMORY, &(sc->bar0id),
                      0, ~0, 1, RF_ACTIVE);
        if (sc->bar0res == NULL) {
            uprintf("Memory allocation of PCI base register 0 failed!\n");
            error = ENXIO;
            goto fail1;
        }
    
        sc->bar1id = 0x14;
        sc->bar1res = bus_alloc_resource(dev, SYS_RES_MEMORY, &(sc->bar1id),
                      0, ~0, 1, RF_ACTIVE);
        if (sc->bar1res == NULL) {
            uprintf("Memory allocation of PCI base register 1 failed!\n");
            error =  ENXIO;
            goto fail2;
        }
        sc->bar0_bt = rman_get_bustag(sc->bar0res);
        sc->bar0_bh = rman_get_bushandle(sc->bar0res);
        sc->bar1_bt = rman_get_bustag(sc->bar1res);
        sc->bar1_bh = rman_get_bushandle(sc->bar1res);
   

Handles for each base address register are kept in the softc structure so that they can be used to write to the device later.

These handles can then be used to read or write from the device registers with the bus_space_* functions. For example, a driver might contain a shorthand function to read from a board specific register like this:

    uint16_t
    board_read(struct ni_softc *sc, uint16_t address) {
        return bus_space_read_2(sc->bar1_bt, sc->bar1_bh, address);
    }

Similarly, one could write to the registers with:

    void
    board_write(struct ni_softc *sc, uint16_t address, uint16_t value) {
        bus_space_write_2(sc->bar1_bt, sc->bar1_bh, address, value);
    }

These functions exist in 8bit, 16bit, and 32bit versions and you should use bus_space_{read|write}_{1|2|4} accordingly.

24.2.2 Interrupts

Interrupts are allocated from the object-oriented bus code in a way similar to the memory resources. First an IRQ resource must be allocated from the parent bus, and then the interrupt handler must be setup to deal with this IRQ.

Again, a sample from a device attach() function says more than words.

    /* Get the IRQ resource */
    
        sc->irqid = 0x0;
        sc->irqres = bus_alloc_resource(dev, SYS_RES_IRQ, &(sc->irqid),
                      0, ~0, 1, RF_SHAREABLE | RF_ACTIVE);
        if (sc->irqres == NULL) {
        uprintf("IRQ allocation failed!\n");
        error = ENXIO;
        goto fail3;
        }
    
        /* Now we should setup the interrupt handler */
    
        error = bus_setup_intr(dev, sc->irqres, INTR_TYPE_MISC,
                   my_handler, sc, &(sc->handler));
        if (error) {
        printf("Couldn't set up irq\n");
        goto fail4;
        }
    
        sc->irq_bt = rman_get_bustag(sc->irqres);
        sc->irq_bh = rman_get_bushandle(sc->irqres);

24.2.3 DMA

On the PC, peripherals that want to do bus-mastering DMA must deal with physical addresses. This is a problem since FreeBSD uses virtual memory and deals almost exclusively with virtual addresses. Fortunately, there is a function, vtophys() to help.

    #include <vm/vm.h>
    #include <vm/pmap.h>
    
    #define vtophys(virtual_address) (...)

The solution is a bit different on the alpha however, and what we really want is a function called vtobus().

    #if defined(__alpha__)
    #define vtobus(va)      alpha_XXX_dmamap((vm_offset_t)va)
    #else
    #define vtobus(va)      vtophys(va)
    #endif

24.2.4 Deallocating Resources

It is very important to deallocate all of the resources that were allocated during attach(). Care must be taken to deallocate the correct stuff even on a failure condition so that the system will remain usable while your driver dies.