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.
Control points are provided at various places in each of the two startup
sequences for user startup operations to be inserted.
The SYS/BIOS startup sequence begins at the end of main() when
BIOS_start() is called:
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:
const BIOS_NO_WAIT |
|
Used in APIs that take a timeout to specify no waiting
#define BIOS_NO_WAIT (UInt)0
const BIOS_WAIT_FOREVER |
|
Used in APIs that take a timeout to specify wait forever
#define BIOS_WAIT_FOREVER (UInt)~(0)
enum BIOS_LibType |
|
SYS/BIOS library selection options
typedef enum BIOS_LibType {
BIOS_LibType_Instrumented,
// Instrumented (Asserts and Logs enabled)
BIOS_LibType_NonInstrumented,
// Non-instrumented (Asserts and Logs disabled)
BIOS_LibType_Custom,
// Custom (Fully configurable)
BIOS_LibType_Debug
// Debug (Fully configurable)
} BIOS_LibType;
VALUES
LibType_Instrumented
The library supplied is prebuilt with
logging and assertions enabled.
LibType_NonInstrumented
The library supplied is prebuilt
with logging and assertions disabled.
LibType_Custom
This option builds the
SYS/BIOS library from sources using the options specified by
customCCOpts. Only the modules and APIs that your application
needs to access are contained in the resulting executable. Program
optimization is performed to reduce the size of the executable and improve
its performance. Enough debug information is retained to allow you to
step through the application code in CCS and locate global variables.
LibType_Debug
This option is similar to the LibType_Custom option
in that it builds the SYS/BIOS library from sources and omits modules and
APIs that your code does not use. However, no program
optimization is performed. The resulting executable is fully debuggable,
and you can step into SYS/BIOS code. The tradeoff is that the executable
is larger and runs slower than builds that use the LibType_Custom option.
DETAILS
This enumeration defines all the SYS/BIOS library types
provided by the product. You can select the library type by setting
the
BIOS.libType configuration parameter.
SEE
enum BIOS_RtsLockType |
|
Type of Gate to use in the TI RTS library
typedef enum BIOS_RtsLockType {
BIOS_NoLocking,
BIOS_GateHwi,
BIOS_GateSwi,
BIOS_GateMutex,
BIOS_GateMutexPri
} BIOS_RtsLockType;
VALUES
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.).
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.
GateSwi
Swis are disabled and restored to maintain
re-entrancy.
GateMutex
A single mutex is used to maintain re-entrancy.
GateMutexPri
A single priority inheriting mutex is used to
maintain re-entrancy.
SEE
enum BIOS_ThreadType |
|
Current thread type definitions
typedef enum BIOS_ThreadType {
BIOS_ThreadType_Hwi,
// Current thread is a Hwi
BIOS_ThreadType_Swi,
// Current thread is a Swi
BIOS_ThreadType_Task,
// Current thread is a Task
BIOS_ThreadType_Main
// Current thread is Boot/Main
} BIOS_ThreadType;
DETAILS
These values are returned by
BIOS_getThreadType.
SEE
typedef BIOS_StartupFuncPtr |
|
User startup function type definition
typedef Void (*BIOS_StartupFuncPtr)(Void);
config BIOS_clockEnabled // module-wide |
|
SYS/BIOS Clock services enable flag
extern const Bool BIOS_clockEnabled;
DETAILS
The following behaviors occur when
clockEnabled is
set to false:
config BIOS_cpuFreq // module-wide |
|
CPU frequency in Hz
DETAILS
This configuration parameter allow 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.
The default value of this parameter is obtained from the platform
(the clockRate property of
Program.cpu)
which is the CPU clock rate when the processor is reset.
EXAMPLE
If CPU frequency is 720MHz, 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 = 720000000;
config BIOS_heapSection // module-wide |
|
Section to place the system heap
extern const String BIOS_heapSection;
DETAILS
This configuration parameter allows you to specify a named output
section that will contain the SYS/BIOS system heap. The system heap
is, by default, used to allocate
Task
stacks and instance object state structures. So, giving this section
a name and explicitly placing it via a linker command file can
significantly improve system performance.
If heapSection is null (or undefined) the system heap is placed
in the target's default data section.
config BIOS_heapSize // module-wide |
|
Size of system heap, units are in MAUs
extern const SizeT BIOS_heapSize;
DETAILS
The system heap is, by default, used to allocate instance object
state structures, such as
Task objects
and their stacks,
Semaphore objects,
etc.
If the application configuration does not set
Memory.defaultHeapInstance, then SYS/BIOS will create a
HeapMem heap of this size. This
heap will be assigned to
Memory.defaultHeapInstance
and will therefore be used as the default system heap. This heap
will also be used by the SYS/BIOS version of the standard C library
functions malloc(), calloc() and free().
config BIOS_heapTrackEnabled // module-wide |
|
Use HeapTrack with system default heap
extern const Bool BIOS_heapTrackEnabled;
DETAILS
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.
config BIOS_runtimeCreatesEnabled // module-wide |
|
Runtime instance creation enable flag
extern const Bool BIOS_runtimeCreatesEnabled;
DETAILS
true = Mod_create() & Mod_delete() callable at runtime
false = Mod_create() & Mod_delete() not callable at runtime
config BIOS_smpEnabled // module-wide |
|
Enables multi core SMP task scheduling
extern const Bool BIOS_smpEnabled;
DETAILS
Currently, this functionality is only supported on the dual core
Cortex M3/M4 Ducati/Benelli subsystems embedded in several TI
SOC devices.
More information about SMP/BIOS is provided here:
SMP/BIOS.
config BIOS_swiEnabled // module-wide |
|
SYS/BIOS Swi services enable flag
extern const Bool BIOS_swiEnabled;
DETAILS
The following behaviors occur when
swiEnabled is
set to false:
- Static Swi creation will
result in a fatal build error.
- See other effects as noted for clockEnabled = false;
- Runtime calls to Swi_create will trigger an assertion violation
via xdc.runtime.Assert.isTrue.
config BIOS_taskEnabled // module-wide |
|
SYS/BIOS Task services enable flag
extern const Bool BIOS_taskEnabled;
DETAILS
The following behaviors occur when
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 start()
thread.)
- Runtime calls to Task_create will trigger an assertion violation
via xdc.runtime.Assert.isTrue.
BIOS_exit() // module-wide |
|
Exit currently running SYS/BIOS executable
Void BIOS_exit(Int stat);
ARGUMENTS
stat
exit status to return to calling environment.
DETAILS
This function is called when a SYS/BIOS executable needs to terminate
normally. This function sets the internal SYS/BIOS threadType to
ThreadType_Main and then calls
System_exit(stat), passing along
the 'stat' argument.
All functions bound via
System_atexit or the ANSI C
Standard Library
atexit function are then executed.
BIOS_getCpuFreq() // module-wide |
|
Get CPU frequency in Hz
DETAILS
This API is not thread safe. Please use appropriate locks.
BIOS_getThreadType() // module-wide |
|
Get the current thread type
RETURNS
Current thread type
BIOS_setCpuFreq() // module-wide |
|
Set CPU Frequency in Hz
DETAILS
This API is not thread safe. Please use appropriate locks.
BIOS_start() // module-wide |
|
Start SYS/BIOS
DETAILS
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
taskEnabled is true. If
taskEnabled
is false, control is transferred directly to the Idle Loop.
The SYS/BIOS start sequence is as follows:
Module-Wide Built-Ins |
|
// Get this module's unique id
Bool BIOS_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool BIOS_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 BIOS_Module_getMask();
// Returns the diagnostics mask for this module
Void BIOS_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
const BIOS.NO_WAIT |
|
Used in APIs that take a timeout to specify no waiting
C SYNOPSIS
const BIOS.WAIT_FOREVER |
|
Used in APIs that take a timeout to specify wait forever
const BIOS.WAIT_FOREVER = ~(0);
C SYNOPSIS
enum BIOS.LibType |
|
SYS/BIOS library selection options
values of type BIOS.LibType
const BIOS.LibType_Instrumented;
// Instrumented (Asserts and Logs enabled)
const BIOS.LibType_NonInstrumented;
// Non-instrumented (Asserts and Logs disabled)
const BIOS.LibType_Custom;
// Custom (Fully configurable)
const BIOS.LibType_Debug;
// Debug (Fully configurable)
VALUES
LibType_Instrumented
The library supplied is prebuilt with
logging and assertions enabled.
LibType_NonInstrumented
The library supplied is prebuilt
with logging and assertions disabled.
LibType_Custom
This option builds the
SYS/BIOS library from sources using the options specified by
customCCOpts. Only the modules and APIs that your application
needs to access are contained in the resulting executable. Program
optimization is performed to reduce the size of the executable and improve
its performance. Enough debug information is retained to allow you to
step through the application code in CCS and locate global variables.
LibType_Debug
This option is similar to the LibType_Custom option
in that it builds the SYS/BIOS library from sources and omits modules and
APIs that your code does not use. However, no program
optimization is performed. The resulting executable is fully debuggable,
and you can step into SYS/BIOS code. The tradeoff is that the executable
is larger and runs slower than builds that use the LibType_Custom option.
DETAILS
This enumeration defines all the SYS/BIOS library types
provided by the product. You can select the library type by setting
the
BIOS.libType configuration parameter.
SEE
C SYNOPSIS
enum BIOS.RtsLockType |
|
Type of Gate to use in the TI RTS library
values of type BIOS.RtsLockType
const BIOS.NoLocking;
const BIOS.GateHwi;
const BIOS.GateSwi;
const BIOS.GateMutex;
const BIOS.GateMutexPri;
VALUES
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.).
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.
GateSwi
Swis are disabled and restored to maintain
re-entrancy.
GateMutex
A single mutex is used to maintain re-entrancy.
GateMutexPri
A single priority inheriting mutex is used to
maintain re-entrancy.
SEE
C SYNOPSIS
enum BIOS.ThreadType |
|
Current thread type definitions
values of type BIOS.ThreadType
const BIOS.ThreadType_Hwi;
// Current thread is a Hwi
const BIOS.ThreadType_Swi;
// Current thread is a Swi
const BIOS.ThreadType_Task;
// Current thread is a Task
const BIOS.ThreadType_Main;
// Current thread is Boot/Main
DETAILS
These values are returned by
BIOS_getThreadType.
SEE
C SYNOPSIS
config BIOS.clockEnabled // module-wide |
|
SYS/BIOS Clock services enable flag
BIOS.clockEnabled = Bool true;
DETAILS
The following behaviors occur when
clockEnabled is
set to false:
C SYNOPSIS
config BIOS.cpuFreq // module-wide |
|
CPU frequency in Hz
DETAILS
This configuration parameter allow 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.
The default value of this parameter is obtained from the platform
(the clockRate property of
Program.cpu)
which is the CPU clock rate when the processor is reset.
EXAMPLE
If CPU frequency is 720MHz, 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 = 720000000;
C SYNOPSIS
config BIOS.heapSection // module-wide |
|
Section to place the system heap
BIOS.heapSection = String null;
DETAILS
This configuration parameter allows you to specify a named output
section that will contain the SYS/BIOS system heap. The system heap
is, by default, used to allocate
Task
stacks and instance object state structures. So, giving this section
a name and explicitly placing it via a linker command file can
significantly improve system performance.
If heapSection is null (or undefined) the system heap is placed
in the target's default data section.
C SYNOPSIS
config BIOS.heapSize // module-wide |
|
Size of system heap, units are in MAUs
BIOS.heapSize = SizeT 0x1000;
DETAILS
The system heap is, by default, used to allocate instance object
state structures, such as
Task objects
and their stacks,
Semaphore objects,
etc.
If the application configuration does not set
Memory.defaultHeapInstance, then SYS/BIOS will create a
HeapMem heap of this size. This
heap will be assigned to
Memory.defaultHeapInstance
and will therefore be used as the default system heap. This heap
will also be used by the SYS/BIOS version of the standard C library
functions malloc(), calloc() and free().
C SYNOPSIS
config BIOS.heapTrackEnabled // module-wide |
|
Use HeapTrack with system default heap
BIOS.heapTrackEnabled = Bool false;
DETAILS
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.
C SYNOPSIS
config BIOS.runtimeCreatesEnabled // module-wide |
|
Runtime instance creation enable flag
BIOS.runtimeCreatesEnabled = Bool true;
DETAILS
true = Mod_create() & Mod_delete() callable at runtime
false = Mod_create() & Mod_delete() not callable at runtime
C SYNOPSIS
config BIOS.smpEnabled // module-wide |
|
Enables multi core SMP task scheduling
BIOS.smpEnabled = Bool false;
DETAILS
Currently, this functionality is only supported on the dual core
Cortex M3/M4 Ducati/Benelli subsystems embedded in several TI
SOC devices.
More information about SMP/BIOS is provided here:
SMP/BIOS.
C SYNOPSIS
config BIOS.swiEnabled // module-wide |
|
SYS/BIOS Swi services enable flag
BIOS.swiEnabled = Bool true;
DETAILS
The following behaviors occur when
swiEnabled is
set to false:
- Static Swi creation will
result in a fatal build error.
- See other effects as noted for clockEnabled = false;
- Runtime calls to Swi_create will trigger an assertion violation
via xdc.runtime.Assert.isTrue.
C SYNOPSIS
config BIOS.taskEnabled // module-wide |
|
SYS/BIOS Task services enable flag
BIOS.taskEnabled = Bool true;
DETAILS
The following behaviors occur when
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 start()
thread.)
- Runtime calls to Task_create will trigger an assertion violation
via xdc.runtime.Assert.isTrue.
C SYNOPSIS
metaonly config BIOS.assertsEnabled // module-wide |
|
SYS/BIOS Assert checking in Custom SYS/BIOS library enable flag
BIOS.assertsEnabled = Bool true;
DETAILS
When set to true, Assert checking code is compiled into
the custom library created when
BIOS.libType
is set to
BIOS_LibType_Custom or
BIOS_LibType_Debug.
When set to false, Assert checking code is removed from
the custom library created when BIOS.libType is set to BIOS.LibType_Custom
or BIOS.LibType_Debug.
This option can considerably improve runtime performance as well
significantly reduce the application's code size.
metaonly config BIOS.common$ // module-wide |
|
Common module configuration parameters
DETAILS
All modules have this configuration parameter. Its name
contains the '$' character to ensure it does not conflict with
configuration parameters declared by the module. This allows
new configuration parameters to be added in the future without
any chance of breaking existing modules.
metaonly config BIOS.customCCOpts // module-wide |
|
Compiler options used when building a custom SYS/BIOS library
BIOS.customCCOpts = String undefined;
DETAILS
When
BIOS.libType is set to
BIOS_LibType_Custom or
BIOS_LibType_Debug,
this string contains the options passed to the compiler during any
re-build of the SYS/BIOS sources.
In addition to the options
specified by BIOS.customCCOpts, several -D and -I options are also
passed to the compiler. The options specified by BIOS.customCCOpts are,
however, the first options passed to the compiler on the command line.
To view the custom compiler options, add the following line to your
config script:
print(BIOS.customCCOpts);
When
BIOS.libType is set to
BIOS_LibType_Custom,
BIOS.customCCOpts is initialized to settings that create a highly
optimized SYS/BIOS library.
When
BIOS.libType is set to
BIOS_LibType_Debug,
BIOS.customCCOpts is initialized to settings that create a non-optimized
SYS/BIOS library that can be used to single-step through the APIs with
the CCS debugger.
More information about using
BIOS.customCCOpts is provided in the
SYS/BIOS FAQs.
WARNING
The default value of BIOS.customCCOpts, which is derived from the target
specified by your configuration, includes runtime model options
(such as endianess) that must be the same for all sources built and
linked into your application. You must not change or add any options
that can alter the runtime model specified by the default value of
BIOS.customCCOpts.
metaonly config BIOS.libType // module-wide |
|
SYS/BIOS Library type
DETAILS
The SYS/BIOS runtime is provided in the form of a library that is
linked with your application. Several forms of this library are
provided with the SYS/BIOS product. In addition, there is an
option to build the library from source. This configuration parameter
allows you to select the form of the SYS/BIOS library to use.
The default value of libType is
BIOS_LibType_Instrumented. For a
complete list of options and what they offer see
LibType.
metaonly config BIOS.logsEnabled // module-wide |
|
SYS/BIOS Log support in Custom SYS/BIOS library enable flag
BIOS.logsEnabled = Bool true;
DETAILS
When set to true, SYS/BIOS execution Log code is compiled into
the custom library created when
BIOS.libType
is set to
BIOS_LibType_Custom or
BIOS_LibType_Debug.
When set to false, all Log code is removed from
the custom library created when BIOS.libType = BIOS.LibType_Custom
or BIOS.LibType_Debug.
This option can considerably improve runtime performance as well
significantly reduce the application's code size.
metaonly config BIOS.rtsGateType // module-wide |
|
Gate to make sure TI RTS library APIs are re-entrant
DETAILS
The application gets to determine the type of gate (lock) that is used
in the TI RTS library. The gate will be used to guarantee re-entrancy
of the RTS APIs.
The type of gate depends on the type of threads that are going to
be calling into the RTS library. For example, if both Swi and Task
threads are going to be calling the RTS library's printf, GateSwi
should be used. In this case, Hwi threads are not impacted (i.e.
disabled) during the printf calls from the Swi or Task threads.
If NoLocking is used, the RTS lock is not plugged and re-entrancy for
the TI RTS library calls are not guaranteed. The application can plug
the RTS locks directly if it wants.
Numerous gate types are provided by SYS/BIOS. Each has its advantages
and disadvantages. The following list summarizes when each type is
appropriate for protecting an underlying non-reentrant RTS library.
- GateHwi:
-
Interrupts are disabled and restored to maintain re-entrancy.
Use if only making RTS calls from a Hwi, Swi and/or Task.
- GateSwi:
-
Swis are disabled and restored to maintain re-entrancy. Use if
only making RTS calls from a Swi and/or Task.
- GateMutex:
-
A single mutex is used to maintain re-entrancy. Use if only
making RTS calls from a Task. Blocks only Tasks that are
also trying to execute critical regions of RTS library.
- GateMutexPri:
-
A priority inheriting mutex is used to maintain re-entrancy.
Blocks only Tasks that are also trying to execute critical
regions of RTS library. Raises the priority of the Task that
is executing the critical region in the RTS library to the
level of the highest priority Task that is block by the mutex.
The default value of rtsGateType depends on the type of threading
model enabled by other configuration parameters.
If
taskEnabled is true,
GateMutex is used.
If
swiEnabled is true and
taskEnabled is false:
GateSwi is used.
If both
swiEnabled and
taskEnabled are false:
xdc.runtime.GateNull is used.
If
taskEnabled is false, the user should not select
GateMutex (or other Task level gates). Similarly, if
taskEnabled and
swiEnabledare false, the user
should not select
GateSwi or the Task level gates.
metaonly config BIOS.startupFxns // module-wide |
|
Functions to be executed at the beginning of BIOS_start()
DETAILS
These user (or middleware) functions are executed before Hwis,
Swis, and Tasks are started.