hal

type ChassisHAL interface {
	// PowerState returns true when the managed system is powered on.
	PowerState(ctx context.Context) (bool, error)
	// SetPower powers the managed system on or off.
	SetPower(ctx context.Context, on bool) error
	// PowerCycle performs a full power cycle of the managed system
	// (Chassis Control action 0x02, spec Table 28-3). The semantic meaning
	// for a given BMC is defined by the upper-layer HAL implementation.
	PowerCycle(ctx context.Context) error
	// ColdReset performs a hardware cold reset of the managed system.
	ColdReset(ctx context.Context) error
	// WarmReset requests an OS-level warm reboot of the managed system.
	WarmReset(ctx context.Context) error
	// Identify pulses the chassis identification LED for the given duration.
	// seconds == 0 means turn off; [ForcedIdentify] is expressed by the caller
	// passing a large value (e.g., math.MaxUint8).
	Identify(ctx context.Context, seconds uint8) error
	// IntrusionState returns true when the chassis has been opened since last reset.
	// Implementations that lack intrusion detection must return ErrNotSupported.
	IntrusionState(ctx context.Context) (bool, error)
	// SetBootFlags commits the full boot flags structure (spec Table 28-6).
	// The upper layer decides which bits it cares about; HAL implementations
	// must not silently drop fields they ignore. Implementations that do not
	// maintain boot state return ErrNotSupported.
	SetBootFlags(ctx context.Context, flags *types.BootOptionParam_BootFlags) error
	// GetBootFlags reads back the current boot flags, symmetric with
	// [SetBootFlags]. Implementations that cannot read boot flags back must
	// return ErrNotSupported; handlers translate that to the
	// CodeParameterNotSupported completion code.
	GetBootFlags(ctx context.Context) (*types.BootOptionParam_BootFlags, error)
	// SetBootInfoAcknowledge persists the boot initiator acknowledge data
	// (spec Table 28-14, param #4).  The HAL may implement this as a no-op
	// (return nil) if it does not track boot initiator identity.
	SetBootInfoAcknowledge(ctx context.Context, ack *types.BootOptionParam_BootInfoAcknowledge) error
	// GetBootInfoAcknowledge reads back the stored acknowledge data.
	// Implementations that do not persist this return ErrNotSupported.
	GetBootInfoAcknowledge(ctx context.Context) (*types.BootOptionParam_BootInfoAcknowledge, error)
}

type ConsoleConn interface {
	io.WriteCloser

	// ReadAvailable copies immediately-pending console output into p and
	// returns (0, nil) when no data is waiting. It must not block.
	ReadAvailable(p []byte) (int, error)

	// SendBreak transmits a ~300 ms serial BREAK to the baseboard (spec
	// v2.0 Table 15-2 operation bit [4]). Implementations whose transport
	// has no BREAK concept (e.g. a websocket) return ErrNotSupported.
	SendBreak(ctx context.Context) error
}

type ConsoleHAL interface {
	// Open attaches to the system serial console and returns its byte stream.
	// It is called when a remote console activates the SOL payload
	// (Activate Payload command, spec v2.0 §24.1) and the returned conn is
	// closed when the payload is deactivated or the owning session ends.
	//
	// Opening an already-attached console must fail: a shared serial port
	// cannot serve two activations (spec v2.0 §15.3 serial port sharing).
	Open(ctx context.Context) (ConsoleConn, error)
}

type FRUStore interface {
	Read(ctx context.Context, deviceID uint8) ([]byte, error)
	Write(ctx context.Context, deviceID uint8, data []byte) error
	Delete(ctx context.Context, deviceID uint8) error
	DeviceIDs(ctx context.Context) ([]uint8, error)
}

type GPIOHAL interface {
	// Set drives an output GPIO high (true) or low (false).
	Set(ctx context.Context, pin string, high bool) error
	// Get reads the current level of an input GPIO.
	Get(ctx context.Context, pin string) (bool, error)
	// Watch calls callback whenever the input level changes.
	// The returned cancel function stops watching.
	Watch(ctx context.Context, pin string, callback func(high bool)) (cancel func(), err error)
}

type HAL interface {
	// Chassis returns chassis power and identification controls, or nil.
	Chassis() ChassisHAL
	// Sensors returns the sensor reading interface, or nil.
	Sensors() SensorHAL
	// Storage returns FRU/SDR blob stores for Storage NetFn handlers, or nil.
	Storage() StorageHAL
	// Network returns BMC NIC configuration, or nil.
	Network() NetworkHAL
	// GPIO returns discrete GPIO control (LEDs, buttons), or nil.
	GPIO() GPIOHAL
	// I2C returns raw I2C bus access for sensors or EEPROMs, or nil.
	I2C() I2CHAL
	// Console returns the system serial console used by SOL payloads
	// (spec v2.0 §15), or nil when the target has no redirectable console.
	Console() ConsoleHAL
	// Close releases all hardware resources.
	Close() error
}

type I2CHAL interface {
	// Read performs a register read from an I2C device.
	Read(ctx context.Context, bus int, addr uint8, reg uint8, length int) ([]byte, error)
	// Write performs a register write to an I2C device.
	Write(ctx context.Context, bus int, addr uint8, reg uint8, data []byte) error
}

type IPConfig struct {
	IP      [4]byte
	Mask    [4]byte
	Gateway [4]byte
	MAC     [6]byte
	DHCP    bool
	// Port is the primary RMCP port the BMC listens on (Get LAN Configuration
	// Parameters param #8). Zero means the standard 623; a non-zero value lets a
	// BMC that listens on a non-standard port advertise it to in-band software.
	Port uint16
}

type NetworkHAL interface {
	GetConfig(ctx context.Context) (*IPConfig, error)
	SetConfig(ctx context.Context, cfg *IPConfig) error
}

type SDRStore interface {
	Read(ctx context.Context, recordID uint16) ([]byte, error)
	Write(ctx context.Context, recordID uint16, data []byte) error
	Delete(ctx context.Context, recordID uint16) error
	RecordIDs(ctx context.Context) ([]uint16, error)
}

type SensorDescriptor struct {
	ID   uint8
	Type uint8 // IPMI sensor type code (section 42 of IPMI spec)
	Name string
}

type SensorHAL interface {
	// ReadRaw returns the raw sensor byte that the BMC formula maps to a real value.
	ReadRaw(ctx context.Context, sensorID uint8) (uint8, error)
	// List returns all sensors available on the hardware.
	List(ctx context.Context) ([]SensorDescriptor, error)
}

type StorageHAL interface {
	FRU() FRUStore
	SDR() SDRStore
}