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 GOARCH=arm` as supported by the TamaGo framework for bare metal Go on ARM SoCs, see https://github.com/f-secure-foundry/tamago.

Index

• func Alloc(buf []byte, align int) (addr uint32)
• func Free(addr uint32)
• func Init(start uint32, size int)
• func Read(addr uint32, off int, buf []byte)
• func Release(addr uint32)
• func Reserve(size int, align int) (addr uint32, buf []byte)
• func Reserved(buf []byte) (res bool, addr uint32)
• func Write(addr uint32, off int, buf []byte)
• type Region
  • func Default() *Region
  • func (dma *Region) Alloc(buf []byte, align int) (addr uint32)
  • func (dma *Region) Free(addr uint32)
  • func (dma *Region) Init()
  • func (dma *Region) Read(addr uint32, off int, buf []byte)
  • func (dma *Region) Release(addr uint32)
  • func (dma *Region) Reserve(size int, align int) (addr uint32, buf []byte)
  • func (dma *Region) Reserved(buf []byte) (res bool, addr uint32)
  • func (dma *Region) Write(addr uint32, off int, buf []byte)

Functions

func Alloc

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

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

func Free

func Free(addr uint32)

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

func Init

func Init(start uint32, size int)

Init initializes the global memory region for DMA buffer allocation, the application must guarantee that the passed memory range is never used by the Go runtime (defining runtime.ramStart and runtime.ramSize accordingly).

The global region is used throughout the tamago package for all DMA allocations.

Separate DMA regions can be allocated in other areas (e.g. external RAM) by the application using Region.Init().

func Read

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

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

func Release

func Release(addr uint32)

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

func Reserve

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

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

func Reserved

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

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

func Write

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

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

Types

type Region

type Region struct {
	sync.Mutex

	Start uint32
	Size  int
	// 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 (*Region) Alloc

func (dma *Region) Alloc(buf []byte, align int) (addr uint32)

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) Free

func (dma *Region) Free(addr uint32)

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

func (*Region) Init

func (dma *Region) Init()

Init initializes a memory region for DMA buffer allocation, the application must guarantee that the passed memory range is never used by the Go runtime (defining runtime.ramStart and runtime.ramSize accordingly).

func (*Region) Read

func (dma *Region) Read(addr uint32, 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 (dma *Region) Release(addr uint32)

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

func (*Region) Reserve

func (dma *Region) Reserve(size int, align int) (addr uint32, 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 (dma *Region) Reserved(buf []byte) (res bool, addr uint32)

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) Write

func (dma *Region) Write(addr uint32, 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.