HALDeviceExpCtl_IDE (changes)

Showing changes from revision #2 to #3: Added | Removed | Changed

Hardware Abstraction Layer

» HAL Device API

» List of HAL devices

» IDE parallel ATA controller

(HALDeviceExpCtl_IDE)

Device API

Currently, only API version 0 is defined. API version 0 only supports memory mapped controllers.

struct idedevice
{
  struct device dev;
  bool (*cableid)(struct idedevice *ide, int bus);
  size_t (*controllerinfo)(struct idedevice *ide,
                           int bus, union atainfo *info, size_t buflen);
  void (*setmodes)(struct idedevice *ide,
                   int bus, struct atamode *dev0, struct atamode *dev1);
};

Capabilities of the controller

The controllerinfo entry point is used to query the controller’s capabilities and limitations for each bus. The parameters are as follows:

The function returns the amount of data that would be written to info had is not been limited by buflen, or zero if the bus does not exist.

union atainfo
{
    struct
    {
        uint32_t flags;
        volatile uint8_t *cmd;
        volatile uint8_t *ctrl;
        volatile uint8_t *bus_master_reg;
        int int_device;
        uint32_t available_pio_modes;
        uint32_t available_dma_modes;
        uint32_t available_ultradma_modes;
        uint16_t dma_id;              // see OS_Hardware device spec
        uint32_t dma_location;        //           "
        const char *dma_description;  //           "
        uint32_t dma_logical_channel; // or -1 to obtain at run-time
    } bus;
    struct
    {
        uint32_t buses;
        uint16_t dma_id;
        uint32_t dma_location;
        const char *dma_description;
    } group;
}

The bus flags are defined as:

This is an internal call for use by the ADFS module and should not be used by user software.

Currently detected drives from cable

All 80 way ribbon cables, and some 40 way ribbon cables include connections to allow the cable type to be detected by software from the state of the CBLID- pin.

The cableid function returns true if CBLID- is currently low; returns false if high, or sensing unavailable.

This is an internal call for use by the ADFS module and should not be used by user software.

Setting the mode for data transfers

This entry point instructs the controller which mode is to be used for subsequent transfers on that bus. PIO, multi-word DMA, and ultra DMA are possible provided the software negotiates with the drive that it is capable and the controller is too.

The dev0 and dev1 structures are updated to show the actual modes selected, if the requested modes were not available on that bus.

On entry, both DMA and Ultra DMA modes may be requested – the DMA mode indicates the fallback if Ultra DMA is not available. On exit, no more than 1 of dma_mode and udma_mode will be set to valid values.

The call specifies timings for both devices simultaneously, as it may not be possible to set independent timings, requiring the highest common mode to be set.

Either dev0 or dev1 may be NULL, indicating that that device is not in use and its atamode should not be changed.

struct atamode
{
    uint32_t flags;
    uint8_t pio_mode;  // (eg 0-4)
    uint8_t dma_mode;  // (eg 0-2) 0xFF if none
    uint8_t udma_mode; // (eg 0-5) 0xFF if none
    uint8_t reserved;  // set to 0xFF
}

The mode flags are defined as:

This is an internal call for use by the ADFS module and should not be used by user software.

Support in RISC OS

HALDeviceExpCtl_IDE is supported by the trunk version of the ADFS module.

Known implementations

Information source: HAL.Tungsten.doc.ATA in CVS