trademarks of Freescale Semiconductor, Inc., Reg. U.S. Pat ... · Overview Import the Project Add...

TM

Freescale, the Freescale logo and CodeWarrior are

trademarks of Freescale Semiconductor, Inc., Reg.

U.S. Pat. & Tm. Off. Xtrinsic is a trademark of

Freescale Semiconductor, Inc.

All other product or service names are the property

of their respective owners.

© 2013 Freescale Semiconductor, Inc.

TM

2

Objectives

In this module, there are three primary objectives focused

on delving deeper into the functionalities enabled by ISF.

• You will become familiar with the process of including

and excluding ISF components in your ISF application.

• You will gain a high-level understanding of the ISF

header files and how to use them in ISF applications.

• You will become familiar with the use of the ISF

Command Interpreter to execute functions and retrieve

sensor data via host commands to the FXLC95000

instead of modifying the inputs and outputs via the

mailboxes. This can be done directly through two

distinct paradigms:

— Command/Response

— Quick-Read.

Module 5

ObjectivesPrerequisitesRequired Items

OverviewImport the ProjectAdd CI to the ProjectRegistering a CI CallbackCommand/Response Add a Host CommandQuick-Read

Module SummaryNext Steps

TM

3

Prerequisites

To complete this module, you will need a Xtrinsic ISF 1.1 Windows 7 development PC

meeting the following minimum hardware requirements:

• Pentium 4 or newer

• 4 GB of RAM

• 2 USB ports (1.0, 2.0, or 3.0)

The development PC must have an internet connection and have specific software

installed.

1. CodeWarrior 10.5 or newer (with ColdFire support)

2. FSL_MQX_3.7_FXLC95K

3. ISF 1.1 Core Library

For more information on these installations, refer to Module 1—Installing Necessary

Software.

You will also need the following items:

• KITFXLC95000EVM/MAG/10-AXIS (Application Board and USB cables)

Module 5




TM

4

Prerequisites

Prior to beginning, you should have completed previous Xtrinsic ISF 1.1

Training modules.

• Module 2—Installing an ISF Binary

• Module 3—Building an ISF Binary

• Module 4—Modifying an ISF Application

Also, you should be familiar with C language programming.

Related documentation can be found on the Windows Start Icon under

“All Programs/Freescale/Xtrinsic ISF v1.1/Documentation”

or

the Detailed documentation can also be found on the Xtrinsic ISF webpage.

• ISF Software Reference Manual (ISF1P195K_SW_REFERENCE_RM)

• ISF API Reference Manual (ISF1P195K_API_REFERENCE_RM)

• ISF Software Release Notes (ISF1P195K_CORE_LIB_RELEASE_RN)

Module 5




http://www.freescale.com/isf

http://www.freescale.com/files/sensors/doc/ref_manual/ISF1P095K_SW_REFERENCE_RM.pdf



http://www.freescale.com/files/sensors/doc/ref_manual/ISF1P095K_API_REFERENCE_RM.zip



http://www.freescale.com/files/sensors/doc/support_info/ISF1P095K_CORE_LIB_RELEASE_RN.pdf



TM

5

Required Items

Prior to beginning, two files must be located in the ISF 1.1

installation.

1. Go to the Windows Start Icon, select “All Programs -> Freescale

-> Xtrinsic ISF v1.1 -> Example Applications Folder”. Locate the

GetAccelData directory.

2. Go to the Windows Start Icon, select “All Programs ->

FXLC95000 Mailbox Tool -> FXLC95000 Mailbox Tool .

Alternatively, if the ISF 1.1 installer has NOT been run, these items must be downloaded

from the Xtrinsic ISF Downloads webpage.

• Download the ISF1P195K GETACCELDATA zip file from the ISF webpage

Run-time Software\Specific Applications - Apps area.

• Download the FXLC95000_ISF1P1_WIN_MAILBOX_TOOL_EXE executable file from

the Software Development Tools\Debuggers and Runtime Analysis area.

This is the Intelligent Sensor Mailbox Tool, used for transferring binaries to the

FXLC95000. (Note that it is also used for transferring commands and data between

the PC and FXLC95000.)

Module 5




TM

6

Overview

With your current understanding, any change to the data configuration of the

mailboxes requires modifying, rebuilding and reloading the user application,

as demonstrated in the previous module.

What if there was a simple command made from the host to read/write the

sensor data whenever and however the host needs it?

Host

User App

Commands/

Data

Internal

Sensor

Sensor

Manager

Sensor

Abstraction

ISFCommand

Interpreter

Module 5




TM

7

Overview (continued)

The ISF Command Interpreter (CI) provides the necessary

infrastructure to handle the dispatching of commands received via

the mailboxes. The Command Interpreter provides a general

mechanism to process commands and data read from the

mailboxes triggering the execution of the command in the user

application.

To help you understand the Command Interpreter and begin using it,

this module provides information in three main areas:

• Adding the Command Interpreter component to the project

• Understanding Command/Response operations and adding a

host command

• Understanding Quick-Read operations and implementing a QR

command to configure the Quick-Read mailboxes.

Module 5




TM

8

The ISF Command Interpreter Component

Because ISF is provided as a set of libraries, the user has the option to link only

those components needed for their user application. The Command Interpreter (CI)

is an optional component. When included in the build, all functions provided by the

CI may be used by the user application. The same is true for any of the other ISF

components and the corresponding tasks apply.

To communicate using the CI, the host and the user applications may use one or

both of two different mechanisms.

• The CI provides a way for user applications to run synchronized commands

based upon the needs of the host application. The sensor data is provided via

the mailboxes. This is the Command/Response operation.

• The CI provides a general mechanism for user applications to write to specific

mailboxes which the host can read asynchronously. This is without the need for

the host application to issue multiple commands to read data from the

mailboxes. This is the Quick-Read operation.

Note: API documentation for all functions provided by the CI can be found in the

ISF API Reference Manual (ISF1P195K_API_REFERENCE_RM)

Module 5







TM

9

Import the Project

1. Open CodeWarrior.

2. Create a clean workspace.

In the Select a workspace window, click Browse, then, in a convenient location, create a

new folder named workspace_module5, then select the folder, and then click OK.

This folder is referred to as the workspace folder.

3. The material is located in the installation directory

C:\Program Files\Freescale\ISF_R1p1\Example Applications\GetAccelData

but you don’t want to corrupt the working versions with the training sandbox. As a result,

please copy the directory into the workspace_module5 directory.)

3. Navigate to the workspace5 folder, and then to the GetAccelData\Build folder.

4. Import the project into the CodeWarrior workspace.

1. Import project

2. Modify application

3. Build application

4. Connect hardware

5. Configure connection

6. Establishcommunication

7. Run application

8. TestModule 5




TM

10

Add CI Component to the Project

There are two sets of header files used in ISF.

• Header files associated with ISF are located in the ISF_ROOT_DIR/Include directory.

ISF_ROOT_DIR is the directory where ISF is installed. The header files are visible to

users because they may require access to the ISF interfaces and for rebuilding the

project.

IMPORTANT: Users are strongly discouraged from modifying these files.

• Header files associated with the project files for the user application are located in the

GetAccelData/Include directory for the project. These files can be modified as

needed for the user application.

1. Import project



4. Connect hardware



7. Run application

8. TestModule 5




TM

11

Add CI Component to the Project (continued)

As provided, the GetAccelData project does not include the Command Interpreter

component.

To work with the Command Interpreter component, it must be added to the project. To do

this, two header files must be modified.

• Modify isf_user_config.h to turn on the component

• Modify GetAccelData_main.c to add the CI function declarations to the user

application by including the isf_ci.h header file

Doing this allows full access to the functions of the Command Interpreter.

1. In CodeWarrior, open the isf_user_config.h file, located in the Include directory in

the CodeWarrior project (Include/isf_user_config.h).

Module 5




TM

12

Add CI component to the Project (continued)

2. Locate the ISF_COMPONENT_CI macro, and then change it from 0 to 1.

3. Save the file.

Before

After

Module 5




TM

13

Add CI component to the Project (continued)

4. Open the GetAccelData_main.c file, located in the Source directory in

the CodeWarrior project (Source/GetAccelData_main.c).

5. Locate the ISF framework includes, and then add the Command

Interpreter function declarations to the user application by including the

isf_ci.h file as shown.

6. Save the file.

Note: isf_ci.h is one of the header files associated with ISF and

should not be modified.

Module 5




TM

14

Checkpoint

At this point, the Command Interpreter component has been added

to the project—you are now ready to link the user application by

including the components necessary for the example in this module.

In summary, to include any given component from the ISF library:

• Modify isf_user_config.h to turn on the specific component

• Add the specific component header file to the user application.

To exclude any given component, turn off the component in

isf_user_config.h by changing 1 to 0.

Module 5




TM

15

Command Interpreter Paradigms

A host may use commands in two distinct paradigms implemented in the ISF

Command Interpreter. Requirements on the host side will influence which

paradigm to use.

In the rest of this module, you will learn about the theory and use of both

paradigms.

• Command/Response

• Quick-Read (QR)

Command/Response is used when a host wants specific tasks to execute in

a user application on demand.

Quick-Read (QR) is used when a host wants to read the sensor data on a

periodic interval without sending a command packet and waiting for a

response.

In the rest of this module, you will learn how to produce both types of

commands which you use depending on your needs.

Module 5




TM

16

Registering a CI Callback

The device may have multiple user applications running on it. Hence, each

user application that wishes to use the CI must register with the CI. This

registration allows ISF to know which commands are associated with the

specific user application. As part of the registration, the user application

specific callback is inserted into the registry. This callback is called

automatically whenever the host sends a specific command to the user

application on the device.

Registering a callback is a three step process.

1. Declare the callback function.

2. Insert the callback function into the CI registry.

3. Define the callback function.

See Wikipedia for more information regarding callbacks if required.

Module 5




TM

17

Registering a CI Callback (continued)

The first step to registering a CI callback is to declare the callback function.

The callback is declared using the following function signature (or format).

For the example in GetAccelData, the callback is named accelCallback.

Hence, the callback is declared as:

Note that the only thing changed from the signature is the name of the

callback.

For information on the parameters, refer to the ISF API Reference Manual,

(ISF1P195K_API_REFERENCE_RM).

ci_response_t callBackName(ci_host_cmd_packet_t *pHost_packet,

ci_app_resp_packet_t *pApp_packet);

ci_response_t accelCallback(ci_host_cmd_packet_t *pHost_packet,

ci_app_resp_packet_t *pApp_packet);

Module 5





TM

18


Now, declare the callback function.

1. In CodeWarrior, open Source/GetAccelData_main.c.

2. Locate the Function Prototypes section, then insert the callback as

shown.

Note: This function declaration can be located anywhere before the function

definition. However, it is good practice to place it in the Function Prototypes

section.

Module 5




TM

19


The second step to registering a CI callback is to insert the callback function into the CI

registry. This is done by inserting the callback into the default ISF CI callback array.

To complete the callback registration, the callback function name must be added to the default ISF callback array called ci_callback. The CI uses the array index as the

Application ID of the registered user application. This allows ISF to simultaneously keep

track of multiple user applications.

In this case, the ISF_APP_CALLBACKS macro defines the first two elements of the array.

The callback for this example, accelCallback, is added as the third element of the

array. Therefore, the GetAccelData application has Application ID 0x02.

// Command Interpreter callbacks. The array index is the ApplicationID.

const ci_funcp_t ci_callback[] =

{

// ISF callbacks come first.

ISF_APP_CALLBACKS

accelCallback

};

Therefore, the GetAccelData application has Application ID 0x02.

Module 5




TM

20


Now, insert the callback function into the CI registry.

Add the callback as shown.

Before

After

Note: The edit

window may

display

question mark

icons in the

margin. In this

case, they may

be ignored.

Module 5




TM

21


The third step to registering a CI callback is to define the callback function for handling the

command.

Add the snippet below to the bottom of the Source/GetAccelData_main.c file, and then

save the file.

Note: The code snippet can go anywhere but it is recommended that it be at the bottom of

file.

Note: For now, the accelCallback function is empty to get the file to compile or build.

The complete definition of the function occurs later in this module.

/*

* @name CI callback for the GetAccelData application.

*

* @brief Implements the host command for the accelerometer in this callback. CI calls this

* callback automatically when the host sends a command for this application.

*/

ci_response_t accelCallback(ci_host_cmd_packet_t *pHost_packet,

ci_app_resp_packet_t *pApp_packet)

{

}

Module 5




TM

22


After:Module 5




TM

23

Checkpoint

The steps to register a callback are complete.

Clean and build the project, using what you learned in Module 3—Building

an ISF application. When the build is complete, the console displays a build

complete message.

1. Import project



4. Connect hardware



7. Run application

8. Test

NOTES:If compilation errors exist,

typographical errors are very

likely present. Double check

for typographical errors.

Copying and pasting text from

this training module may

introduce issues with dropped

spaces. Check to make sure

no errors were introduced.

Module 5




TM

24

Adding a Command/Response Host Command

The Command/Response paradigm is a synchronous interface which means that a

specified order is expected when using the 32 mailboxes on the FXLC95000.

1. An initial command from the host is placed into the mailboxes.

2. The ISF firmware responds to the command by putting the response data into the same

32 mailboxes.

3. A special bit called the Command Complete, or COCO, bit in MB1 is used to indicate

that the data is ready to be collected from the mailboxes.

4. A second command from the host is required to read the data from the mailboxes.

In this section, the necessary modifications for adding a Command/Response host

command continue. For the C/R host command, the values needed to be written to the

mailboxes to trigger the callback function are determined.

The two actions required for adding a Command/Response host command are:

• Create a sensor data buffer available to the callback function

• Implement the logic required to handle the host command

Module 5




TM

25

Command/Response Command Format

When using the Command/Response paradigm, the host commands are sent from the host to the

FXLC95000.

Command/Response commands consist of four fields, each one byte in size. In the case of C/R, the

host issues commands by writing specific values to these bytes.

Once the command enters the FXLC95000, the four command fields are placed into the first four

mailboxes, MB0:3. These bytes are always reserved as such, even for Quick-Read commands.

• The ApplicationID field describes the identification number for the user application registered with the Command Interpreter. The number corresponds to the location in the ci_callback

array beginning with index 0.

• The CommandID field specifies various operations or commands the CI can perform. ISF has some predefined commands located in ci_commands_enum in isf_ci.h.

• The Offset field specifies the byte number into the user application data buffer.

• The Number of bytes field is the number of data bytes the host wants to access.

Command Structure (Command/Response)

Field Field 1 Field 2 Field 3 Field4

Field contents ApplicationID CommandID Offset Number of bytes

Mailbox assignment MB0 MB1 MB2 MB3

Module 5




TM

26

Command/Response Command Format (continued)

Example

This example will show the process used to define a Command/Response command.

The objective is to create a host command to request the following sensor data from the

user application:

• four bytes of sample count

• six bytes of X,Y, Z accelerometer data.

Field 1: ApplicationID

The ApplicationID field describes the identification number for the user application

registered with the Command Interpreter. The number corresponds to the index in the ci_callback array.

Earlier in this module, accelCallback was declared in the third position of the

ci_callback array (index = 2).

Therefore, the value of Field 1 is 0x02.

Module 5




TM

27


Field 2: CommandID

There are several command types listed in the ISF Software Reference Manual.

In this example, we are interested in reading data from an application’s output

buffer. Referencing the list, the appropriate command type is CI_CMD_READ_APP_DATA = 3. This value (3) is used as the CommandID.


Module 5




TM

28


Field 3: Offset

The Offset specifies the starting location of the data to be read from the user application

output data buffer.

ISF uses the predefined type AfeDataPkt_t to return the sample count and

accelerometer data. For more information, refer to the ISF API Reference Manual

(ISF1P195K_API_REFERENCE_RM) .

• The first four bytes contain the tickCount.

• The next six bytes contain the X, Y and Z accelerometer data

Since the data is read from the beginning of the data buffer in this example, the offset is 0.


Module 5





TM

29


Field 4: Number of bytes

The Number of bytes field is the number of data bytes the host wants.

In this example, the host wants 10 bytes.

• 4 bytes sample count

• 2 bytes X accelerometer data

• 2 bytes Y accelerometer data

• 2 bytes Z accelerometer data

Therefore, the value of Field 4 is 0x0A.

Together, based on the values determined for the four fields, the

Command/Response command is: 02 03 00 0A

Module 5




TM

30

Adding a Host Command

A data buffer needs to be defined to hold the sensor data available to the callback function, accelCallback, in response the read command from the host. In our example, the action is

completed by making the local variable into a global variable. In the user_task function, make

the local variable

AfeDataPkt_t accelSampleData; /* The buffer which receives the accelerometer data. */

available to accelCallback by moving it to the global variables section. As a result, the variable

accelSampleData can be accessed in the accelCallback callback function.

Comment

out local

variable

here (or

delete)

Insert global variable here

Module 5




TM

31

Adding a Host Command (continued)

Next, implement logic to handle the host command in the callback function, which is called

automatically whenever a specific command is received by the device.

The general logic is:

Identify the type of command

Validate the command

Send and receive data to and from the host

Module 5




TM

32


Now, implement the logic to handle the host command in the callback function, accelCallback .

1. Locate the empty callback function defined earlier in this module.ci_response_t accelCallback(ci_host_cmd_packet_t *pHost_packet, ci_app_resp_packet_t *pApp_packet)

2. Insert the following code snippet into the empty accelCallback callback function.

ci_response_enum callbackRet = CI_ERROR_NONE;

switch(pHost_packet->cmd)

{

/* This is the command type for requesting user application data.*/

case CI_CMD_READ_APP_DATA:

// Validate the requested data size

if(pHost_packet->byte_cnt > sizeof(AfeDataPkt_t)){

callbackRet = CI_INVALID_COUNT;

break;

}

// Validate the requested data size from the offset.

if(pHost_packet->offset + pHost_packet->byte_cnt > sizeof(AfeDataPkt_t) ){

callbackRet = CI_ERROR_COMMAND;

break;

}

// Send the accelerometer data to the host.

pApp_packet->bytes_xfer = (uint8)isf_ci_app_write(pHost_packet->appId,

(uint32)pHost_packet->byte_cnt,

(uint8*)((uint8*)&accelSampleData + pHost_packet->offset));

break;

default:

callbackRet = CI_ERROR_COMMAND;

break;

}

return callbackRet;

Module 5




TM

33


Identify the command type from the Host command


Send back the accelerometer data to the host using the CI write function, isf_ci_app_write

Module 5




TM

34


The process is the same when implementing other CI commands, such as:

CI_CMD_READ_CONFIG

allows the host to read the configuration data supplied by the application

CI_CMD_WRITE_CONFIG

allows the host to write specific configuration data to the application

The implementation logic is just like what was done on the previous slides by applying the

same steps.

Identify the type of command


Send and receive data to and from the host

Module 5




TM

35


In this module, since an existing user application is being modified, some clean-up is required

to give full control to the Command Interpreter for mailbox management and avoid overlapping

data in mailboxes.

Delete the following code snippet for direct mailbox access from the function user_task in

the Source/GetAccelData_main.c source code. (Located approximately at line 220.)

This completes the necessary modifications for adding a Command/Response host command.

/*

* Put the data and stats in the mailboxes to be ready by the host.

*/

/* SP_MB1_dword is a 4-byte word at SP_MB4-SP_MB7. */

SP_MB1_dword = sampleCount;

/* SP_MB2_dword is a 4-byte word at SP_MB8-SP_MB11. */

SP_MB2_dword = missedSamples;

/* SP_MB6_word is a 2-byte word at SP_MB12-SPMB13. */

SP_MB6_word = accelSampleData.afeData.accel[0];





/* Let the host the mailboxes are updated with valid data. */

SP_MB1 = 0x80;

Module 5




TM

36

Building the Image

The necessary source code modifications for adding a host command are

complete.

Clean and build the project, using what you learned in Module 3—Building

an ISF application. When the build is complete, the console displays a build

complete message.

1. Import project



4. Connect hardware



7. Run application

8. Test

Module 5




TM

37

Connecting the Hardware,

Configuring the Connection,

Establishing Communication

Steps 4, 5, and 6, for this module are similar to the corresponding steps

completed in earlier modules.

For the purposes of this training, the method of using the Mailbox Tool to load

the S19 file is being used.

1. Import project



4. Connect hardware



7. Run application

8. Test

Module 5




TM

38

Establishing Communication

1. Locate and open the Intelligent Sensor Mailbox Tool

(ISF1P1WIN_MAILBOX_TOOL_EXE.exe)

2. Click Open Comm.

Verify that communication is established. (If communication is not established, reset the

board and try again.)

• Running ROM code is displayed in the console

• Connected to Device is indicated in the status bar

You are now ready to transfer the S19 Binary image to the FXLC95000CL device and run

the application.

• Return to the mailbox tool and switch over to the “Flash Utility” tab .

• In case there is another image already in flash, begin by pressing “Erase Flash”.

• Now select “Program Flash” and select the S19 file from the CodeWarrior workspace

C:\Users\...\workspace_module5\GetAccelData\Build\Binary\GetAccelData.elf.S19

• Select “Boot to Flash”.

1. Import project



4. Connect hardware



7. Run application

8. Test

Module 5




TM

39

Command/Response Checkpoint

With communication established, the new build completed, and the application running

on the Application Board, you can send the command defined in this exercise using

the Intelligent Sensor Mailbox Tool.

1. In the Intelligent Sensor Mailbox Tool, on the “Mail Box” tab,

enter 02 03 00 0A in the Bytes to Write field, and then click MB Write.

This sends the command to the user application causing the registered callback

to put sensor data into the mailboxes.

This is the first stage in the command/response synchronization.

1. Import project



4. Connect hardware



7. Run application

8. TestModule 5




TM

40

Command/Response Checkpoint (continued)

2. Read the mailbox data by clicking MB Read button. This is the second command

described in the command/response synchronization.

The sample user application provides the sample count and X, Y, Z accelerometer data.

• MB0:3 contain the status response

— Note that MB1 has changed from 03 on input to 80 on output. This is because

of the COCO bit which is set (making bit 7 = 1) on command completion.

— In addition, MB2 has changed from 00 to 0A. On output, MB2 tells how many

bytes were actually transferred. Since it matches the value in MB3, you know

the transaction was successful.

• MB4:7 contain the sample count

• MB8:13 contain the X, Y, Z accelerometer data

MB8:13MB0:3 MB31MB4:7

Module 5




TM

41

Command/Response Checkpoint (continued)

To obtain the next set of data, you may send the same command by

clicking MB Write and then MB Read.

You have implemented a host command and seen that the

Command/Response paradigm supported by ISF Command

Interpreter is a synchronous interface requiring a host command.

Next, you will implement the data management for a host application

using the Quick-Read paradigm.

Module 5




TM

42

Implementing Quick-Read Support

How can a user application make sensor data available to the host without

sending a command and waiting for a response?

Can the data be made available to certain mailboxes configured by the host?

The CI enables this type of data management through the Quick-Read (QR)

paradigm which provides asynchronous communication between a user

application and the host where the user application updates the data into

special QR mailboxes configured by the host. This allows the host to obtain

data as needed without any firmware intervention. The mapping of data from

the user application to the QR mailboxes specified by the host is managed by

the CI without any need for synchronous intervention.

Module 5




TM

43

Implementing Quick-Read Support (continued)

The first step is to configure the mailboxes for Quick-Read.

The CI has a special command structure and a specific mailbox application

used to configure QR. The mailbox application has a set of configuration

registers or input buffers. These registers assign two attributes to each

mailbox, called a QR pair.

(i) an application ID which matches the user application to its QR data

and

(ii) A byte offset which specifies the offset into the user application’s output

data buffer.

Note that the appID for this special mailbox application that performs QR configuration

is 0x01.

Module 5




TM

44


The diagram shows the QR command structure starting from mailbox zero (MB0).

Each field is one byte in length.

As before, when the command comes from the host into the FXLC95000, the command

goes into the 32 mailboxes. This means that command width must be less than or equal to

32. The discussion going forward assumes that the command is already located in the

mailboxes on the FXLC95000.

1

Note that the appID for this special mailbox application that performs QR configuration

is 0x01.

Module 5




TM

45


Note that the first four bytes of the command corresponding to MB0:3 are dedicated for

command/ response transfers and cannot be configured for Quick-Read.

Mailboxes MB4:31 can be configured by the host for Quick-Read. Any or all of these

mailboxes can be configured for Quick-Read. The command can extend to MB31 but it

does not have to do so. However, it is assumed that the command definition continues as

long as there are QR pairs. As soon as the QR pairs end, then the command ends with the

last QR pair. There is an example later in this module.

The commands are sent from the host to the FXLC95000.

The Quick Read mailboxes are output from the FXLC95000 to the host.

The mailboxes are the communication mechanism in both cases.

The commands have to communicate to the FXLC95000 which mailboxes the host is

expecting to read for Quick Read data.

If a mailbox pair is configured by the host for Quick-Read data, it cannot be used by the CI

for Command/Response data transfer, and the host should not write to these mailboxes.

QR mailboxes are written by the user application and read by the host.

Module 5




TM

46


MB0: The Application ID field contains the

identification number of the special Command

Interpreter mailbox application registered with

the Command Interpreter (CI). This is always

0x01 for Quick-Read.

MB1: The Command ID field is the type of

command the CI can handle for the mailbox

application. (For the types of commands

possible in the CI, see page 30 of the

ISF1P195K_SW_REFERENCE_RM.)

MB2: The Offset field is the offset into the

mailbox application data buffer or register.

MB3: The Number of Bytes field is the length of

the data bytes in the command.

SP_MB0 SP_MB1 SP_MB2 SP_MB3

Application ID

Command ID OffsetNumber of Bytes

Mailbox Application

Mailbox Application

Mailbox Application

Mailbox Application

Dedicated for command/response

1

Module 5




TM

47


The User App ID is the ID of the user application that provides the QR data.

The Offset of the User App is the offset into the user application’s data buffer.

Refer to the ISF1P195K_SW_REFERENCE_RM for more details.

SP_MB4 SP_MB5 SP_MB6 SP_MB7

…

SP_MB30 SP_MB31

User App IDOffset

(User App)User App ID Offset

(User App)User App ID Offset

(User App)

Mailboxes that may be configured for Quick-Read access.

Module 5




TM

48


This illustrates how different user applications can choose to map

different mailboxes to different outputs for Quick Read.

App3Inputs

0

1

2

…

n

Application ID 3

App3Outputs

0

1

2

…

n

App4Inputs

0

1

2

…

n

Application ID 4

App4Outputs

0

1

2

…

n

Module 5




TM

49


The following table, from the ISF Software Reference Manual, shows the

mapping between the mailbox application input buffer offset and the physical

mailboxes on the FXLC95000.

Note that CI Input Buffer Byte

Offset 0 and 1 are associated

with QR and the physical

mailbox, MB4. The value in

this input buffer configures the

QR data of the user application

in the physical mailbox MB04.

This will be used on the next

slide.

CI Input Buffer

Byte Offset QR Mailbox

Table A – Mailbox App Inputs

Module 5




TM

50

CI Input

Buffer

byte offset

Buffer

Name

(Parameter)

5

The mailbox application maps its buffers directly to the physical mailboxes for the QR data.

The command input below is interpreted by the mailbox application as a user application

with App ID 2 placing its 6th byte of output data in the physical QR MB4.

• In the command, the offset of 0 (red circle) matches the CI Input Buffer Byte Offset 0 in Table

A corresponding to QR MB4.

• In the command, the User App ID is 2 (blue square).

• In the command, the offset into App2’s output data buffer is 5 (red triangle), which is the sixth

byte.

1


App2Inputs

0

1

2

…

n

Application ID 2

App2Outputs

a

b

c

d

e

f

Command Input

Command Output

2Table A – Mailbox App Inputs

5

Module 5




TM

51


Let’s check your understanding.

Suppose you want to put the 3rd byte of output data from user application

ID=7 into MB9.

What are the entries in Table A for the CI Input Buffer byte offset and the

corresponding parameter?

App7Inputs

0

1

2

…

n

Application ID 7

App7Outputs

a

b

c

…

n


Hint: You will need to go

back to the complete

Table A on slide 49.

Module 5




TM

52


Suppose you want to put the 3rd byte of output data from user application ID=7 into MB9.

What are the entries in the CI Input Buffer byte offset and the corresponding parameter?

App7Inputs

0

1

2

…

n

Application ID 7

App7Outputs

a

b

c

…

n

Now that you have confirmed your understanding of the output, what

would the input command for this specific example look like?


Module 5




TM

53


Now that you have confirmed your understanding of the output, what would the

input command for this specific example look like?

App7Inputs

0

1

2

…

n

Application ID 7

App7Outputs

a

b

c

…

n

Command Input:


Module 5




TM

54


Now, consider a more true to life example.

What is the command to configure ISF to write the 6 bytes of accelerometer data (x, y, z) into

mailboxes 18 through 23 (MB18:23) as QR. What would the configuration command be?

Remember that the first four bytes are reserved for command/response.

Then, since we want 6 bytes of accelerometer data, we need six pairs or twelve bytes in the

command to lay out the location of the data.

This means that our command is 16 bytes long.

Construct the command byte by byte starting with byte 0.

Module 5




TM

55




Beginning with byte 0, what is the application ID of the command that configures the QR?

Module 5




TM

56




Beginning with byte 0, what is the application ID of the command that configures the QR?

The first byte is the application ID of the mailbox application is always 1.

The second byte is determined by the type of command used in the QR. There are several

types of commands listed in the ISF Software Reference Manual. This can also be determined by looking at ci_commands_enum in the header file isf_ci.h.

1

Module 5




TM

57




The second byte is determined by the type of command used in the QR. There are several

types of commands listed in the ISF Software Reference Manual. This can also be determined by looking at ci_commands_enum in the header file isf_ci.h.

The CI_CMD_WRITE_CONFIG = 2.

1 2

Module 5




TM

58




The third byte is determined by the offset into the

Command Interpreter Input Buffer Byte Offset. Use

the table on the right (from the ISF Software

Reference Manual).

1 2

Module 5




TM

59




The third byte is determined by the offset into the

Command Interpreter Input Buffer Byte Offset. Use

the table on the right (from the ISF Software

Reference Manual).

Mailbox 18 corresponds to an offset value of 28.

28 written in hexadecimal is 1C which becomes the

third value in the QR Configuration Command.

The fourth byte contains the number of bytes of data

involved. What is the correct value?

1 2 1C

Module 5




TM

60




The fourth byte contains the number of bytes of data involved. What is the correct value?

We have 6 bytes of QR data to be configured. Each byte of QR data requires two

configuration bytes—one for the Application ID and one for the offset.

Multiplying 6 by 2 gives a total of 12, which is C in hexadecimal .

This completes the command values.

Beginning with the fifth byte, the focus moves to the data values which are provided in pairs. In

this case, the interest is in the first byte of the x value of the accelerometer which is two bytes

long.

1 2 1C C

Module 5




TM

61




Beginning with the fifth byte, the focus moves to the data values which are provided in pairs. In

this case, the interest is in the x value of the accelerometer which is two bytes long.

Bytes 6 and 7 are easy because they contain the second byte of the x value of the

accelerometer. What would the values be for the next two bytes of the command?

1 2 1C C 2 4

The output format of the accelerometer provided in

the core library for this application ID is:

• Bytes 0-3 contain the ticket count

• Bytes 4-9 contain the accelerometer x, y, z

values from the accelerometer

It is out of the scope of this training to show you

where this is defined in the code. For now, accept

this as a definition.

Recall from slide 19 that the User

Application ID for GetAccelData is 2.

This becomes the value for byte 5.

Byte 6 contains the index of the output

buffer that contains the first byte of the x

value of the accelerometer. It turns out

that this value is the fifth byte of the

output buffer for app2 or getAccelData.

The offset is 4.

Module 5




TM

62




Byte 6 and 7 are easy because they contain the second byte of the x value of the

accelerometer. What would the values be for the next two bytes of the command?

The User App ID for GetAccelData is still 2. The second byte of data is in output buffer

location 5 (refer back to slide 61).

Now, we are looking for the y value of the accelerometer. It is also from GetAccelData and is

also two bytes long. You should be able to identify the values for the next four bytes of the

command this time.

1 2 1C C 2 4 2 5

Module 5




TM

63




Now, we are looking for the y value of the accelerometer. It is also from GetAccelData and is

also two bytes long. You should be able to identify the values for the next four bytes of the

command this time.

User App ID for GetAccelData remains 2. The first byte of the y value is in output buffer byte 6,

while the second byte is in output buffer byte 7 (refer back to slide 61).

The last four bytes contain the mapping for the z value of the accelerometer.

1 2 1C C 2 4 2 5 2 6 2 7

Module 5




TM

64




The last four bytes contain the mapping for the z value of the accelerometer.

The App ID for GetAccelData remains 2. The first byte of the z value is in output buffer byte 8

while the second byte is in output bugger byte 9 (refer back to slide 61).

This shows how the mailboxes are set up when the command comes into the CI.

Based upon this command, sketch out the mailbox configuration for the data being returned to

the host.

1 2 1C C 2 4 2 5 2 6 2 7 2 8 2 9

Module 5




TM

65


QR Configuration Command

This shows how the mailboxes are set up when the command comes into the CI.

Based upon this command, sketch out the mailbox configuration for the data being returned

to the host.

Note that once certain mailboxes are configured for QR, the host should track how many

mailboxes remain contiguous for general command/response type data. Refer to the

ISF1P195K_SW_REFERENCE_RM for more details. In this case, MB4:17 are contiguous

and available for C/R or QR. MB24:31, while contiguous are only available for QR

configuration. A new QR configuration command would be required in either case.

1 2 1C C 2 4 2 5 2 6 2 7 2 8 2 9

Module 5




TM

66


Now that you understand the commands, it is time to implement the logic in the user application to update the QR mailboxes whenever the data is available. The isf_ci_qr_update function is

defined as part of the CI (refer to the API Reference Manual ISF1P195K_API_REFERENCE_RM).

Insert the following code snippet into GetAccelData after the sensor data is retrieved from the Sensor Manager using isf_sm_get_sensor_data. Navigate to the user_task function in

Source\GetAccelData_main.c and add:

isf_ci_qr_update(0x2, (int8)sizeof(accelSampleData), (uint8 *)&accelSampleData);

isf_ci_qr_update parameters are:

• The appID of GetAccel Data

• The size of the data buffer

• The address of the data buffer

Module 5




http://cache.freescale.com/files/sensors/doc/ref_manual/ISPF_Version_0.43_API_Reference.zip?fpsp=1&WT_TYPE=Reference Manuals&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=zip&WT_ASSET=Documentation

TM

67

Quick-Read Checkpoint

You have completed the necessary modification for Quick-Read

support.

1. Clean and build the project.

2. Flash the updated image onto the application board as before.

(It is recommended to close and reopen the Mailbox Tool.)

3. With the application running on the Application Board, you can

send a command using the Intelligent Sensor Mailbox Tool.

Using the Intelligent Sensor Mailbox Tool, enter the following

command in the Bytes to Write field to configure the QR

mailboxes.

01 02 1C 0C 02 04 02 05 02 06 02 07 02 08 02 09

4. Click MB Write. This sends the command to the mailbox

application, configuring MB18:23 as Quick-Read.

Module 5




TM

68

Quick-Read Checkpoint (continued)

4. Read the mailboxes by clicking MB Read.

Note that the accelerometer data is placed in MB18:23.

MB18:23MB0

Module 5




TM

69

In theory, there could be up to 14 different user applications getting one set of QR data or

one user application getting 14 sets of QR data in a single command.

Suppose you wanted to configure more than 14 mailboxes for Quick-Read, say 16.

Clearly, it would require 2 commands.

Even though one of the earlier examples “configured” MB4, it doesn’t makes sense to start

there because it is needed for the second of the two commands and would be overwritten.

Also, it may be needed for future C/R commands. For this reason, it is a better idea to

configure the higher number mailboxes first.

For this exercise, let’s configure MB16:MB31 for Quick-Read.

There are many ways to split this up. Following the recommendation, the first command

configures MB18-31 and the second command configures MB16-17.

Quick-Read Exercise

Module 5




TM

70

For this exercise, let’s configure MB16:MB31 for Quick-Read, the last 16 bytes of the

mailboxes.

The first command first.

It is a QR configuration command so the first byte has a value of 1. For the purposes of

this discussion, CI_CMD_WRITE_CONFIG is still being used which has an Command ID

of 2. Since we are starting the configuration at MB18, what is the value for MB2 in the

command? MB3 value?

Advanced Quick-Read Exercise

Module 5




TM

71


mailboxes. First of two QR configuration commands.

Quick-Read Exercise

For the first command, MB:18-31 are configured.

For the second command, MB:16-17 are configured.

MB2 value: The offset is 28. The hexadecimal value

for 28?

MB3 value: 14 mailboxes times 2 = 28.

Module 5




TM

72



Quick-Read Exercise

The rest of the entries would have the appID of the user application providing the data. For

our purposes, it doesn’t matter, let’s say 8.

The data values from the output buffer are also not important for this discussion. Let’s say

the output buffer data corresponds to the desired mailbox configuration, i.e. output data buffer

value 0 goes into MB:16, output data buffer value 1 goes into MB:17, …, and output data

buffer value 15 goes into MB:31.

What does the rest of the first command look like?

Module 5




TM

73



Quick-Read Exercise

Now we have to create the second command to configure MB:16 and MB:17 for

QuickRead.

The first two bytes are the same as the first command, it is still QR Configuration and still

CI_CMD_WRITE_CONFIG.

Will the offset and number of bytes be the same as well? Try to determine what the third

and fourth bytes of the command before going to the next slide.

Module 5




TM

74


mailboxes. Second of two QR configuration commands.

Quick-Read Exercise

The offset for MB16 is 24 which has a hexadecimal

value of 18.

We have 2 MBs to configure. 2 times 2 is 4.

“QR” has been left in the mailbox model to remind us

not to have commands overwrite these mailboxes

going forward.

What are the last four bytes of the command?

Module 5




TM

75


mailboxes. Second of two QR configuration commands.

Quick-Read Exercise

You can carry the thought exercise further by determining how many commands are

required to configure the maximum number of mailboxes for QR.

Module 5




TM

76

Module Summary

This completes Module 5—Using the Command Interpreter.

At this point, you know how to:

• Add and remove components of ISF into the project.

• Implement a host command using the Command/Response paradigm

available in the Command Interpreter.

• Use ISF header files and the contents of the header files to develop User

Applications which can communicate with the host.

• Configure the mailboxes for Quick-Read by the host allowing the host to

access sensor data on a periodic basis.

Whenever modifying any user application, we recommend that you make

incremental changes and check your work as each change is made.

Module 5




TM

77

Next Steps

Now that you know the basics of communications between

the host and the embedded application for gaining access to

sensor data, the next major thing to learn would be to add

an external sensor using one of the sensor adapters

provided by FSL.

In Module 6, you will learn how to add an external sensor.

Module 5




trademarks of Freescale Semiconductor, Inc., Reg. U.S. Pat ... · Overview Import the Project Add...

Documents

Transcript of trademarks of Freescale Semiconductor, Inc., Reg. U.S. Pat ... · Overview Import the Project Add...