ST AN2491 Application note
AN2491
Application note
STW8110x hardware component layer API guide
Introduction
Purpose and scope
This document describes the HCL elements of the STW8110x HCL API included in the
STW8110x evaluation kit. This document is intended for people using the STW8110x digital
bus interfaces. It proposes an abstraction of the hardware in order to allow a user to use all
the facilities provided by the HW IP.
The document provides:
■ A brief description of the hardware
■ An overview of concepts on which the STW8110x HCL API is based
■ A description and explanation of all API types and functions
■ A user scenario
■ The public header file
HCL API version
■ Version of the STW8110x HCL API: V1.0
■ Applicable to the IC: STW8110x
August 2007 Rev 1 1/32
www.st.com
Contents AN2491
Contents
1 STW8110x API package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1 Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.1 Digital bus interface header file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.2 STW8110x API header file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1.3 STW8110x API source file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2 How to use the STW8 1 10 x A P I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2 API overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1 Global initialization functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2 Configuration functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.3 Data extraction functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4 Debug management functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.5 Driv e r targets and compilation options . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3 Constants and enums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.1 Both modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2
3.2 I
C mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4 Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1 Both modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2
4.2 I
C mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
5 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.1 Both modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.2 I2C mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6 User scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
6.1 I2C mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
6.2 SPI mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
7 STW8110x public header file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
8 Digital_Bus_interface header file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2/32
AN2491 Contents
9 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
10 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3/32
List of functions, constants, enums and structures AN2491
List of functions, constants, enums and structures
Configure_STW8110x() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
I2C_Read_Status_Register() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
STW8110x_Check_config() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
STW8110x_Get_Fout_value() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
STW8110x_Init(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
STW8110x_ProcessError(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
t_CP_SEL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
t_PD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
t_PLL_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
t_PSC_SEL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
t_SERCAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
t_stw8110x_Config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
t_stw8110x_Device_Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
t_stw8110x_error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
t_stw8110x_I2C_RO_reg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
t_stw8110x_PLL_Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
t_stw8110x_Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4/32
AN2491 STW8110x API package
1 STW8110x API package
It is highly recommended to read the STW81101, STW81102 or STW81103 datasheet
before continuing to read this document. This API is a simple abstraction of the principles
presented in these datasheet s.
The STW8110x device has two embedded digital bus interfaces (I
their internal registers to be programmed. Each of these interfaces has its own dedicated
protocol which must be followed to program the device correctly. For details of the
STW8110x register and SPI and I
1.1 Content
2
C protocols, refer to the relevant datasheet.
2
C and SPI) which allow
Three files are available in this package. A fourth file must be created by the user with
implementation of I
Figure 1. Files available with this package
2
C and SPI functions according to the master interface.
1.1.1 Digital bus interface header file
Contains declarations of functions to be implemented by the user (refer to
complete listing). This subsection describes the tasks that the functions must accomplish.
For more details about the digital bus protocol flow and configuration to apply to your master
interface (as frequency) please refer to the STW81101, STW81102 or STW81103
datasheet.
I2C mode
t_I2C_Ack I2C_Send_data(unsigned char *data, int nb_bytes)
{
// 1 - Send Start Bit
// 2 - loop i=1 to i=nb_bytes
// a - send data[i]
// b - wait acknowledge of slave
// 3 - Send Stop Bit
// return ACK, or NO_ACK if acknowledge hasn’t been received
}
1. Digital bus interface header file
2. STW8110x API header file
3. STW8110x API source file
Section 8
for a
t_I2C_Ack I2C_Read_data(unsigned char Add, unsigned char *data)
{
// 1 - Send Start Bit
// 2 - send Add
// 3 - wait acknowledge of slave
5/32
STW8110x API package AN2491
// 4 - read received data and affect it to *data
// 3 - Send Stop Bit
// return ACK, or NO_ACK if acknowledge hasn’t been received
}
SPI mode
void SPI_Send_data(unsigned int data)
{
// Send data (32bits) on SPI bus
}
1.1.2 STW8110x API header file
Contains declaration of functions, structures and defines necessary to the device driver.
(Refer to
Section 7
for a complete listing).
1.1.3 STW8110x API source file
Contains the C code of device driver.
1.2 How to use the STW8110x API
1. Add the API in your project (STW8110x.c, STW8110x.h, Digital_Bus_interface.h).
2. Create a file (Digital_Bus_interface.c) with functions to implement according your
master interface.
3. Include the STW8110x header file (#include “STW8110x.h”) in the file which uses the
API functions.
4. Use dedicated functions to program the device (see examples in
Section 6
).
6/32
AN2491 API overview
2 API overview
Note: To ensure the correct usage of this HCL API, it is HIGHLY recommended to use this API in
the debug mode first (by use of __DEBUG preprocessor as described in Section 2.5). Only
after the application has executed successfully in debug mode should the STW8110x driver
be run in release mode.
The API contains 4 types of functions:
● Functions related to the global initialization of STW8110x
● Functions related to the configuration of STW8110x
● Functions related to extraction of the STW8110x configuration information
● Functions related to STW8110x debug management
2.1 Global initialization functions
STW8110x_Init(); initializes the data structures of the STW8110x HCL.
2.2 Configuration functions
Configure_STW8110x(); configures the STW8110x device.
2.3 Data extraction functions
● STW8110x_Check_config(); verifies selected configuration.
● STW8110x_Get_Fout_value(); gets output frequency according selected configuration.
● I2C_Read_Status_Register(); obtains information about read-only register (I
2.4 Debug management functions
STW8110x_ProcessError (); manages possible errors of the STW8110x device driver.
2
C mode).
7/32
API overview AN2491
2.5 Driver targets and compilation options
The driver source files can work in several environments. There are three possible targets
for which the driver compilation options (#define) customize the code for the target.
● The platform - represents the IC (STW81101, STW81102, STW81103).
● The interface - represents digital interface used to program the device (I
● The mode - identifies if the code is being compiled for debug or release mode.
Table 1. Target platform compilation options
Platform STW81101 STW81102 STW81103
#define __PLATFORM_STW81101 __PLATFORM_STW81102 __PLATFORM_STW81103
Table 2. Target interface compilation options
Interface I2C SPI
#define __INTERFACE_I2C __INTERFACE_SPI
Table 3. Target mode compilation options
Mode Debug Release
2
C, SPI ).
#define __DEBUG __NO_DEBUG
8/32
AN2491 Constants and enums
3 Constants and enums
3.1 Both modes
t_PD
Defines the device functional mode.
typedef enum
{
POWER_DOWN,
VCO_A_FREQ_DIV_2,
VCO_B_FREQ_DIV_2,
VCO_EXT_FREQ_DIV_2,
VCO_A_FREQ_DIV_4,
VCO_B_FREQ_DIV_4,
VCO_EXT_FREQ_DIV_4,
VCO_A_DIRECT_OUTPUT,
VCO_B_DIRECT_OUTPUT,
VCO_EXT_DIRECT_OUTPUT
} t_PD;
t_SERCAL
Defines the VCO auto-ca libration status.
typedef enum
{
VCO_CAL_DISABLED,
VCO_CAL_ENABLED
} t_SERCAL;
t_CP_SEL
Defines the charge pump current
typedef enum
{
CURRENT_I_MIN,
CURRENT_2_I_MIN,
CURRENT_3_I_MIN,
CURRENT_4_I_MIN,
CURRENT_5_I_MIN,
CURRENT_6_I_MIN,
CURRENT_7_I_MIN,
CURRENT_8_I_MIN
} t_CP_SEL;
9/32
Constants and enums AN2491
t_PSC_SEL
Defines the prescaler modulus.
typedef enum
{
PRESCALER_16,
PRESCALER_19
} t_PSC_SEL;
t_PLL_A
Defines the PLL amplitude voltage of VCO.
typedef enum
{
AMPL_1V1,
AMPL_1V3,
AMPL_1V9,
AMPL_2V1
} t_PLL_A;
t_stw8110x_error
Defines all errors that can be returned by the functions of the STW8110x HCL API.
typedef enum
{
OK = 0,
ERR_A_HIGHER_THAN_B = -113,
ERR_A_OUTOF_RANGE ,// = -112,
ERR_B_OUTOF_RANGE ,// = -111,
ERR_N_OUTOF_RANGE ,// = -110,
ERR_VCOA_FREQ_OUTOF_RANGE ,// = -109,
ERR_VCOB_FREQ_OUTOF_RANGE ,// = -108,
ERR_FUNCT_MODE_UNKNOWN ,// = -107,
ERR_REF_CLK_DIVIDER ,// = -106,
ERR_PRESCALER ,// = -105,
ERR_VCO_CALIBRATION ,// = -104,
ERR_VCO_VOLTAGE ,// = -103,
#ifdef __INTERFACE_I2C
ERR_I2C_ACK ,// = -102,
ERR_BAD_DEVICE ,// = -101,
ERR_I2C_READ ,// = -100,
#endif //__INTERFACE_I2C
ERR_CHARGE_PUMP_CURRENT // = -99 or -102
} t_stw8110x_error ;
10/32
Loading...