RTEMS: bsps/powerpc/gen5200/bestcomm/bestcomm_api.c File Reference

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
Functions | Variables
bestcomm_api.c File Reference
`#include <bsp/bestcomm/include/ppctypes.h>`
`#include <bsp/bestcomm/bestcomm_api.h>`
`#include <bsp/bestcomm/task_api/bestcomm_cntrl.h>`
`#include <bsp/bestcomm/task_api/bestcomm_api_mem.h>`
`#include <bsp/bestcomm/task_api/tasksetup_bdtable.h>`

## Functions
const char * | TaskVersion (void)
| Get a string containing API version information.
int | TasksInitAPI (uint8 *MBarRef)
| Initialize the API.
int | TasksInitAPI_VM (uint8 *MBarRef, uint8 *MBarPhys)
| Initialize the API when virtual memory is used.
int | TasksAttachImage (sdma_regs *sdma)
| Deprecated
int | TaskStart (TaskId taskId, uint32 autoStartEnable, TaskId autoStartTask, uint32 intrEnable)
| Start an initialized task running.
int | TaskStop (TaskId taskId)
| Stop a running task.
BDIdx | TaskBDAssign (TaskId taskId, void *buffer0, void *buffer1, int size, uint32 bdFlags)
| Assign a buffer to a buffer descriptor.
BDIdx | TaskBDRelease (TaskId taskId)
| Release last buffer in the buffer descriptor ring.
BDIdx | TaskBDReset (TaskId taskId)
| Release all buffers.
int | TaskDebug (TaskId taskId, TaskDebugParamSet_t *paramSet)
| Return BestComm debug information.

## Variables
uint8 * | MBarGlobal
sint64 | MBarPhysOffsetGlobal
int | TaskRunning [MAX_TASKS]

## Detailed Description

Bestcomm_api.c implements most of the BestComm C API. The TaskSetup() function is generated by the BestComm Task API tools in capi/task_api/tasksetup_general.h as configured and included by code_dma/image_rtos?/task_capi/(*).c. Other functions are defined as inline in capi/bestcomm_api.h.

## Function Documentation

## ◆ TaskBDAssign()

BDIdx TaskBDAssign | ( | TaskId | taskId,
|  | void * | buffer0,
|  | void * | buffer1,
|  | int | size,
|  | uint32 | bdFlags
| ) |  |

Assign a buffer to a buffer descriptor.

Parameters

  taskId | Task handle passed back from a successful TaskSetup()
  buffer0 | A buffer to send data from or receive data into a device
  buffer1 | A second buffer to send data from or receive data into a device for use with double-buffer tasks.
  size | Size of the buffer in bytes.
  bdFlags | Buffer descriptor flags to set. Used by ethernet BD tasks.

Returns
  Handle to the buffer descriptor used by this DMA transfer. Error is indicated by a negative return value (see TaskErr_t).

This function is used for both transmit and receive buffer descriptor tasks. The buffer may be freed by the TaskBDRelease() function. In the case of tasks with a buffer descriptor with two buffer pointers this function uses both buffer0 and buffer1 where buffer0 is a source and buffer1 is a destination. When the buffer descriptor is a single pointer type, the buffer0 is the only pointer used and buffer1 is ignored.

Using this function on non-buffer descriptor tasks will produce unpredictable results.

## ◆ TaskBDRelease()

BDIdx TaskBDRelease | ( | TaskId | taskId | ) |

Release last buffer in the buffer descriptor ring.

Parameters

  taskId | Task handle passed back from a successful TaskSetup()

Returns
  Buffer descriptor index of next buffer index that will be released by another call of this function. TASK_ERR_BD_RING_EMPTY is returned if the ring is already empty.

This function allows the system to reallocate the memory used by the buffer. It also cleans up the structure in the BD ring by removing the tail buffer in the ring. The buffer descriptor tasks are designed around this. Non-BD tasks do not use this function.

Using this function on non-buffer descriptor tasks will produce unpredictable results.

## ◆ TaskBDReset()

BDIdx TaskBDReset | ( | TaskId | taskId | ) |

Release all buffers.

Parameters

  taskId | Task handle passed back from a successful TaskSetup()

Returns
  Buffer descriptor index of next buffer that will be assigned by TaskBDAssign() which will also be the first released by the next call to TaskBDRelease() or TASK_ERR_TASK_RUNNING if the task has not been stopped.

This function is similar to TaskBDRelease() except that it releases all assigned buffers including those not yet processed by the BestComm task; i.e. SDMA_BD_MASK_READY is set. Non-BD tasks do not use this function.

The task should not be running. Call TaskStop() first.

Note: Partially transmitted buffers are up to the user to handle.

Using this function on non-buffer descriptor tasks will produce unpredictable results.

## ◆ TaskDebug()

int TaskDebug | ( | TaskId | taskId,
|  | TaskDebugParamSet_t * | paramSet
| ) |  |

Return BestComm debug information.

Parameters

  taskId | Task handle passed back from a successful TaskSetup()
  paramSet | TBD

Returns
  TBD

The implementation of this function is yet to be determined.

## ◆ TasksAttachImage()

int TasksAttachImage | ( | sdma_regs * | sdma | ) |

Deprecated

Parameters

  sdma | Base address of the BestComm register set

Returns
  TASK_ERR_NO_ERR

Use of this function is no longer necessary. It is retained for compatibility with previous versions of the API.

## ◆ TasksInitAPI()

int TasksInitAPI | ( | uint8 * | MBarRef | ) |

Initialize the API.

Parameters

  MBarRef | Reference pointer to the device register memory map.

Returns
  TASK_ERR_NO_ERR on successful initialization. or TASK_ERR_API_ALREADY_INITIALIZED.

This function is only used with physical addresses.

This function will also initialize API internal variables. The return value TASK_ERR_API_ALREADY_INITIALIZED is intended to help determine if another process has already instantiated a version of the API.

## ◆ TasksInitAPI_VM()

int TasksInitAPI_VM | ( | uint8 * | MBarRef,
|  | uint8 * | MBarPhys
| ) |  |

Initialize the API when virtual memory is used.

Parameters

  MBarRef | Reference pointer to the device register memory map.
  MBarPhys | Actual physical location of MBAR device register memory map.

Returns
  TASK_ERR_NO_ERR on successful initialization. or TASK_ERR_API_ALREADY_INITIALIZED.

This function allows using virtual memory addresses as well as physical addresses. All device registers are offset to the address supplied here, so the virtual memory space should include enough space for the entire register set of the device to include the SRAM space.

This function will also initialize API internal variables. The return value TASK_ERR_API_ALREADY_INITIALIZED is intended to help determine if another process has already instantiated a version of the API.

## ◆ TaskStart()

int TaskStart | ( | TaskId | taskId,
|  | uint32 | autoStartEnable,
|  | TaskId | autoStartTask,
|  | uint32 | intrEnable
| ) |  |

Start an initialized task running.

Parameters

  taskId | Task handle passed back from a successful TaskSetup()
  autoStartEnable | Boolean for whether autostart bit is enabled. If this is set then the parameter autoStartTask defines the task to auto start.
  autoStartTask | TaskId for task to autostart. If autoStartEnable is not set then this parameter is a don't care.
  intrEnable | Boolean for interrupt enable for this task.

Returns
  TASK_ERR_NO_ERR on success or TASK_ERR_INVALID_ARG if taskId is invalid.

## ◆ TaskStop()

int TaskStop | ( | TaskId | taskId | ) |

Stop a running task.

Parameters

  taskId | Task handle passed back from a successful TaskSetup()

Returns
  TASK_ERR_NO_ERR on success or TASK_ERR_INVALID_ARG if taskId is invalid.

Note: Stopping a polling buffer descriptor task is a catastrophic operation. It does not merely pause execution. Context is not saved. The task's pointer into the BD ring is reset back to the beginning.

Note: This is not the case for the new "fall-through" BD tasks. They save the BD ring pointer across stop/start boundaries. The previous polling tasks are considered deprecated.

## ◆ TaskVersion()

const char * TaskVersion | ( | void |  | ) |

Get a string containing API version information.

Returns
  Pointer to the API version string