▼Ledum Definers
►3 Device Bus
On this page:
3.1 Bus Structs
busintf
busreg
match-busreg-addr
3.2 Generic Device Interface
gen:  device
device?
device-read
device-write
device-blockread
device-blockwrite
device-attach
device-detach
device-capabilities
device-dma
device-has-capability?
device-has-read?
device-has-write?
device-has-blockread?
device-has-blockwrite?
device-has-attach?
device-has-detach?
3.3 Bus Core
make-bus
busintf-attach!
busintf-detach!
busintf-write!
busintf-read
busintf-blockwrite!
busintf-blockread
busintf-dma
3.4 Bus Environment
current-bus
bus-attach!
bus-detach!
bus-read
bus-write!
9.2
    contents    up   

3 Device Bus🔗

 (require ledum/define/bus) package: ledum-definers

This module provides all the common bindings required to implement and use devices connected to the bus emulation layer.

Specifically it reprovides the following procedures: bus-attach!, bus-detach!, bus-write!, bus-read.

3.1 Bus Structs🔗

 (require ledum/define/bus/struct) package: ledum-definers

Only the rudimentary bus interface and registered device structs are provided with some auxiliary functionality as well.

struct

(struct busintf (adrbw datbw [devs #:mutable]))

  adrbw : exact-positive-integer?
  datbw : exact-positive-integer?
  devs : (listof busreg?)
Represents the bus itself. The interface consists only of the address bus bit-width adrbw and the data bus bit-width datbw. The list of devices devs is to be updated dynamically as devices are attached and/or detached.

struct

(struct busreg (start end dev))

  start : exact-nonnegative-integer?
  end : exact-nonnegative-integer?
  dev : device?
This struct contains the attachment information about a given device instance dev starting at address start and ending at address end.

procedure

(match-busreg-addr br addr) → boolean?

  br : busreg?
  addr : exact-nonnegative-integer?
Returns #t if given address addr falls within the registered region of bus-registered device br.

3.2 Generic Device Interface🔗

 (require ledum/define/bus/device) package: ledum-definers

Any device connecting to the bus must conform to the generic interface specified in this module. The implementation does not need to be complete - only the device-capabilities must be implemented and then only the generic methods for which the device has a capability have to be implemented as well.

generic interface

gen:device

A generic interface for device connected to the bus. The interface specifies the following methods:

See the bus-watcher implementation for a simple device example.

procedure

(device? v) → boolean?

  v : any/c
Returns #t if given value v is an instance of the generic interface gen:device.

procedure

(device-read device addr) → exact-nonnegative-integer?

  device : device?
  addr : exact-nonnegative-integer?
Reads a single word from given device at given device address addr.

procedure

(device-write device addr value) → void?

  device : device?
  addr : exact-nonnegative-integer?
  value : exact-nonnegative-integer?
Writes a single word value to given address addr of given device.

procedure

(device-blockread device addr buf) → void?

  device : device?
  addr : exact-nonnegative-integer?
  buf : (vectorof exact-nonnegative-integer?)
Not all devices support this capability, remember to check using the device-has-blockread? predicate first.

Fills the given buffer buf with device data starting at address addr.

procedure

(device-blockwrite device addr buf) → void?

  device : device?
  addr : exact-nonnegative-integer?
  buf : (vectorof exact-nonnegative-integer?)
Not all devices support this capability, remember to check using the device-has-blockwrite? predicate first.

Sets the device data starting at address addr to the contents of the buffer buf.

procedure

(device-attach device bus) → void?

  device : device?
  bus : busintf?
When the device is attached to the bus and the predicate device-has-attach? reports #t, this procedure is called on the device and it can react appropriately on being attached to the bus.

procedure

(device-detach device) → void?

  device : device?
When the device is detached from the bus and the predicate device-has-detach? returns #t, this procedure gets called immediately after removing the device from the bus.

procedure

(device-capabilities device) → (listof symbol?)

  device : device?
Returns a list of device capabilities.

procedure

(device-dma device addr size) → 
vector?
exact-nonnegative-integer?
exact-positive-integer?
  device : device?
  addr : exact-nonnegative-integer?
  size : exact-positive-integer?
Returns the underlying memory backing data structure and size and offset information allowing direct manipulation of device memory.

procedure

(device-has-capability? dev cap) → boolean?

  dev : device?
  cap : symbol?
Returns #t if the list returned by device-capabilities for given device dev contains the symbol cap.

procedure

(device-has-read? dev) → boolean?

  dev : device?
A predicate matching device dev which implements device-read generic method.

procedure

(device-has-write? dev) → boolean?

  dev : device?
A predicate matching device dev which implements device-write generic method.

procedure

(device-has-blockread? dev) → boolean?

  dev : device?
A predicate matching device dev which implements device-blockread generic method.

procedure

(device-has-blockwrite? dev) → boolean?

  dev : device?
A predicate matching device dev which implements device-blockwrite generic method.

procedure

(device-has-attach? dev) → boolean?

  dev : device?
A predicate matching device dev which implements device-attach generic method.

procedure

(device-has-detach? dev) → boolean?

  dev : device?
A predicate matching device dev which implements device-detach generic method.

3.3 Bus Core🔗

 (require ledum/define/bus/core) package: ledum-definers

This module provides the core procedures to create and use the bus.

procedure

(make-bus addr data) → busintf?

  addr : exact-positive-integer?
  data : exact-positive-integer?
Creates a new bus instance of given address bus width addr and data bus width data.

procedure

(busintf-attach! bus start end dev) → void?

  bus : busintf?
  start : exact-nonnegative-integer?
  end : exact-nonnegative-integer?
  dev : device?
Attaches the given device dev to the bus at address start spanning to the address end. If the device has the device-has-attach? capability the device-attach generic method is invoked after attaching the device to the bus.

procedure

(busintf-detach! bus dev) → void?

  bus : busintf?
  dev : device?
Detaches the device dev from the bus. If the device reports device-has-detach? the device-detach generic method is invoked at the end of the process.

procedure

(busintf-write! bus addr value) → void?

  bus : busintf?
  addr : exact-nonnegative-integer?
  value : exact-nonnegative-integer?
Writes a single word value at address addr of whichever device is mapped there.

If no device on the bus accepts the write, exn:ledum:bus is raised with offending address addr and informative value.

procedure

(busintf-read bus addr) → exact-nonnegative-integer?

  bus : busintf?
  addr : exact-nonnegative-integer?
Reads a single word value from address addr of whichever device is mapped there.

If no device on the bus serves the read, exn:ledum:bus is raised with offending address addr.

procedure

(busintf-blockwrite! bus addr buf) → void?

  bus : busintf?
  addr : exact-nonnegative-integer?
  buf : (vectorof exact-nonnegative-integer?)
If the address addr falls into a region where a device with device-has-blockwrite? resides, the buffer buf is passed onto the device for performing the device-blockwrite.

This should not be used for standard inter-device communication but mainly as an optimization of the emulation layer for data-intensive tasks like video output.

procedure

(busintf-blockread bus addr buf) → void?

  bus : busintf?
  addr : exact-nonnegative-integer?
  buf : (vectorof exact-nonnegative-integer?)
If the address addr falls into a region where a device with device-has-blockread? resides, the buffer buf is passed onto the device for performing the device-blockread.

This should not be used for standard inter-device communication but mainly as an optimization of the emulation layer for data-intensive tasks like video output.

procedure

(busintf-dma bus addr size) → 
vector?
exact-nonnegative-integer?
exact-positive-integer?
  bus : busintf?
  addr : exact-nonnegative-integer?
  size : exact-positive-integer?
If the address range of given size length starting at addr on the bus is occupied by a device with DMA capability, this procedure returns three values allowing direct access to its underlying memory backing storage. It is primarily intended for high-performance implementation of video output.

3.4 Bus Environment🔗

 (require ledum/define/bus/env) package: ledum-definers

This module provides the parameterizable environment to be used by both ISA specification and computer system emulator.

parameter

(current-bus) → busintf?

(current-bus bus) → void?
  bus : busintf?
This parameter holds the currently used system bus instance.

procedure

(bus-attach! start end dev) → void?

  start : exact-nonnegative-integer?
  end : exact-nonnegative-integer?
  dev : device?
Uses busintf-attach! to attach given device dev to the provided address range from start to end onto the (current-bus).

procedure

(bus-detach! dev) → void?

  dev : device?
Uses busintf-detach! to detach given device dev from the (current-bus).

procedure

(bus-read addr) → exact-nonnegative-integer?

  addr : exact-nonnegative-integer?
Uses busintf-read to read a single value from the address addr on the (current-bus).

procedure

(bus-write! addr value) → void?

  addr : exact-nonnegative-integer?
  value : exact-nonnegative-integer?
Uses busintf-write! to write a single value to the address addr on the (current-bus).

    contents    up