Struct sunrise_ahci::hba::Px

#[repr(packed)]pub struct Px {
    clb: Mmio<u64>,
    fb: Mmio<u64>,
    is: Mmio<PxIS>,
    ie: Mmio<PxIE>,
    cmd: Mmio<PxCMD>,
    _rsv0: Mmio<u32>,
    tfd: Mmio<PxTFD>,
    sig: Mmio<u32>,
    ssts: Mmio<PxSSTS>,
    sctl: Mmio<u32>,
    serr: Mmio<u32>,
    sact: Mmio<u32>,
    ci: Mmio<u32>,
    sntf: Mmio<u32>,
    fbs: Mmio<u32>,
    _rsv1: [Mmio<u32>; 11],
    vendor: [Mmio<u32>; 4],
}

HBA Memory Port registers.

See spec section 3.3

An array of 1 to 32 Px is found at BAR5 + 0x0100-0x10FF.

The list of ports that are actually implemented can be found in HBA.PI. Px not implemented must never be accessed.

Fields

clb: Mmio<u64>

fb: Mmio<u64>

is: Mmio<PxIS>

ie: Mmio<PxIE>

cmd: Mmio<PxCMD>

_rsv0: Mmio<u32>

tfd: Mmio<PxTFD>

sig: Mmio<u32>

ssts: Mmio<PxSSTS>

sctl: Mmio<u32>

serr: Mmio<u32>

sact: Mmio<u32>

ci: Mmio<u32>

sntf: Mmio<u32>

fbs: Mmio<u32>

_rsv1: [Mmio<u32>; 11]

vendor: [Mmio<u32>; 4]

Implementations

impl Px

pub fn stop(&mut self)

Stop this port.

Clears PxCMD.ST, and waits for PxCMD.CR to be cleared.

unsafe fn start(&mut self, command_list: &mut CmdHeaderArray)

Start this port.

Makes PxCLB point to command_list, sets PxCMD.ST, and waits for PxCMD.CR to be set.

See section 10.3.1 for conditions to meet before calling this function.

Unsafety

Port will continue updating frames pointed to by command_list. To prevent that, clear_addresses must be called before command_list is outlived.

Panics

• PxCMD.FRE is not set.
• PxCMD.CR is already set.
• A functional device is not present: probe returned false.

pub fn disable_fis_receive(&mut self)

Disables FIS Receive.

Clears PxCMD.FRE, and waits for PxCMD.FR to be cleared.

See section 10.3.2 for conditions to meet before calling this function.

Panics

• Port is running: PxCMD.ST or PxCMD.CR is set.

pub unsafe fn enable_fis_receive(&mut self, memory_area: &mut ReceivedFis)

Enable FIS Receive.

Make PxFB point to memory_area, and sets PxCMD.FRE.

Unsafety

Port will continue writing received FIS to memory_area. To prevent that, clear_addresses must be called before memory_area is outlived.

Panics

• Port is running: PxCMD.ST or PxCMD.CR is set.
• FIS Receive is already running: PxCMD.FRE or PxCMD.FR is set.

fn probe(&self) -> bool

Checks if a functional device is present on the port.

Determined by PxTFD.STS.BSY == 0 && PxTFD.STS.DRQ == 0 && (PxSSTS.DET = 3 || PxSSTS.IPM == (2,6,8)

pub fn clear_addresses(&mut self)

Makes PxFB and PxCLB point to 0x00000000.

This ensures HBA will not write to frames we may no longer own.

This function will stop the port and disable FIS Receive.

fn init(
    port_registers: &'static mut Px,
    command_list_length: usize
) -> Option<Disk>

Initializes a port, returning a Disk to interface with it.

If the port is not connected to anything, or initialisation failed, this function returns None.

fn command_running(&self, slot: usize) -> bool

Checks if the command issued in slot is still running.

This function returns true either if the slot bit is cleared in PxCI, or if an error occurred.

fn wait_command_completion(&self, slot: usize) -> Result<(), Error>

Polls the port until the command in slot is completed, or an error occurred.

unsafe fn identify(
    px: &mut Px,
    command_header: &mut CmdHeader,
    command_table: &mut CmdTable,
    command_slot_index: usize
) -> Result<(u64, bool), Error>

Sends the IDENTIFY DEVICE command to a port to gather some information about it.

Returns

• The number of addressable sectors this device possesses.
• Whether the device supports 48-bit addresses.

Unsafety

• The port must be started
• command_slot_index must not have its bit set in PxCI.
• command_header and command_table must belong to command_slot_index's command slot.

pub unsafe fn read_dma(
    buffer: *const u8,
    buffer_len: usize,
    lba: u64,
    sector_count: u64,
    px: &mut Px,
    command_header: &mut CmdHeader,
    command_table: &mut CmdTable,
    command_slot_index: usize,
    supports_48_bit: bool
) -> Result<(), Error>

Read sector_count contiguous sectors from the disk into buffer.

This function places a command in command_slot_index, signals it to the port, and waits for an interruption indicating its completion.

Based on supports_48_bits_addresses, this function will either use the READ DMA or READ DMA EXT command.

Unsafety

• buffer must point to valid memory.
• buffer_len must reflect buffer's length.
• buffer[0] - buffer[buffer_len - 1] must fall in a single mapping.
• command_slot_index must be free to use, implemented, and must point to command_header and command_table.
• px must be properly initialized.

Error

• buffer_len < sector_count * 512.
• sector_count == 0.
• sector_count is greater than supported maximum (256 for 28-bit devices, 65536 for 48-bit ones).
• lba + sector_count is not representable on a 28-bit/48-bit address.
• query_physical_address() failed.
• AhciError::BufferTooScattered: buffer is so scattered it overflows PRDT.

pub unsafe fn write_dma(
    buffer: *const u8,
    buffer_len: usize,
    lba: u64,
    sector_count: u64,
    px: &mut Px,
    command_header: &mut CmdHeader,
    command_table: &mut CmdTable,
    command_slot_index: usize,
    supports_48_bit: bool
) -> Result<(), Error>

Write sector_count contiguous sectors to the disk from buffer.

This function places a command in command_slot_index, signals it to the port, and waits for an interruption indicating its completion.

Based on supports_48_bits_addresses, this function will either use the WRITE DMA or WRITE DMA EXT command.

Unsafety

• buffer must point to valid memory.
• buffer_len must reflect buffer's length.
• buffer[0] - buffer[buffer_len - 1] must fall in a single mapping.
• command_slot_index must be free to use, implemented, and must point to command_header and command_table.
• px must be properly initialized.

Error

• buffer_len < sector_count * 512.
• sector_count == 0.
• sector_count is greater than supported maximum (256 for 28-bit devices, 65536 for 48-bit ones).
• lba + sector_count is not representable on a 28-bit/48-bit address.
• query_physical_address() failed.
• AhciError::BufferTooScattered: buffer is so scattered it overflows PRDT.

Trait Implementations

impl Debug for Px

fn fmt(&self, f: &mut Formatter) -> Result<(), Error>

Debug does not access reserved registers.