#include <rtems.h>
#include "include/ppctypes.h"
#include "include/mgt5200/sdma.h"
#include "task_api/tasksetup_bdtable.h"
#include "task_api/bestcomm_cntrl.h"
#include "task_api/bestcomm_api_mem.h"
#include "bestcomm_priv.h"
#include "dma_image.capi.h"

Data Structures
struct	TaskSetupParamSet_t
	Parameters for TaskSetup() More...

struct	TaskDebugParamSet_t
	Parameters for TaskDebug() More...

struct	TaskBD_t
	Generic buffer descriptor. More...

struct	TaskBD1_t
	Single buffer descriptor. More...

struct	TaskBD2_t
	Dual buffer descriptor. More...

Macros
#define	DEBUG_BESTCOMM_API 0
	TaskSetup() debugging. More...

#define	MAX_TASKS 16
	Maximum number of tasks in the system. This number is hardware-dependent and not user configuration.

#define	DEBUG_INTR_ID SDMA_INT_BIT_DBG
	Debug interrupt "task ID".

#define	TEA_INTR_ID SDMA_INT_BIT_TEA
	TEA interrupt "task ID".

#define	TASK_AUTOSTART_ENABLE 1
	Task start autostart enable.

#define	TASK_AUTOSTART_DISABLE 0
	Task start autostart disable.

#define	TASK_INTERRUPT_ENABLE 1
	Task start interrupt enable.

#define	TASK_INTERRUPT_DISABLE 0
	Task start interrupt disable.

#define	TASK_BD_TFD (1 << SDMA_DRD_BIT_TFD)
	Transmit frame done.

#define	TASK_BD_INT (1 << SDMA_DRD_BIT_INT)
	Interrupt on frame done.

#define	TaskSetupHelper(TaskName, TaskSetupParams) TaskSetup_ ## TaskName (TaskName ## _api, TaskSetupParams)
	Initialize a single task. More...

#define	TaskSetup(TaskName, TaskSetupParams) TaskSetupHelper(TaskName, TaskSetupParams)

gpio Usage
#define	NULL ((void *)0)
	Requests a GPIO pin group configuration. More...

Typedefs
typedef sint8	TaskId

typedef sint32	BDIdx

Enumerations
enum	Sz_t { SZ_FLEX = 3, SZ_UINT8 = 1, SZ_UINT16 = 2, SZ_UINT32 = 4 }
	Data transfer size. More...

enum	TaskErr_t { TASK_ERR_NO_ERR = -1, TASK_ERR_NO_INTR = TASK_ERR_NO_ERR, TASK_ERR_INVALID_ARG = -2, TASK_ERR_BD_RING_FULL = -3, TASK_ERR_API_ALREADY_INITIALIZED = -4, TASK_ERR_SIZE_TOO_LARGE = -5, TASK_ERR_BD_RING_EMPTY = -6, TASK_ERR_BD_BUSY = -7, TASK_ERR_TASK_RUNNING = -8 }
	API error codes. More...

enum	MPC5200Initiator_t { INITIATOR_ALWAYS = 0, INITIATOR_SCTMR_0 = 1, INITIATOR_SCTMR_1 = 2, INITIATOR_FEC_RX = 3, INITIATOR_FEC_TX = 4, INITIATOR_ATA_RX = 5, INITIATOR_ATA_TX = 6, INITIATOR_SCPCI_RX = 7, INITIATOR_SCPCI_TX = 8, INITIATOR_PSC3_RX = 9, INITIATOR_PSC3_TX = 10, INITIATOR_PSC2_RX = 11, INITIATOR_PSC2_TX = 12, INITIATOR_PSC1_RX = 13, INITIATOR_PSC1_TX = 14, INITIATOR_SCTMR_2 = 15, INITIATOR_SCLPC = 16, INITIATOR_PSC5_RX = 17, INITIATOR_PSC5_TX = 18, INITIATOR_PSC4_RX = 19, INITIATOR_PSC4_TX = 20, INITIATOR_I2C2_RX = 21, INITIATOR_I2C2_TX = 22, INITIATOR_I2C1_RX = 23, INITIATOR_I2C1_TX = 24, INITIATOR_PSC6_RX = 25, INITIATOR_PSC6_TX = 26, INITIATOR_IRDA_RX = 25, INITIATOR_IRDA_TX = 26, INITIATOR_SCTMR_3 = 27, INITIATOR_SCTMR_4 = 28, INITIATOR_SCTMR_5 = 29, INITIATOR_SCTMR_6 = 30, INITIATOR_SCTMR_7 = 31 }
	BestComm initiators. More...

Functions
const char *	TaskVersion (void)
	Get a string containing API version information. More...

int	TasksInitAPI (uint8 *MBarRef)
	Initialize the API. More...

int	TasksInitAPI_VM (uint8 MBarRef, uint8 MBarPhys)
	Initialize the API when virtual memory is used. More...

void	TasksLoadImage (sdma_regs *sdma)
	Load BestComm tasks into SRAM. More...

int	TasksAttachImage (sdma_regs *sdma)
	Deprecated More...

int	TaskStart (TaskId taskId, uint32 autoStartEnable, TaskId autoStartTask, uint32 intrEnable)
	Start an initialized task running. More...

int	TaskStop (TaskId taskId)
	Stop a running task. More...

BDIdx	TaskBDAssign (TaskId taskId, void buffer0, void buffer1, int size, uint32 bdFlags)
	Assign a buffer to a buffer descriptor. More...

BDIdx	TaskBDRelease (TaskId taskId)
	Release last buffer in the buffer descriptor ring. More...

BDIdx	TaskBDReset (TaskId taskId)
	Release all buffers. More...

int	TaskDebug (TaskId taskId, TaskDebugParamSet_t *paramSet)
	Return BestComm debug information. More...

Detailed Description

Bestcomm_api.h is the only header necessary for inclusion by user code. The include path the C compiler searches to find .h files should contain bestcomm/capi and one of bestcomm/code_dma/image_*. This second entry selects which set of BestComm tasks will be used. Of course the appropriate files in image_* must also be compiled and linked.

Macro Definition Documentation

◆ DEBUG_BESTCOMM_API

#define DEBUG_BESTCOMM_API 0

TaskSetup() debugging.

Define this macro as follows for debugging printf()s to see what the API receives and sets from the TaskSetupParamSet_t struct. Implemented in capi/task_api/tasksetup_general.h.

* >0  : print basic debug messages
* >=10: also print C-API interface variables
* >=20: also print task API interface variables
* else: do nothing
*

◆ NULL

pins array is NULL ((void *)0)

Requests a GPIO pin group configuration.

Parameters

[in]	group_definition	rtems_gpio_group_definition structure filled with the group pins configurations.
[out]	group	Reference to the created group.

Return values

RTEMS_SUCCESSFUL	Pin group was configured successfully.
RTEMS_UNSATISFIED	the
*

See also: rtems_gpio_release_pin().

◆ TaskSetupHelper

#define TaskSetupHelper	(	TaskName,
		TaskSetupParams
	)	TaskSetup_ ## TaskName (TaskName ## _api, TaskSetupParams)

Initialize a single task.

Parameters

TaskName	Type of task to initialize. E.g. PCI transmit, ethernet receive, general purpose dual-pointer. Values expected can be found in the TaskName_t enum defined in dma_image.capi.h.
TaskSetupParams	Task-specific parameters. The user must fill out the pertinent parts of a TaskSetupParamSet_t data structure.

Returns: TaskId task identification token which is a required parameter for most other API functions.

This function returns a task identification token which is a required parameter for most other API functions.

Certain values of the structure pointed to by TaskParams are set as a side-effect based on task type. These may be examined after a successful call to TaskSetup(). User-specified values may be overridden.

TaskId TaskSetup( TaskName_t TaskName, TaskSetupParamSet_t *TaskSetupParams );

Enumeration Type Documentation

◆ MPC5200Initiator_t

enum MPC5200Initiator_t

BestComm initiators.

These are assigned by TaskSetup().

◆ Sz_t

enum Sz_t

Data transfer size.

Enumerator
SZ_FLEX	invalid for TaskSetupParamSet_t
SZ_UINT8	1-byte
SZ_UINT16	2-byte
SZ_UINT32	4-byte

◆ TaskErr_t

enum TaskErr_t

API error codes.

Enumerator
TASK_ERR_NO_ERR	No error
TASK_ERR_NO_INTR	No interrupt
TASK_ERR_INVALID_ARG	Invalid function argument
TASK_ERR_BD_RING_FULL	Buffer descriptor ring full
TASK_ERR_API_ALREADY_INITIALIZED	API has already been initialized
TASK_ERR_SIZE_TOO_LARGE	Buffer descriptor cannot support size parameter
TASK_ERR_BD_RING_EMPTY	Buffer descriptor ring is empty
TASK_ERR_BD_BUSY	The buffer descriptor is in use by the BestComm
TASK_ERR_TASK_RUNNING	The task is running.

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.

◆ TasksLoadImage()

void TasksLoadImage ( sdma_regs * sdma )

Load BestComm tasks into SRAM.

Parameters

sdma	Base address of the BestComm register set

The BestComm tasks must be loaded before any task can be setup, enabled, etc. This might be called as part of a boot sequence before any BestComm drivers are required.

◆ 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

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ DEBUG_BESTCOMM_API

◆ NULL

◆ TaskSetupHelper

Enumeration Type Documentation

◆ MPC5200Initiator_t

◆ Sz_t

◆ TaskErr_t

Function Documentation

◆ TaskBDAssign()

◆ TaskBDRelease()

◆ TaskBDReset()

◆ TaskDebug()

◆ TasksAttachImage()

◆ TasksInitAPI()

◆ TasksInitAPI_VM()

◆ TasksLoadImage()

◆ TaskStart()

◆ TaskStop()

◆ TaskVersion()