BIOS.h File Reference

Detailed Description

SYS/BIOS Top-Level Manager.

This module is responsible for setting up global parameters pertaining to SYS/BIOS and for performing the SYS/BIOS startup sequence.

The SYS/BIOS startup sequence is logically divided into two phases: those operations that occur prior to the application's "main()" function being called, and those operations that are performed after the application's "main()" function is invoked.

The "before main()" startup sequence is governed completely by the ti/sysbios/runtime/Startup module.

The "after main()" startup sequence is governed by SYS/BIOS and is initiated by an explicit call to the BIOS_start function at the end of the application's main() function.

Control points are provided at various places in each of the two startup sequences for user startup operations to be inserted.

The RTSC runtime startup sequence is as follows:

• Immediately after CPU reset, perform target-specific CPU initialization (beginning at c_int00).
• Prior to cinit(), run the user-supplied "reset functions"
• Run cinit() to initialize C runtime environment.
• Run the user-supplied "first functions"
• Run all the module initialization functions.
• Run pinit().
• Run the user-supplied "last functions"
• Run * main().

The SYS/BIOS startup sequence begins at the end of main() when BIOS_start() is called:

• Run the user-supplied "startup functions"
• Enable Hardware Interrupts.
• Enable Software Interrupts. If the system supports Software Interrupts (Swis) (via the BIOS.swiEnabled configuration parameter), then the SYS/BIOS startup sequence enables Swis at this point.
• Timer Startup. If the system supports Timers, then at this point all statically configured timers are initialized per their user-configuration. If a timer was configured to start "automatically", it is started here.
• Task Startup. If the system supports Tasks (via the BIOS.taskEnabled configuration parameter), then task scheduling begins here. If there are no statically or dynamically created Tasks in the system, then execution proceeds directly to the Idle loop.

Warning

Local variables defined in main() no longer exist once BIOS_start() is called. The RAM where main's local variables reside is reassigned for use as the interrupt stack during the execution of BIOS_start().

Below is a configuration script excerpt that installs a user-supplied startup function at every possible control point in the RTSC and SYS/BIOS startup sequence:

// get handle to xdc Startup module
var Startup = xdc.useModule('xdc.runtime.Startup');

// install "reset function"
Startup.resetFxn = '&myReset';

// install a "first function"
var len = Startup.firstFxns.length
Startup.firstFxns.length++;
Startup.firstFxns[len] = '&myFirst';

// install a "last function"
var len = Startup.lastFxns.length
Startup.lastFxns.length++;
Startup.lastFxns[len] = '&myLast';

// get handle to SYS/BIOS module
var BIOS = xdc.useModule('ti.sysbios.BIOS');

// install a SYS/BIOS startup function
BIOS.addUserStartupFunction('&myBiosStartup');

Calling Context

Function	Hwi	Swi	Task	Main	Startup
getCpuFreq	Y	Y	Y	Y	Y
getThreadType	Y	Y	Y	Y	N
setCpuFreq	Y	Y	Y	Y	Y
start	N	N	N	Y	N
Definitions: Hwi: API is callable from a Hwi thread. Swi: API is callable from a Swi thread. Task: API is callable from a Task thread. Main: API is callable during any of these phases: In your module startup after this module is started (e.g. BIOS_Module_startupDone() returns true). During xdc.runtime.Startup.lastFxns. During main(). During BIOS.startupFxns. Startup: API is callable during any of these phases: During xdc.runtime.Startup.firstFxns. In your module startup before this module is started (e.g. BIOS_Module_startupDone() returns false).

#include <xdc/std.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/sysbios/runtime/Types.h>

Include dependency graph for BIOS.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	ti_sysbios_BIOS_version   (0x70000)
#define	BIOS_WAIT_FOREVER   (~(0U))
	Used in APIs that take a timeout to specify wait forever. More...
#define	BIOS_NO_WAIT   (0U)
	Used in APIs that take a timeout to specify no waiting. More...

Typedefs
typedef enum BIOS_ThreadType	BIOS_ThreadType
typedef enum BIOS_RtsLockType	BIOS_RtsLockType
typedef void(*	BIOS_StartupFuncPtr) (void)
	User startup function type definition. More...
typedef void(*	BIOS_StartFuncPtr) (void)
typedef void(*	BIOS_ExitFuncPtr) (int arg1)

Enumerations
enum	BIOS_ThreadType {   BIOS_ThreadType_Hwi,   BIOS_ThreadType_Swi,   BIOS_ThreadType_Task,   BIOS_ThreadType_Main }
	Current thread type definitions. More...
enum	BIOS_RtsLockType {   BIOS_NoLocking,   BIOS_GateHwi,   BIOS_GateSwi,   BIOS_GateMutex,   BIOS_GateMutexPri }
	Type of Gate to use in the TI RTS library. More...

Functions
void	BIOS_start (void)
	Start SYS/BIOS. More...
void	BIOS_exit (int stat)
	Exit currently running SYS/BIOS executable. More...
BIOS_ThreadType	BIOS_getThreadType (void)
	Get the current thread type. More...
void	BIOS_setCpuFreq (Types_FreqHz *freq)
	Set CPU Frequency in Hz. More...
void	BIOS_getCpuFreq (Types_FreqHz *freq)
	Get CPU frequency in Hz. More...

Variables
const Types_FreqHz	BIOS_cpuFreq
	CPU frequency in Hz. More...
const bool	BIOS_taskEnabled
	SYS/BIOS Task services enable flag. More...
const bool	BIOS_swiEnabled
	SYS/BIOS Swi services enable flag. More...
const bool	BIOS_clockEnabled
	SYS/BIOS Clock services enable flag. More...
const size_t	BIOS_heapSize
	Size of system heap, units are in MAUs. More...
const bool	BIOS_heapTrackEnabled
	Use HeapTrack with system default heap. More...

Macro Definition Documentation

ti_sysbios_BIOS_version

#define ti_sysbios_BIOS_version   (0x70000)

BIOS_WAIT_FOREVER

#define BIOS_WAIT_FOREVER   (~(0U))

Used in APIs that take a timeout to specify wait forever.

BIOS_NO_WAIT

#define BIOS_NO_WAIT   (0U)

Used in APIs that take a timeout to specify no waiting.

Typedef Documentation

BIOS_ThreadType

typedef enum BIOS_ThreadType BIOS_ThreadType

BIOS_RtsLockType

typedef enum BIOS_RtsLockType BIOS_RtsLockType

BIOS_StartupFuncPtr

typedef void(* BIOS_StartupFuncPtr) (void)

User startup function type definition.

BIOS_StartFuncPtr

typedef void(* BIOS_StartFuncPtr) (void)

BIOS_ExitFuncPtr

typedef void(* BIOS_ExitFuncPtr) (int arg1)

Enumeration Type Documentation

BIOS_ThreadType

enum BIOS_ThreadType

Current thread type definitions.

These values are returned by BIOS_getThreadType.

See also

BIOS_getThreadType

Enumerator
BIOS_ThreadType_Hwi
BIOS_ThreadType_Swi
BIOS_ThreadType_Task
BIOS_ThreadType_Main

BIOS_RtsLockType

enum BIOS_RtsLockType

Type of Gate to use in the TI RTS library.

See also

BIOS_rtsGateType

Enumerator
BIOS_NoLocking	No gate is added to the RTS library. In this case, the application needs to be careful to always serialize access to the inherently non-reentrant ANSI C functions (such as malloc(), printf(), etc.).
BIOS_GateHwi	Interrupts are disabled and restored to maintain re-entrancy. This is a very efficient lock but will also result in unbounded interrupt latency times. If real-time response to interrupts is important, you should not use this gate to lock the RTS library.
BIOS_GateSwi	Swis are disabled and restored to maintain re-entrancy.
BIOS_GateMutex	A single mutex is used to maintain re-entrancy.
BIOS_GateMutexPri	A single priority inheriting mutex is used to maintain re-entrancy.

Function Documentation

BIOS_start()

void BIOS_start

(

void

)

Start SYS/BIOS.

The user's main() function is required to call this function after all other user initializations have been performed.

This function does not return.

This function performs any remaining SYS/BIOS initializations and then transfers control to the highest priority ready task if BIOS_taskEnabled is true. If BIOS_taskEnabled is false, control is transferred directly to the Idle Loop.

The SYS/BIOS start sequence is as follows:

• Invoke all the functions in the BIOS_startupFxns array.
• call Hwi_startup() to enable interrupts.
• if BIOS_swiEnabled is true, call Swi_startup() to enable the Swi scheduler.
• Start any statically created or constructed Timers in the Timer_StartMode_AUTO mode.
• if BIOS_taskEnabled is true, enable the Task scheduler and transfer the execution thread to the highest priority task in the Task_Mode_READY mode.
• Otherwise, fall directly into the Idle Loop.

BIOS_exit()

void BIOS_exit

(

int

stat

)

Exit currently running SYS/BIOS executable.

This function is called when a SYS/BIOS executable needs to terminate normally. This function sets the internal SYS/BIOS threadType to BIOS_ThreadType_Main and then calls System_exit passing along the 'stat' argument.

All functions bound via System_atexit or the ANSI C Standard Library atexit function are then executed.

Parameters

stat	exit status to return to calling environment.

BIOS_getThreadType()

BIOS_ThreadType BIOS_getThreadType

(

void

)

Get the current thread type.

Return values

Current

thread type

BIOS_setCpuFreq()

void BIOS_setCpuFreq

(

Types_FreqHz *

freq

)

Set CPU Frequency in Hz.

This API is not thread safe. Please use appropriate locks.

BIOS_getCpuFreq()

void BIOS_getCpuFreq

(

Types_FreqHz *

freq

)

Get CPU frequency in Hz.

This API is not thread safe. Please use appropriate locks.

Variable Documentation

BIOS_cpuFreq

const Types_FreqHz BIOS_cpuFreq

CPU frequency in Hz.

This configuration parameter allows SYS/BIOS to convert various periods between timer ticks (or instruction cycles) and real-time units. For example, timer periods expressed in micro-seconds need to be converted into timer ticks in order to properly program the timers.

Example

If CPU frequency is 100MHz, the following configuration script configures SYS/BIOS with the proper clock frequency:

var BIOS = xdc.useModule('ti.sysbios.BIOS');
BIOS.cpuFreq.hi = 0;
BIOS.cpuFreq.lo = 100000000;

BIOS_taskEnabled

const bool BIOS_taskEnabled

SYS/BIOS Task services enable flag.

The following behaviors occur when BIOS_taskEnabled is set to false:

• Static Task creation will result in a fatal build error.
• The Idle task object is not created. (The Idle functions are invoked within the BIOS_start() thread.)
• Runtime calls to Task_create will trigger an assertion violation via xdc.runtime.Assert::isTrue.

BIOS_swiEnabled

const bool BIOS_swiEnabled

SYS/BIOS Swi services enable flag.

The following behaviors occur when BIOS_swiEnabled is set to false:

• Static Swi creation will result in a fatal build error.
• See other effects as noted for BIOS_clockEnabled = false;
• Runtime calls to Swi_create will trigger an assertion violation

BIOS_clockEnabled

const bool BIOS_clockEnabled

SYS/BIOS Clock services enable flag.

The following behaviors occur when BIOS_clockEnabled is set to false:

• Static Clock creation will result in a fatal build error.
• No Clock Swi is created.
• The Clock_tickSource is set to Clock_TickSource_NULL to prevent a Timer object from being created.
• For APIs that take a timeout, values other than BIOS_NO_WAIT will be equivalent to BIOS_WAIT_FOREVER.

BIOS_heapSize

const size_t BIOS_heapSize

Size of system heap, units are in MAUs.

The system heap is, by default, used to allocate instance object state structures, such as Task objects and their stacks, Semaphore objects, etc.

BIOS_heapTrackEnabled

const bool BIOS_heapTrackEnabled

Use HeapTrack with system default heap.

This configuration parameter will add a HeapTrack instance on top of the system heap. HeapTrack adds a tracker packet to every allocated buffer and displays the information in RTOS Object Viewer (ROV). An assert will be raised on a free if there was a buffer overflow.