2023年12月7日发(作者：)
1
STAPI介绍
一、 定义
1、API：Application Programming Interface
应用编程接口
2、 STAPI: ST Application Programming Interface
ST应用编程接口,即为方便应用程序调用ST Drivers实现各种需求而提供的接口函数等。
二、 简介
1 The Initialization function
1.1 Prototype：
ST_ErrorCode_t STXXXXX_Init(const ST_DeviceName DeviceName,
const STXXXXX_InitParams_t* InitParams);
1.2 The initialization function will typically do some or all
of the following:
• Create and initialize all internal memory structures.
• Associate the DeviceName with the hardware device or
component usually identified by the BaseAddress in the
InitParams.
• Process and store the elements of InitParams.
• Install an internal interrupt handler using the interrupt
number and level specified in the InitParams.
• Check accessibility and functionality of the hardware device
and set to a default state
1 2
• Return an error code.
1.3 The following table lists the error codes commonly
returned by the STXXXXX_Init() unction.
ST_NO_ERROR： No errors occurred
ST_ERROR_ALREADY_INITIALIZED： Another user has already
initialized the device
ST_ERROR_BAD_PARAMETER： One or more of the parameters was
invalid
ST_ERROR_NO_MEMORY： Unable to allocate memory
ST_ERROR_REVISION_NOT_SUPPORTED： The API revision used by the
caller is not supported by this driver (ie caller API revision
is greater than driver API revision).
ST_ERROR_INTERRUPT_ENABLE： Error enabling interrupts for the
API’s internal interrupt handler
ST_ERROR_INTERRUPT_INSTALL：Error installing interrupts for
the API’s internal interrupt handler
ST_ERROR_FEATURE_NOT_SUPPORTED： The device type or feature is
not supported
2 The Open function
2.1 Prototype：
ST_ErrorCode_t STXXXXX_Open(const ST_DeviceName DeviceName,
2 3
const STXXXXX_OpenParams_t * OpenParams,
ST_Handle_t * Handle);
2.2 The open function will typically do some or all of the
following:
• Use the DeviceName to identify the hardware device.
• Process and store the elements of OpenParams.
• Enable any internal interrupt handler.
• Check accessibility and functionality of the hardware device
and set to a state defined in the OpenParams.
• Return a Handle which is the mechanism by which subsequent
access and control functions identify the caller. The
STXXXXX_Open() function is the only function returning a
Handle.
• Return an error code.
2.3 The following table lists the error codes commonly
returned by the STXXXXX_Open() function.
ST_NO_ERROR： No error has occurred
ST_ERROR_UNKNOWN_DEVICE： Invalid device name
ST_ERROR_NO_FREE_HANDLES： The maximum number of allocated
handles are in use; cannot allocate another handle
ST_ERROR_FEATURE_NOT_SUPPORTED： The required mode or feature
is not supported
3 4
ST_ERROR_BAD_PARAMETER： One or more of the parameters was
invalid
ST_ERROR_DEVICE_BUSY： Another user has already opened the
device, or the device is in use
3 Access and control functions
The majority of functions fall into this category. Almost all
APIs manage access to these functions by the Handle obtained
in the STXXXXX_Open() function.
These functions are, naturally, dependant on the device
supported by the API.
4 The Close function
4.1
Prototype：
ST_ErrorCode_t STXXXXX_Close(ST_Handle_t Handle);
4.2 The following table lists the error codes commonly
returned by the STXXXXX_Close() function.
ST_NO_ERROR： No error has occurred
ST_ERROR_INVALID_HANDLE： Device handle invalid
5 The Termination function
5.1
Prototype：
4 5
ST_ErrorCode_t STXXXXX_Term(const ST_DeviceName DeviceName,
const STXXXXX_TermParams_t* TermParams);
5.2 The termination function will typically do some or all of
the following:
• If directed, close any open Handles; otherwise return an error
indicating that not all Handles have been closed.
• Process the elements of TermParams.
• Destroy all internal memory structures.
• Uninstall any internal interrupt handler.
5.3 The following table lists the error codes commonly
returned by the STXXXXX_Term() function.
ST_NO_ERROR： No error has occurred
ST_ERROR_INVALID_HANDLE： Device handle invalid
ST_ERROR_BAD_PARAMETER： One or more of the parameters was
invalid
ST_ERROR_UNKNOWN_DEVICE：The device has not been initialized
ST_ERROR_OPEN_HANDLE： Could not terminate driver; not all
handles have been closed
ST_ERROR_INTERRUPT_DISABLE： Error disabling interrupts for
the API’s internal interrupt handler
ST_ERROR_INTERRUPT_UNINSTALL： Error uninstalling interrupts
for the API’s internal interrupt handler
5 6
6 The GetRevision function
6.1
Prototype：
ST_Revision_t STXXXXX_GetRevision(void);
6.2
The STXXXXX_GetRevision() function provides information
about the revision of an individual API
7 Callback functions
Callback functions are used as the standard mechanism by which
an API notifies to the user the occurrance of an asynchronous
event or the results of an asynchronous (non-blocking) function
call. Typical uses of a callback function are to notify the user
that a SmartCard has been inserted or that a lengthy read
function has completed.
Callback functions are supplied by the user and are declared
in the parameter of an STXXXXX_Open() function. The number of
parameters to the function is dependant on the callback, but
typically the function prototype is :
(void *) Callback( p1, p2, p3);
8 Event Handler
The Event Handler is an API which provides a general and more
powerful mechanism to notify users of the occurrance of events.
It is used on occassion in preference to simple callback
6 7
functions. In particular, it provides a mechanism which allows
any software component to subscribe to notified events.
For details see the Event Handler API, document DVD-API-018
contained within this document.
9 System header files
The following is a list of header files common to the ST API
stddefs.h ST API standard common definitions
三、原理
1
A Set Top Box (STB) is a complex software environment where
many individual drivers must interact and control a number of
hardware devices to implement all the functions required. The
sorts of control that are necessary include real-time control
of dedicated hardware (for example the video decoder),
real-time collection of data (from the PTI or programmable
transport interface), and general device driver functions
(such as UART, FLASH or I2C support).
The diagram below shows the drivers that are provided in
a typical ST-API based system. The arrows between the drivers
show the flow of data between different devices.
7 8
2
Driver mappings
8 9
3
Common Constants
Description
Constants which are available for all drivers to use.
Definitions
TRUE Logical true value
FALSE Logical false value (defined as !TRUE)
4
Common ST Constants
Description
Constants which are available for all drivers to use.
Definitions
ST_MAX_DEVICE_NAME Maximum number of bytes (including
trailing 0) that can be used as a device name.
5
Common Typedefs
9 10
Description
The common typedefs that are used.
Definitions
U8 unsigned char
U16 unsigned short
U32 unsigned int
S8 signed char
S16 signed short
S32 signed int
BOOL int
ST_String_t char* [1]
Comments
[1] char is assumed to be unsigned
6
Derived Typedefs
Description
Typedefs that are derived from other typedefs.
Definitions
ST_ErrorCode_t U32
7
Common Error Defines
Description
Error definitions that are used by multiple drivers.
Definitions
ST_NO_ERROR The requested operation was successful.
10 11
ST_ERROR_BAD_PARAMETER Returned when at least one of the
parameters supplied to the function is invalid, and when no
accurate error reason is required.
ST_ERROR_NO_MEMORY A memory allocation failed and the
operation was unable to continue (see comments below) [1]
ST_ERROR_UNKNOWN_DEVICE Unknown device name, device not
initialized.
ST_ERROR_ALREADY_INITIALIZED Named device already
initialized.
ST_ERROR_NO_FREE_HANDLES The maximum number of handles for
this device have been used, cannot open device again.
ST_ERROR_OPEN_HANDLE This error is returned by the Term()
functions when there are still connections open to the driver
(i.e. there are still “valid” handles in the system).
ST_ERROR_INVALID_HANDLE The driver doesn’t recognise the
handle passed.
ST_ERROR_FEATURE_NOT_SUPPORTED The requested feature of the
API is not implemented (ie either not supported by the hardware
or not emulated by the software).
ST_ERROR_INTERRUPT_INSTALL A problem occurred whilst
installing an interrupt handler for a device. [2]
ST_ERROR_INTERRUPT_UNINSTALL A problem occurred whilst
11 12
deleting an interrupt handler [2]
ST_ERROR_TIMEOUT The operation has exceeded a mutually agreed
time limit.
ST_ERROR_DEVICE_BUSY The target device is temporarily unable
to satisfy the , a read call to a UART is already
pending.
Comments
[1] It is strongly recommended that any memory allocations take
place during a driver’s initialization routine thus
restricting the no memory error code to initialization time.
[2] In the current implementation of OS20, an error may only
occur during an interrupt related operation if the interrupt
level is invalid. This may not be true of other operating
environments,hence the requirement for the interrupt error
codes above.
8
ST_DeviceName_t
Description
Describes the name used to refer to a particular driver
instantiation.
Definition
typedef char ST_DeviceName_t[ST_MAX_DEVICE_NAME];
Comments
Defines the device name used by the Init() call to define the
name of a particular device. This name is used in any subsequent
12 13
Open() calls to attach to the device. The name is also used by
calls which are “connectionless” in their context. An example
would be the GetCapabilities() call which needs to find out
information about a particular device instantiation to help
decide upon strategies for device use or Open() parameters.
9
ST_Revision_t
Description
Describes the current revision level of a driver.
Definition
typedef const char *ST_Revision_t;
Comments
This typedef will contain a string of the format:
string}
These numbers are changed at release time and are always updated
to the appropriate level. The rules for changing these numbers
are as follows:
Major revision numbers are incremented whenever the API changes
substantially. Examples of this kind of change include addition
of new function entry points, API rework or the restructuring
of the APIs working methods.
Minor revision numbers are incremented when the API changed in
only small amounts, for example an extra element is added to
13 14
a structure but a recompilation means that old code will
work directly.
The Patch revision is incremented when no visible (to an ST-API
level programmer) changes are made. This will typically happen
when bug fixing or during alpha and beta development prior to
general release.
In all cases, if the hierarchically higher number is
incremented, all lower numbers are reset to zero.
10
ST_GetClockSpeed()
Description
Gets processor clock speed.
Definition
U32 ST_GetClockSpeed(void);
Arguments
None.
Return Value
Returns the processor clock speed (Hz).
Comments
This function may be called at any time.
See Also
ST_GetClocksPerSecond()
11
ST_GetClocksPerSecond()
Description
Gets the number of clock ticks per second.
Definition
U32 ST_GetClocksPerSecond(void);
14 15
Arguments
None.
Return Value
Returns the number of processor clock ticks in a one second
interval.
Comments
The actual value that is returned by ST_GetClocksPerSecond()
is derived from the processor clock speed and task priority.
This function may be called at any time.
See Also
ST_GetClockSpeed()
12
ST_GetMajorRevision()
Description
Gets the current major revision level of the driver
Definition
#include “stddefs.h”
U32 ST_GetMajorRevision(ST_Revision_t Revision);
Arguments
Return Value
Returns the major revision level of the driver.
Comments
None.
See Also
ST_GetMinorRevision()
ST_GetPatchRevision()
Revision The structure returned from a STXXXXX_GetRevision()
call.
15 16
13
ST_GetMinorRevision()
Description
Gets the current minor revision level of the driver
Definition
#include “stddefs.h”
U32 ST_GetMinorRevision(ST_Revision_t Revision);
Arguments
Return Value
Returns the minor revision level of the driver.
Comments
None.
See Also
ST_GetMajorRevision()
ST_GetPatchRevision()
Revision The structure returned from a STXXXXX_GetRevision()
call.
14
ST_GetPatchRevision()
Description
Gets the current patch level of the driver
Definition
#include “stddefs.h”
U32 ST_GetPatchRevision(ST_Revision_t Revision);
Arguments
Return Value
Returns the patch level of the driver.
Comments
None.
See Also
16 17
ST_GetMajorRevision()
ST_GetMinorRevision()
四 实例 STFLASH（Flash Memory API）
1
Using the API
The API allows access and control over one or more banks of
Flash devices
2
Constants
The API for the Flash driver is defined in the header file
stflash.h.
3
Events
The Flash API exports no events.
4
Types
The data types exported by the API are listed below.
Type Description
STFLASH_Block_t Structure describing a block or segment of
the Flash device
STFLASH_Handle_t Handle returned by STFLASH_Open() function
STFLASH_InitParams_t Parameters for the STFLASH_Init()
function
STFLASH_OpenParams_t Parameters for the STFLASH_Open()
function
STFLASH_Params_t Structure describing the Flash device
17 18
STFLASH_TermParams_t Parameters for the STFLASH_Term()
function
5
Functions
The following table lists the API calls available.
Function Description
STFLASH_GetRevision() Get revision number of the Flash device
driver
STFLASH_GetParams() Get the characteristics of the specified
Flash bank
STFLASH_Init() Initialize an instance of the Flash device
driver
STFLASH_Open() Open access for the specified Initialization
instance
STFLASH_Read() Read from the specified Flash bank
STFLASH_Erase() Erase blocks within the specified Flash bank
STFLASH_Write() Write to the specified Flash bank
STFLASH_Close() Close access for the specified Initialization
instance
STFLASH_Term() Terminate an instance of the Flash device driver
18
发布评论