dma

Documentation

Overview

Package dma provides primitives for direct memory allocation and alignment, it is primarily used in bare metal device driver operation to avoid passing Go pointers for DMA purposes.

This package is only meant to be used with `GOOS=tamago` as supported by the TamaGo framework for bare metal Go on ARM/RISC-V SoCs, see https://github.com/usbarmory/tamago.

Index

• func Alloc(buf []byte, align int) (addr uint)
• func Free(addr uint)
• func Init(start uint, size int) (err error)
• func Read(addr uint, off int, buf []byte)
• func Release(addr uint)
• func Reserve(size int, align int) (addr uint, buf []byte)
• func Reserved(buf []byte) (res bool, addr uint)
• func Write(addr uint, off int, buf []byte)
• type Region
  • func Default() *Region
  • func NewRegion(addr uint, size int, unsafe bool) (r *Region, err error)
  • func (r *Region) Alloc(buf []byte, align int) (addr uint)
  • func (r *Region) End() uint
  • func (r *Region) Free(addr uint)
  • func (r *Region) FreeBlocks() map[uint]uint
  • func (r *Region) Init(start uint, size uint)
  • func (r *Region) Read(addr uint, off int, buf []byte)
  • func (r *Region) Release(addr uint)
  • func (r *Region) Reserve(size int, align int) (addr uint, buf []byte)
  • func (r *Region) Reserved(buf []byte) (res bool, addr uint)
  • func (r *Region) Size() uint
  • func (r *Region) Start() uint
  • func (r *Region) UsedBlocks() map[uint]uint
  • func (r *Region) Write(addr uint, off int, buf []byte)

Functions

func Alloc

func Alloc(buf []byte, align int) (addr uint)

Alloc is the equivalent of Region.Alloc() on the global DMA region.

func Free

func Free(addr uint)

Free is the equivalent of Region.Free() on the global DMA region.

func Init

func Init(start uint, size int) (err error)

Init initializes the global memory region for DMA buffer allocation, used throughout the tamago package for all DMA allocations.

Additional DMA regions for application use can be allocated through NewRegion().

func Read

func Read(addr uint, off int, buf []byte)

Read is the equivalent of Region.Read() on the global DMA region.

func Release

func Release(addr uint)

Release is the equivalent of Region.Release() on the global DMA region.

func Reserve

func Reserve(size int, align int) (addr uint, buf []byte)

Reserve is the equivalent of Region.Reserve() on the global DMA region.

func Reserved

func Reserved(buf []byte) (res bool, addr uint)

Reserved is the equivalent of Region.Reserved() on the global DMA region.

func Write

func Write(addr uint, off int, buf []byte)

Write is the equivalent of Region.Write() on the global DMA region.

Types

type Region

type Region struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Region represents a memory region allocated for DMA purposes.

func Default

func Default() *Region

Default returns the global DMA region instance.

func NewRegion

func NewRegion(addr uint, size int, unsafe bool) (r *Region, err error)

NewRegion initializes a memory region for DMA buffer allocation.

To avoid unforseen consequences the caller must ensure that allocated regions do not overlap among themselves or with the global one (see Init()).

To allow allocation of DMA buffers within Go runtime memory the unsafe flag must be set.

func (*Region) Alloc

func (r *Region) Alloc(buf []byte, align int) (addr uint)

Alloc reserves a memory region for DMA purposes, copying over a buffer and returning its allocation address, with optional alignment. The region can be freed up with Free().

If the argument is a buffer previously created with Reserve(), then its address is return without any re-allocation.

The optional alignment must be a power of 2 and word alignment is always enforced (0 == 4).

func (*Region) End

func (r *Region) End() uint

End returns the DMA region end address.

func (*Region) Free

func (r *Region) Free(addr uint)

Free frees the memory region stored at the passed address, the region must have been previously allocated with Alloc().

func (*Region) FreeBlocks

func (r *Region) FreeBlocks() map[uint]uint

FreeBlocks returns the DMA region free blocks addresses and size.

func (*Region) Init

func (r *Region) Init(start uint, size uint)

Init initializes a memory region with a single block that fits it.

func (*Region) Read

func (r *Region) Read(addr uint, off int, buf []byte)

Read reads exactly len(buf) bytes from a memory region address into a buffer, the region must have been previously allocated with Alloc().

The offset and buffer size are used to retrieve a slice of the memory region, a panic occurs if these parameters are not compatible with the initial allocation for the address.

If the argument is a buffer previously created with Reserve(), then the function returns without modifying it, as it is assumed for the buffer to be already updated.

func (*Region) Release

func (r *Region) Release(addr uint)

Release frees the memory region stored at the passed address, the region must have been previously allocated with Reserve().

func (*Region) Reserve

func (r *Region) Reserve(size int, align int) (addr uint, buf []byte)

Reserve allocates a Slice of bytes for DMA purposes, by placing its data within the DMA region, with optional alignment. It returns the slice along with its data allocation address. The buffer can be freed up with Release().

Reserving buffers with Reserve() allows applications to pre-allocate DMA regions, avoiding unnecessary memory copy operations when performance is a concern. Reserved buffers cause Alloc() and Read() to return without any allocation or memory copy.

Great care must be taken on reserved buffer as:

• buf contents are uninitialized (unlike when using Alloc())
• buf slices remain in reserved space but only the original buf can be subject of Release()

The optional alignment must be a power of 2 and word alignment is always enforced (0 == 4).

func (*Region) Reserved

func (r *Region) Reserved(buf []byte) (res bool, addr uint)

Reserved returns whether a slice of bytes data is allocated within the DMA buffer region, it is used to determine whether the passed buffer has been previously allocated by this package with Reserve().

func (*Region) Size

func (r *Region) Size() uint

Size returns the DMA region size.

func (*Region) Start

func (r *Region) Start() uint

Start returns the DMA region start address.

func (*Region) UsedBlocks

func (r *Region) UsedBlocks() map[uint]uint

UsedBlocks returns the DMA region allocated blocks addresses and size.

func (*Region) Write

func (r *Region) Write(addr uint, off int, buf []byte)

Write writes buffer contents to a memory region address, the region must have been previously allocated with Alloc().

An offset can be passed to write a slice of the memory region, a panic occurs if the offset is not compatible with the initial allocation for the address.