User Manual

Data Flash Access Library

16

Type T01, European Release

16 Bit Single-chip Microcontroller
RL78 Series
Installer: RENESAS_RL78_EEL-FDL_T01_PACK01_xVxx

All information contained in these materials, including products and product specifications,represents information on the product at the time of publication and is subject to change byRenesas Electronics Corp. without notice. Please review the latest information published byRenesas Electronics Corp. through various means, including the Renesas Technology Corp.
website (http://www.renesas.com).

www.renesas.com

R01US0034ED0110
September 10, 2019

Notice
1. Descriptions of circuits, software and other related information in this document are provided only to illustrate the operation ofsemiconductor products and application examples. You are fully responsible for the incorporation or any other use of the circuits,
software, and information in the design of your product or system. Renesas Electronics disclaims any and all liability for any losses anddamages incurred by you or third parties arising from the use of these circuits, software, or information.
2. Renesas Electronics hereby expressly disclaims any warranties against and liability for infringement or any other claims involving patents,
copyrights, or other intellectual property rights of third parties, by or arising from the use of Renesas Electronics products or technicalinformation described in this document, including but not limited to, the product data, drawings, charts, programs, algorithms, andapplication examples.
3. No license, express, implied or otherwise, is granted hereby under any patents, copyrights or other intellectual property rights of Renesas
Electronics or others.
4. You shall not alter, modify, copy, or reverse engineer any Renesas Electronics product, whether in whole or in part. Renesas Electronics
disclaims any and all liability for any losses or damages incurred by you or third parties arising from such alteration, modification,
copying or reverse engineering.
5. Renesas Electronics products are classified according to the following two quality grades: “Standard” and “High Quality”. The intended
applications for each Renesas Electronics product depends on the product’s quality grade, as indicated below.
“Standard”:
Computers; office equipment; communications equipment; test and measurement equipment; audio and visual equipment;
home electronic appliances; machine tools; personal electronic equipment; industrial robots; etc.
“High Quality”: Transportation equipment (automobiles, trains, ships, etc.); traffic control (traffic lights); large-scale communicationequipment; key financial terminal systems; safety control equipment; etc.
Unless expressly designated as a high reliability product or a product for harsh environments in a Renesas Electronics data sheet or otherRenesas Electronics document, Renesas Electronics products are not intended or authorized for use in products or systems that may pose adirect threat to human life or bodily injury (artificial life support devices or systems; surgical implantations; etc.), or may cause serious
property damage (space system; undersea repeaters; nuclear power control systems; aircraft control systems; key plant systems; militaryequipment; etc.). Renesas Electronics disclaims any and all liability for any damages or losses incurred by you or any third parties arisingfrom the use of any Renesas Electronics product that is inconsistent with any Renesas Electronics data sheet, user’s manual or otherRenesas Electronics document.
6. When using Renesas Electronics products, refer to the latest product information (data sheets, user’s manuals, application notes, “General
Notes for Handling and Using Semiconductor Devices” in the reliability handbook, etc.), and ensure that usage conditions are within theranges specified by Renesas Electronics with respect to maximum ratings, operating power supply voltage range, heat dissipation
characteristics, installation, etc. Renesas Electronics disclaims any and all liability for any malfunctions, failure or accident arising out of
the use of Renesas Electronics products outside of such specified ranges.
7. Although Renesas Electronics endeavors to improve the quality and reliability of Renesas Electronics products, semiconductor products
have specific characteristics, such as the occurrence of failure at a certain rate and malfunctions under certain use conditions. Unlessdesignated as a high reliability product or a product for harsh environments in a Renesas Electronics data sheet or other Renesas
Electronics document, Renesas Electronics products are not subject to radiation resistance design. You are responsible for implementing
safety measures to guard against the possibility of bodily injury, injury or damage caused by fire, and/or danger to the public in the eventof a failure or malfunction of Renesas Electronics products, such as safety design for hardware and software, including but not limited to
redundancy, fire control and malfunction prevention, appropriate treatment for aging degradation or any other appropriate measures.
Because the evaluation of microcomputer software alone is very difficult and impractical, you are responsible for evaluating the safety of
the final products or systems manufactured by you.
8. Please contact a Renesas Electronics sales office for details as to environmental matters such as the environmental compatibility of each
Renesas Electronics product. You are responsible for carefully and sufficiently investigating applicable laws and regulations that regulate
the inclusion or use of controlled substances, including without limitation, the EU RoHS Directive, and using Renesas Electronics
products in compliance with all these applicable laws and regulations. Renesas Electronics disclaims any and all liability for damages orlosses occurring as a result of your noncompliance with applicable laws and regulations.
9. Renesas Electronics products and technologies shall not be used for or incorporated into any products or systems whose manufacture, use,or sale is prohibited under any applicable domestic or foreign laws or regulations. You shall comply with any applicable export control
laws and regulations promulgated and administered by the governments of any countries asserting jurisdiction over the parties ortransactions.
10. It is the responsibility of the buyer or distributor of Renesas Electronics products, or any other party who distributes, disposes of, orotherwise sells or transfers the product to a third party, to notify such third party in advance of the contents and conditions set forth in thisdocument.
11. This document shall not be reprinted, reproduced or duplicated in any form, in whole or in part, without prior written consent of Renesas
Electronics.
12. Please contact a Renesas Electronics sales office if you have any questions regarding the information contained in this document orRenesas Electronics products.
(Note 1) “Renesas Electronics” as used in this document means Renesas Electronics Corporation and also includes its directly or indirectly
controlled subsidiaries.
(Note 2) “Renesas Electronics product(s)” means any product developed or manufactured by or for Renesas Electronics.
(Rev.4.0-1

November 2017)Table of Contents
Chapter 1
1.1

Introduction .........................................................................................................................5

Components of the EEPROM Emulation System ..................................................................... 6

1.1.1

Physical flash layer ............................................................................................................ 6

1.1.2

Flash access layer ............................................................................................................. 6

1.1.3

EEPROM access layer ...................................................................................................... 6

1.1.4

Application layer................................................................................................................. 6

1.2

Naming Conventions ................................................................................................................. 7

Chapter 2
2.1

Architecture .........................................................................................................................8

Data Flash fragmentation .......................................................................................................... 8

2.1.1

FDL pool ............................................................................................................................ 9

2.1.2

EEL pool ............................................................................................................................ 9

2.1.3

USER pool ......................................................................................................................... 9

2.2

Address virtualization .............................................................................................................. 10

2.3

Access right supervision ......................................................................................................... 11

2.4

Request-Response architecture ............................................................................................. 12

2.5

Background operation ............................................................................................................. 13

2.5.1

Background operation (Erase) ......................................................................................... 13

2.5.2

Background operation (write)........................................................................................... 14

2.5.3

Background operation (blank-check/verify) ..................................................................... 15

2.5.4

No background operation for read command .................................................................. 15

2.6

Suspension of block oriented commands (erase)................................................................... 16

Chapter 3User interface (API) ..........................................................................................................17

3.1

Run-time configuration ............................................................................................................ 17

3.2

Data types ............................................................................................................................... 18

3.2.1

Library specific simple type definitions ............................................................................ 18

3.2.2

Enumeration type “fal_command_t” ................................................................................ 18

3.2.3

Enumeration type “ fal_status_t” ...................................................................................... 19

3.2.4

Structured type “fal_request_t” ........................................................................................ 19

3.2.5

Structured type “fal_descriptor_t” .................................................................................... 20

3.3

Functions ................................................................................................................................. 22

3.3.1

Basic functional workflow................................................................................................. 22

3.3.2

Interface functions ........................................................................................................... 22

Chapter 4

Operation ..........................................................................................................................33

4.1

Blank-check ............................................................................................................................. 33

4.2

Internal verify........................................................................................................................... 34

4.3

Read ........................................................................................................................................ 35

4.4

Write ........................................................................................................................................ 35

4.5

Erase ....................................................................................................................................... 37

R01US0034ED0110

User Manual3Chapter 5

FDL usage by user application .........................................................................................38

5.1

First steps ................................................................................................................................ 38

5.2

Special considerations ............................................................................................................ 38

5.2.1

Reset consistency ............................................................................................................ 38

5.2.2

EEL+FDL or FDL only...................................................................................................... 38

5.3

File structure ........................................................................................................................... 39

5.3.1

Library for IAR V1.xx Compiler ........................................................................................ 39

5.3.2

Library for IAR V2.xx Compiler ........................................................................................ 39

5.3.3

Library for CA78K0R Compiler ........................................................................................ 40

5.4

Configuration ........................................................................................................................... 41

5.4.1

Linker sections ................................................................................................................. 41

5.4.2

Descriptor configuration (partitioning of the data flash) ................................................... 41

5.4.3

Request structure ............................................................................................................ 42

5.5

General flow ............................................................................................................................ 42

5.5.1

General flow: Initialization ................................................................................................ 42

5.5.2

General flow: commands except read ............................................................................. 43

5.5.3

General flow: read command........................................................................................... 44

5.6

Example of FDL used in operating-systems ........................................................................... 45

5.7

Example: Simple application ................................................................................................... 46

5.8

Example: Read/Write during background erase ..................................................................... 47

Chapter 6

Characteristics ..................................................................................................................49

6.1

Resource consumption ........................................................................................................... 49

6.2

Timings .................................................................................................................................... 49

6.2.1

Maximum Function Execution Times ............................................................................... 49

6.2.2

Command execution times .............................................................................................. 50

Chapter 7

Cautions ............................................................................................................................51

R01US0034ED0110

User Manual4Data Flash Access Library

Chapter 1 Introduction
This user’s manual describes the overall structure, functionality and softwareinterfaces (API) of the Data Flash Library (FDL) accessing the physical Data
Flash separated and independent from the Code Flash. This library supports
dual operation mode where the content of the Data Flash is accessible (read,
write, erase) during instruction code execution.
The Data Flash Library Type01 provides APIs for the C and assembly
language of the CA78K0R, IAR V1.xx and IAR V2.xx tool chains.(APIs for theassembly language are provided by the CA78K0R tool chain only.)
The Data Flash Library Type01 for IAR V2.xx tool chain (except linker sample
file) can also be used with the IAR V3.xx and IAR V4.xx tool chains.
The FAL (flash access layer) is a layer of EEPROM emulation system andencapsulates the low-level access to the physically flash in secure way. In
case of Data Flash this layer is using the FDL. It provides a functional socket
for Renesas EEPROM emulation software, but beside this it offers also directaccess to the user at which the access priority and access separation is fully
controlled by the library.
Figure 1-1 Components of the EEPROM emulation system

FDL-POOL (data flash)

FDL

physical data flash

flash access layer (FAL)

FDL-API

EEPROM layer
EEL

EEL-API

User application

application layer

To boost the flexibility and the real-time characteristics of the library it offers
only fast atomic functionality to read, write and erase the Data Flash memory
at smallest possible granularity. Beside the pure access commands somemaintenance functionality to check the quality of the flash content is also
provided by the library

R01US0034ED0110

User Manual5Data Flash Access Library

1.1

Components of the EEPROM Emulation System
To achieve a high degree of encapsulation the EEPROM emulation system isdivided into several layers with narrow functional interfaces.

1.1.1

Physical flash layer
The FDL is accessing the Data Flash as a physical media for storing data in
the EEPROM emulation system. The Data Flash is a separate memory thatcan be accessed independent of the Code Flash memory. This allows
background access to data stored in the Data Flash during program execution
located in the code flash. The physical Data Flash is mapped by the FDL into avirtual pool called FDL-Pool below.

1.1.2

Flash access layer
The Data Flash access layer is represented by the flash access libraryprovided by Renesas. In case of devices incorporating data-flash the FDL isrepresenting this layer. It offers all atomic functionality to access the FDL pool.
To isolate the data-flash access from the used flash-media this layer (the FDL)
is transforming thy physical addresses into a virtual, linear address-room.

1.1.3

EEPROM access layer
The EEPROM layer allows read/write access to the Data Flash at abstractlevel. It is represented by Renesas EEL or alternatively any other, user
specific implementation.

1.1.4

Application layer
The application layer is user’s application software that can use freely all
visible (specified by the API definition) commandos of upper layers. The
EEPROM layer and the flash access layer can be used asynchronously. The
FDL manages the access rights to it in a proper way.

R01US0034ED0110

User Manual

6Data Flash Access Library

1.2

Naming Conventions
Certain terms, required for the description of the Data Flash Access and
EEPROM emulation library are long and too complicated for good readabilityof the document. Therefore, special names and abbreviations will be used in
the course of this document to improve the readability.
These abbreviations shall be explained here:
Abbreviations /Acronyms
Block
Code Flash

Data Flash

Dual Operation

EEL
EEPROMemulation
FAL
FCL
FDL
Flash

Flash Block
Flash Macro

NVM
RAM
ROM
Serial programming

Single Voltage

R01US0034ED0110

User Manual

Description
Smallest erasable unit of a flash macro
Embedded Flash where the application code is stored.
For devices without Data Flash EEPROM emulation
might be implemented on that flash in the so called data
area.
Embedded Flash where mainly the data of the EEPROM
emulation are stored. Beside that also code operation
might be possible.
Dual operation is the capability to fetch code during
reprogramming of the flash memory. Current limitation isthat dual operation is only available between different
flash macros. Within the same flash macro it is notpossible!
EEPROM Emulation Library
In distinction to a real EEPROM the EEPROM emulation
uses some portion of the flash memory to emulate the
EEPROM behavior. To gain a similar behavior someside parameters have to be taken in account.
Flash Access Library (Flash access layer)
Code Flash Library (Code Flash access layer)
Data Flash Library (Data Flash access layer)“Flash EPROM” - Electrically erasable andprogrammable nonvolatile memory. The difference to
ROM is, that this type of memory can be re-programmed
several times.
A flash block is the smallest erasable unit of the flash
memory.
A flash comprises of the cell array, the sense amplifier
and the charge pump (CP). For address decoding andaccess some additional logic is needed.
Non volatile memory. All memories that hold the value,even when the power is cut off. E.g. Flash memory,
EEPROM, MRAM...
“Random access memory” - volatile memory withrandom access“Read only memory” - nonvolatile memory. The content
of that memory can not be changed.
The onboard programming mode is used to program thedevice with an external programmer tool.
For the reprogramming of single voltage flashes thevoltage needed for erasing and programming are
generated onboard of the microcontroller. No external
voltage needed like for dual- voltage flash types.

7

Data Flash Access Library

Chapter 2 ArchitectureThis chapter describes the overall architecture of the FDL library.

2.1

Data Flash fragmentation
The physical Data Flash location is fixed to a physical address assigned by the
hardware (e.g. for RL78/G13: 0xF1000 – 0xF1FFF). Just the logicalfragmentation of the Data Flash can be configured within the given range.
Following figure shows the logical fragmentation of physical Data Flash.

Figure 2-1 Logical fragmentation of physical Data Flash
0xF1FFF

Data FlashFDL pool
USER pool

Access byapplication only

EEL pool

0xF1000

R01US0034ED0110

User Manual

Access by
EEL only8

Data Flash Access Library

2.1.1

FDL pool
The FDL pool defines the maximum usage of physical Data Flash used by the
FDL. In case of physical Data Flash size of 16KByte it is possible to define thefollowing sizes for FDL pool configuration: 2KByte, 4KByte, 6KByte, 8KByte,
10KByte, 12KByte, 14KByte, 16KByte. This pool is divided into the EEL and
USER pool which are described below.

2.1.2

EEL pool
EEL pool is a part of the FDL pool and is assigned exclusively to Renesas
EEPROM Emulation Library (EEL) only. In case the EEL is not used the whole
FDL pool will be reserved for USER pool.

2.1.3

USER pool
The USER pool is a part of the FDL pool. It can be used exclusively by theapplication in a free way. In case of proprietary EEPROM emulation
implementation (user specific) the completely FDL pool has to be configured
as USER-pool.

R01US0034ED0110

User Manual9Data Flash Access Library

2.2

Address virtualization
To facilitate the access to the USER pool the physical addresses werevirtualized. The virtualized pool looks like a simple one-dimensional array of
flash-words (4 bytes).

Figure 2-2 Relationship between physical and virtual pool addresses
USER/EEL
Pool

Data Flash

0x03FF

0xF2FFF

Block 7Block 30xF2C00

0x0300

0xF2BFF

0x02FF

Block 6Block 2

0xF2800

0x0200

0xF27FF

0x01FF

Block 1

Block 50xF2400
0xF23FF

Block 4
0xF2000

USER poolFlash blockand addresstransformation

0x01000x00FF

Block 00x00000xF1FFF

Block 30xF1C00
0xF1BFF

Block 2
0xF1800

EEL pool

0xF17FF

Block 1
0xF1400
0xF13FF

Block 0
0xF1000

Physicaladdress

R01US0034ED0110

User Manualvirtual
word
index

10

Data Flash Access Library

2.3

Access right supervision
As mentioned before the complete FDL pool is divided into two parts shared
between user and the EEL. The construction of the FDL does not allow user
access to the EEL-pool and vice versa.

Figure 2-3 FDL pool access supervision

FDL pool

USER

N-1
USER pool

USER pool access)-1

N flash words(N0-0x0000FDL
EEL pool

EEL pool access

EEL

R01US0034ED0110

User Manual11Data Flash Access Library

2.4

Request-Response architecture
The communication between the requester (user) and the executor (here theFDL) is a common structured request variable. The requester can specify therequest and pass it to the FDL. After acceptance the progress of the execution
can be checked by polling the request status.
From execution-time point of view the commands of the FDL are divided into
two groups:- suspendable block-oriented command like block erase taking relatively longtime for its execution- not-suspendable word-oriented commands like write, read ... taking very
short time for its execution
Depending on the real-time requirements the user can decide if independent,
quasi-parallel execution of block and word commands is required or not. In
such a case two separate request-variables have to be defined and managed
by the application. Please refer to chapter “Operation” for details.
Following figure shows the access from requester and FDL point of view.

Figure 2-4 Request oriented communication between FDL and its requester

Requester

DATA
INDEX
COMMANDSTATUSFDL

R01US0034ED0110

User Manual12Data Flash Access Library

2.5

Background operation
Due to the fact that the Data Flash operates in the background it is possible to
do something else in the meantime. For example the application could prepare
next data for writing into the Data Flash or handle different ISRs. Background
operation is a powerful feature especially in operation systems were each task
could start FAL commands which will be executed in the background duringtask switching.

2.5.1

Background operation (Erase)
The erase command is from timing point of view the longest command. As
shown in the figure below, the application has the possibility to execute otheruser code during the background operation.

Figure 2-5 Background operation (Erase)

USER

FDL

Data Flash
hardware(background)

FAL_Execute(ERASE)FAL_BUSYFAL_Handler()

FAL_BUSYFAL_Handler()

Erase
FAL_BUSYFAL_Handler()

FAL_BUSYFAL_Handler()

FAL_OK

R01US0034ED0110

User Manual13Data Flash Access Library

2.5.2

Background operation (write)
During the running write command blank-check/write/verify will be performed
in background. As shown in the figure below, the application has the possibility
to execute other user code during the background operation.

Figure 2-6 Background operation (write)

USER

FDL

Data Flash
hardware(background)

FAL_Execute(WRITE)FAL_BUSY

BlankCheck

FAL_Handler()

FAL_BUSYFAL_Handler()

Write
FAL_BUSYFAL_Handler()

FAL_BUSY

VerifyFAL_Handler()

FAL_OK

R01US0034ED0110

User Manual14

Data Flash Access Library

2.5.3

Background operation (blank-check/verify)
Same procedure as for erase the verify or blank-check will be performed inbackground.

Figure 2-7 Background operation (blank-check/verify)

USER

FDL

Data Flash
hardware(background)

FAL_Execute(BC/VI)

FAL_BUSY

BlankCheck/
VerifyFAL_Handler()

FAL_BUSYFAL_Handler()

FAL_OK

2.5.4

No background operation for read command
The read command doesn’t use the background operation. It’s directly finishedafter the request acceptance.

Figure 2-8 No background operation for read command

USER

FDL

Data Flash
hardware(background)

FAL_Execute(read)

FAL_OK

R01US0034ED0110

User Manual15

Data Flash Access Library

2.6

Suspension of block oriented commands (erase)
In cases of systems working under critical real-time conditions, immediately
read/write access to the data is a must. In such cases, separate request
variables must be defined for word command accesses and block command
accesses. Both types of access are managed separately on FDL andrequester side.
The suspension and resumption of the running block command (erase) is
managed automatically according to the following rules- word commands cannot be suspended- each block command can be suspended by any word command- User requested block command does always suspend running blockcommands of the EEL- EEL requested block commands cannot suspend running user blockcommandIn other words:- word commands have always higher priority than block commands- user access have always higher priority than EEL (running in background)
The following table shows dependencies between running and requested
commands of EEL or user.

Table 2-1 Block command suspension rules
command acceptancerequestedcommand

WCMD
(eel)
WCMD
(user)
BCMD
(eel)
BCMD
(user)

rejectedrunning command
WCMD
BCMD
(user)(eel)
suspend/rejectedresume***suspend/rejectedresume

BCMD(user)
suspend/resumesuspend/resume***rejected

rejected

rejected

rejected

rejected

WCMD
(eel)
rejected

rejectedsuspend/resumerejected

Agenda:
WCMD = word command
BCMD = block command,
rejected = requested command is rejectedsuspend = running block command is suspended*** when the address of the WCMD refers to the block addressed by BCMD
the WCMD will be rejected too.

R01US0034ED0110

User Manual16

Data Flash Access Library

Chapter 3 User interface (API)
3.1

Run-time configuration
During runtime the configuration of the FDL can be changed dynamically. To
be able to do it more than one descriptor constant has to be defined by theuser in advance. Depends on the application mode different descriptors can bechosen for the FAL_Init(...) function.
/*
/*
/*

................... */some code*/................... *//* load standard descriptor */my_status=FAL_Init(&fal_descriptor_str);
/*
/*
/*

................... */some code*/................... */FAL_Close();EEL_Close();/* close USER part of the FAL pool *//* close EEL part of the FAL pool *//* - but only if necessary, means *//*if EEL used in system*//* load alternative descriptor*/
my_status=FAL_Init(&fal_descr_2_str);
/*
/*
/*

................... */some code*/................... */Note: Before changing FAL pool configuration by using of different FAL pooldescriptor the user has to close the FAL (USER part of the pool) in any case.
In case that the EEL is active in the system, the EEL part of the FAL-pool has
to be closed by using EEL_Close() too.

R01US0034ED0110

User Manual17Data Flash Access Library

3.2

Data types
This chapter describes all data definitions used by the FDL.

3.2.1

Library specific simple type definitions
This type defines simple numerical type used by the library

typedef unsigned chartypedef unsigned int
typedef unsigned long int

3.2.2

fal_u08;
fal_u16;
fal_u32;

Enumeration type “fal_command_t”
This type defines all codes of available commands

typedefenum{
FAL_CMD_UNDEFINEDFAL_CMD_BLANKCHECK_WORD
FAL_CMD_IVERIFY_WORD
FAL_CMD_READ_WORD
FAL_CMD_WRITE_WORD
FAL_CMD_ERASE_BLOCK} fal_command_t;= (0x00),= (0x00 | 0x01),= (0x00 | 0x02),= (0x00 | 0x03),= (0x00 | 0x04),= (0x00 | 0x05),

Code value description:
FAL_CMD_UNDEFINEDFAL_CMD_BLANKCHECK_WORD
FAL_CMD_IVERIFY_WORD
FAL_CMD_READ_WORD
FAL_CMD_WRITE_WORD
FAL_CMD_ERASE_BLOCK

R01US0034ED0110

User Manual- default value- blank-check of 1 Data Flash word
- verify of 1 Data Flash word
- read 1 Data Flash word
- write 1 Data Flash word
- erases 1 Data Flash block18

Data Flash Access Library

3.2.3

Enumeration type “ fal_status_t”
This enumeration type defines all possible status- and error-codes can begenerated during data-flash access via the FDL. The FAL_OK and FAL_BUSY
status are returned to the requester during normal operation. Other codes
signalize problems.
typedefenum{/* operation related status --------------*/FAL_OK= (0x00),
FAL_BUSY= (0x00 | 0x01),/* run-time error related status ---------*/
FAL_ERR_PROTECTION= (0x10 | 0x00),
FAL_ERR_BLANKCHECK= (0x10 | 0x01),
FAL_ERR_VERIFY= (0x10 | 0x02),
FAL_ERR_WRITE= (0x10 | 0x03),
FAL_ERR_ERASE= (0x10 | 0x04),/* configuration error related status ----*/
FAL_ERR_PARAMETER= (0x20 | 0x00),
FAL_ERR_CONFIGURATION= (0x20 | 0x01),
FAL_ERR_INITIALIZATION= (0x20 | 0x02),
FAL_ERR_COMMAND= (0x20 | 0x03),
FAL_ERR_REJECTED= (0x20 | 0x04)} fal_status_t;

Status value
FAL_OK
FAL_BUSY
FAL_ERR_PROTECTION
FAL_ERR_BLANKCHECKFAL_ERR_VERIFY
FAL_ERR_WRITE
FAL_ERR_ERASEFAL_ERR_PARAMETER
FAL_ERR_CONFIGURATIONFAL_ERR_INITIALIZATIONFAL_ERR_COMMAND
FAL_ERR_REJECTED

3.2.4

Description
default value, ready, no error detected
request is accepted and is being processed
access outside permitted pool area
specified flash-word is not blankspecified flash-word could not be verified
write is failed
block erase is failed
not relevant for the FDL (defined for future
improvements)
Wrong values configured in descriptor
FDL not initialized or not opened
wrong command code used
when FDL busy with another request

Structured type “fal_request_t”
This type is used for definition of request variables and used for informationexchange between the application and the FDL. A request variable is passed
to the FDL to initiate a command and can be used by the requester (EEL,
application...) to check the status of its execution.
/* FAL request type (base type for any FAL access) */typedef struct {fal_u32
data_u32;
fal_u16
index_u16;
fal_command_t
command_enu;
fal_status_t
status_enu;} fal_request_t;

R01US0034ED0110

User Manual19Data Flash Access Library

Struct member
data_u32
index_u16
command_enu
status_enu

3.2.5

Description
32-bit buffer for data exchange during read/write
accessvirtual word index within the targeted poolcommand code
request status code (feedback)

Structured type “fal_descriptor_t”
This type defines the structure of the FDL descriptor. It contains all
characteristics of the FDL. It is used in the fdl_descriptor.c file for definition of
the ROM constant fal_descriptor_str.
Based on configuration data inside the fdl_descriptor.h the initialization data ofdescriptor constant is generated automatically in the fdl_descriptor.c.
/* FAL descriptor type */typedef struct {fal_u32
fal_pool_first_addr_u32;
fal_u32
eel_pool_first_addr_u32;
fal_u32
user_pool_first_addr_u32;
fal_u32
fal_pool_last_addr_u32;
fal_u32
eel_pool_last_addr_u32;
fal_u32
user_pool_last_addr_u32;
fal_u16
fal_pool_first_block_u16;
fal_u16
eel_pool_first_block_u16;
fal_u16
user_pool_first_block_u16;
fal_u16
fal_pool_last_block_u16;
fal_u16
eel_pool_last_block_u16;
fal_u16
user_pool_last_block_u16;
fal_u16
fal_first_widx_u16;
fal_u16
eel_first_widx_u16;
fal_u16
user_first_widx_u16;
fal_u16
fal_last_widx_u16;
fal_u16
eel_last_widx_u16;
fal_u16
user_last_widx_u16;
fal_u16
fal_pool_wsize_u16;
fal_u16
eel_pool_wsize_u16;
fal_u16
user_pool_wsize_u16;
fal_u16
block_size_u16;
fal_u16
block_wsize_u16;
fal_u08
fal_pool_size_u08;
fal_u08
eel_pool_size_u08;
fal_u08
user_pool_size_u08;
fal_u08
fx_MHz_u08;
fal_u08
wide_voltage_mode_u08;} fal_descriptor_t;

R01US0034ED0110

User Manual20Data Flash Access Library

Struct member
fal_pool_first_addr_u32
eel_pool_first_addr_u32
user_pool_first_addr_u32
fal_pool_last_addr_u32
eel_pool_last_addr_u32
user_pool_last_addr_u32
fal_pool_first_block_u16
eel_pool_first_block_u16
user_pool_first_block_u16
fal_pool_last_block_u16
eel_pool_last_block_u16
user_pool_last_block_u16
fal_first_widx_u16
eel_first_widx_u16
user_first_widx_u16
fal_last_widx_u16
eel_last_widx_u16
user_last_widx_u16
fal_pool_wsize_u16
eel_pool_wsize_u16
user_pool_wsize_u16
block_size_u16
block_wsize_u16
fal_pool_size_u08
eel_pool_size_u08
user_pool_size_u08

Description
first physical address of the FAL poolfirst physical address of the EEL poolfirst physical address of the USER poollast physical address of the FAL poollast physical address of the EEL poollast physical address of the USER poolfirst virtual block of the FAL poolfirst virtual block of the EEL poolfirst virtual block of the USER poollast virtual block of the FAL poollast virtual block of the EEL poollast virtual block of the USER poolfirst virtual word-index inside the FAL poolfirst virtual word-index inside the EEL poolfirst virtual word-index inside the USER poollast virtual word-index inside the FAL poollast virtual word-index inside the EEL poollast virtual word-index inside the USER poolsize of the FAL pool expressed in words
size of the EEL pool expressed in words
size of the USER pool expressed in words
size of one Data Flash block expressed in bytes
size of one Data Flash block expressed inwords
size of the FAL pool expressed in blocks
size of the EEL pool expressed in blocks(Note 1, 2)
size of the USER pool expressed in blocks(Note 1, 2)

fx_MHz_u08

Frequency of user clock(Note 3)

wide_voltage_mode_u08

selection of flash memory programming mode
0: full speed mode
1: wide voltage mode

Note 1: the sum of eel_pool_size_u08 and user_pool_size_u08 must notexceed fal_pool_size_u08.
Note 2: both descriptor configuration conditions will be checked by
FAL_Init(...)
Note 3: User frequency ( frequency >= 4MHz)
Frequency must be rounded up as shown below:
descr.fsl_frequency_u08 = 20 for 20000000Hz
descr.fsl_frequency_u08 = 24 for 23100000Hz
User frequency ( frequency < 4MHz)
In case the frequency is smaller than 4MHz the only supported
physical frequencies are the following:
descr.fsl_frequency_u08 = 1 for 1000000Hz
descr.fsl_frequency_u08 = 2 for 2000000Hz
descr.fsl_frequency_u08 = 3 for 3000000Hz

R01US0034ED0110

User Manual21Data Flash Access Library

3.3

FunctionsDue to the request oriented interface of the FDL the functional interface is very
narrow. Beside the initialization function and some administrative function thewhole flash access is concentrated to two functions only: FAL_Execute(...)
and FAL_Handler().

3.3.1

Basic functional workflow
To be able to use the FDL (execute pool-related commands) in a proper way
the requester has to follow a specific startup and shutdown procedure.
Figure 3-1 Basic workflow flow

Power OFFON
FAL_Init()OFF

closedFAL_Open()

FAL_Close()

openedFAL_Execute(CMD)
where CMD =status = NOT busy

READ_WORD,
WRITE_WORD,
BLANKCHECK_WORD,IVERIFY_WORD,
ERASE_BLOCK

busy

FAL_Handler()

3.3.2

Interface functions
The interface functions create the functional software interface of the library.
They are prototyped in the header file fdl.h.

R01US0034ED0110

User Manual22Data Flash Access Library

3.3.2.1 FAL_Init
Description
Initialization of all internal data.
C interface for CA78K0R compiler
fal_status_t __far FAL_Init(const __far fal_descriptor_t*
descriptor_pstr);

C interface for IAR V1.xx compiler__far_func fal_status_t FAL_Init(const __far fal_descriptor_t__far* descriptor_pstr);

C interface for IAR V2.xx compiler__far_func fal_status_t FAL_Init(const fal_descriptor_t__far * descriptor_pstr);

Pre-condition
Internal high-speed oscillator is running.
Post-condition
Initialization is done.
Argument
ArgumentTypedescriptor_pstr

fal_descriptor_t

Description
Pointer to the descriptor (describing the
FDL configuration). The virtualization of
the data-flash address-room is done
based on that descriptor. The user canuse different descriptors to switch
between different FDL-pool
configurations.

Return types/values

R01US0034ED0110

User Manual

Value

Type

fal_status

fal_status_t

Description
FAL_ERR_CONFIGURATION
when descriptor data are not plausible.
FAL_OK when descriptor correct andinitialization successful.

23

Data Flash Access Library

Usage
fal_status_t my_status;
my_status = FAL_Init(&fal_descriptor_str);
if(my_status == FAL_OK){/* FDL can be used /}else{/ error handler */}R01US0034ED0110

User Manual24Data Flash Access Library

3.3.2.2 FAL_Open
Description
This function must be used by the application to activate the data-flash. It turns
on the data flash clock if necessary.
Please note that this function includes the necessary delay for the data flash
clock setup. The data flash is operational and can be used right after function
exit.
C interface for CA78K0R compiler
void __far FAL_Open(void);

C interface for IAR V1.xx compiler__far_func void FAL_Open(void);

C interface for IAR V2.xx compiler__far_func void FAL_Open(void);

Pre-condition
FAL_Open() does not check any precondition, but FAL_Init(...) has to be
executed successfully already.
Post-condition
Data flash clock is switched on.
Argument
Argument
None

Type

Description

Return types/values
Value
None

Type

Description

Usage
FAL_Open();

R01US0034ED0110

User Manual25Data Flash Access Library

3.3.2.3 FAL_Close
Description
This function deactivates the data flash.
C interface for CA78K0R compiler
void__far FAL_Close(void);

C interface for IAR V1.xx compiler__far_func void

FAL_Close(void);

C interface for IAR V2.xx compiler__far_func void

FAL_Close(void);

Pre-condition
None
Post-condition
Data flash clock is switched off. In case of FAL and EEL usage both
FAL_Close and EEL_Close must be called for switching off the Data Flash.
Argument
Argument
None

Type

Description

Return types/values
Value
None

Type

Description

Usage

FAL_Close();R01US0034ED0110

User Manual26

Data Flash Access Library

3.3.2.4 FAL_Execute
Description
This is the main function of the FDL the application can use to initiate
execution of any command. Please refer to the chapter “Operation” fordetailed explanation of each command.
C interface for CA78K0R compiler
void __far FAL_Execute(__near fal_request_t* request_pstr);

C interface for IAR V1.xx compiler__far_func void FAL_Execute(__near fal_request_t __near*request_pstr);

C interface for IAR V2.xx compiler__far_func void FAL_Execute(fal_request_t __near *request_pstr);

Pre-condition
FAL_Init() executed successfully with status FAL_OK.
FAL_Open() executed already.
Post-condition
None
Argument
Argument
request_pstr

Type
fal_request_t

Description
This argument defines the command
which should be executed by FDL. It is arequest variable which is used for bidirectional information exchange before
and during execution between FDL andthe application.

Return types/values
Value
None

R01US0034ED0110

User ManualType

Description

27

Data Flash Access LibraryUsage__near fal_request_t

my_fal_WCMD_request_str;

my_fal_WCMD_request.data_u32 = 0x12345678;
my_fal_WCMD_request.index_u16 = 0x0123;
my_fal_WCMD_request.command_enu = FAL_CMD_WRITE_WORD;/* command initiation */do {FAL_Execute(&my_fal_WCMD_request);
FAL_Handler();/* proceed background process */} while (my_fal_WCMD_request.status_enu == FAL_ERR_REJECTED);/* command execution */do {FAL_Handler();} while (my_fal_WCMD_request.status_enu == FAL_BUSY);
if(my_fal_WCMD_request.status_enu != FAL_OK) error_handler();

R01US0034ED0110

User Manual28Data Flash Access Library

3.3.2.5 FAL_Handler
Description
This function is used by the application to proceed the execution of acommand running in the background. In case of the FDL the functionality of
the Handler is reduce to simple status polling of the running backgroundcommand. In case any background command was suspended in the past, the
FAL_Handler takes care for the resume-process.
C interface for CA78K0R compiler
void__far FAL_Handler(void);

C interface for IAR V1.xx compiler__far_func void

FAL_Handler(void);

C interface for IAR V2.xx compiler__far_func void

FAL_Handler(void);

Pre-condition
FAL_Init() executed successfully with status FAL_OK.
FAL_Open() executed already.
Post-condition
In case of finished command the status is written to the request structure.
Argument
Argument
None

Type

Description

Return types/values
Value
None

R01US0034ED0110

User ManualType

Description

29

Data Flash Access Library

Usage/* infinite scheduler loop */do {/* proceed potential command execution */FAL_Handler();/* 20ms time slize (potential FAL requester) */MyTask_A(20);/* 10ms time slize (potential FAL requester) */MyTask_B(10);/* 40ms time slize (potential FAL requester) */MyTask_C(40);/* 10ms time slize (potential FAL requester) */MyTask_D(10);} while (true);

R01US0034ED0110

User Manual30Data Flash Access Library

3.3.2.6 FAL_GetVersionString
Description
This function provides the internal version information of the used library.
C interface for CA78K0R compiler__far fal_u08* __far FAL_GetVersionString(void);

C interface for IAR V1.xx compiler__far_func fal_u08 __far*

FAL_GetVersionString(void);

C interface for IAR V2.xx compiler__far_func fal_u08 __far *FAL_GetVersionString(void);

Pre-condition
None
Post-condition
None
Argument
Argument
None

Type

Return types/values
Value
Type
fal_u08 __far*

Description

Description
Pointer to the first character of a zeroterminated version string.

Usage (CA78K0R compiler)__far const fal_u08 *my_version_string;my_version_string = FAL_GetVersionString();

Usage (IAR V1.xx and V2.xx compiler)
fal_u08 __far* my_version_string;my_version_string = FAL_GetVersionString();

R01US0034ED0110

User Manual31Data Flash Access Library

Description of the version string
For version control at runtime the developer can use this function to find thestarting character of the library version string (ASCII format).
The version string is a zero-terminated string constant that covers library-specificinformation and is based on the following structure: NMMMMTTTCCCCCGVVV..V,
where:•

N: library type specifier (here ‘D’ for FDL)

•

MMMM

: series name of microcontroller (here ‘RL78’)•

TTT: type number (here ‘T01’)

•

CCCCC

: compiler information (4 or 5 characters)‘Rxyy’‘Ixyy’‘Lxyyz’for CA78K0R compiler
for IAR V1.xx compiler
for IAR V2.xx compiler: all memory models (here ‘G’ for general): library version
for release version x.yy
for engineering version x.yyy

•
•
•
•
•

G
VVV..V•‘Vxyy’•‘Exyyy’Examples:The version string of the FDL V1.12 for the CA78K0R compiler is:"DRL78T01R110GV112"
The version string of the FDL V1.12 for the IAR V1.xx compiler is:"DRL78T01I120GV112"
The version string of the FDL V1.12 for the IAR V2.xx compiler is:"DRL78T01L1000GV112"

R01US0034ED0110

User Manual32

Data Flash Access Library

Chapter 4 Operation
4.1

Blank-check
The blank-check operation can be used to check if all bits within the addressed
pool-word are still “erased”. The user can use blank-check command freely.
The blank-check command is initiated by FAL_Execute() and must becontinued by FAL_Handler() as long as command is not finished (requeststatus updated).

Table 4-1 Status of FAL_CMD_BLANKCHECK_WORD command

R01US0034ED0110

User Manual

StatusClass

FAL_ERR_INITIALIZATION

heavy

FAL_ERR_PROTECTION

heavy

FAL_ERR_REJECTED

normalFAL_ERR_BLANKCHECK

normalFAL_BUSY

normalFAL_OK

normalBackground and Handling
FDL not initialized or
meaning
not opened
wrong handling on user
reasonside
Initialize and open FDL
remedybefore using it
request cannot bemeaning
accepted
word index is outside
reasonthe corresponding poolset correct word index
remedyand try again
FDL driver cannot
meaning
accept the request
FDL driver is busy with
an other word
reasoncommand or blockcommand (in case ofsame block).
Call FAL_Handler as
remedylong as request isn’t
accepted.
specified flash-word ismeaning
not blank
any bit in the flash
reasonword addressed byword index isn’t erased
nothing, free
remedyinterpretation atrequester side
request is being
meaning
processedrequest checked andreasonaccepted
nothing, call
remedyFAL_Handler until
status changes
request was finishedmeaning
regularno problems during
reasoncommand execution
happens
remedynothing33

Data Flash Access Library

4.2

Internal verify
The internal verify operation can be used to check if all bits (0’s and 1’s) areelectronically correct written. Inconsistent and weak data caused byasynchronous RESET can be detected by using the verify command. The user
can uses verify freely to check the quality of user data. The verify command isinitiated by FAL_Execute() and must be continued by FAL_Handler() as longas command is not finished (request-status updated).

Table 4-2 Status of FAL_CMD_IVERIFY_WORD command

R01US0034ED0110

User Manual

StatusClass

FAL_ERR_INITIALIZATION

heavy

FAL_ERR_PROTECTION

heavy

FAL_ERR_REJECTED

normalFAL_ERR_VERIFY

normalFAL_BUSY

normalFAL_OK

normalBackground and Handling
FDL not initialized or
meaning
not opened
wrong handling on user
reasonside
Initialize and open FDL
remedybefore using it
request cannot bemeaning
accepted
word index is outside
reasonthe corresponding poolset correct word index
remedyand try again
FDL driver cannot
meaning
accept the request
FDL driver is busy with
an other word
reasoncommand or blockcommand (in case ofsame block).
Call FAL_Handler as
remedylong as request isn’t
accepted.
specified flash-word inmeaning pool could not be
verifiedany bit in thereasonaddressed flash word
isn’t electrically correct
nothing, free
remedyinterpretation atrequester side
request is being
meaning
processedrequest checked andreasonaccepted
nothing, call
remedyFAL_Handler until
status changes
request was finishedmeaning
regularno problems during
reasoncommand execution
happens
remedynothing34

Data Flash Access Library

4.3

Read
The read operation can be used to read the content of the addressed poolword. It is initiated and finished directly by FAL_Execute(). FAL_Handler() isnot needed in that case.

Table 4-3 Status of FAL_CMD_READ_WORD command
StatusClass

FAL_ERR_INITIALIZATION

heavy

FAL_ERR_PROTECTION

heavy

FAL_ERR_REJECTED

normalBackground and Handling
FDL not initialized or
meaning
not opened
wrong handling on user
reasonside
Initialize and open FDL
remedybefore using it
request cannot bemeaning
accepted
word index is outside
reasonthe corresponding poolset correct word index
remedyand try again
FDL driver cannot
meaning
accept the request

reasonremedymeaning
FAL_OK

normalreasonremedy4.4

FDL driver is busy with
an other wordcommand or blockcommand (in case ofsame block).
Call FAL_Handler aslong as request isn’t
accepted.
request was finishedregularno problems duringcommand execution
happens
nothing

Write
The write operation writes 32-bit data into passed word index. To protect
existing flash data against accidental overwrite 1-word blank-check is
executed in advance. After that the write-command is initiated. In case of
successfully finished writing the quality of data will be checked via internalverify.

Table 4-4 Status of FAL_CMD_WRITE_WORD command

R01US0034ED0110

User Manual

StatusClass

FAL_ERR_INITIALIZATION

heavy

Background and Handling
FDL not initialized or
meaning
not opened
wrong handling on user
reasonside
Initialize and open FDL
remedybefore using it

35

Data Flash Access Librarymeaning
FAL_ERR_PROTECTION

heavy

reasonremedymeaning

FAL_ERR_REJECTED

normalreasonremedymeaning

FAL_ERR_BLANKCHECK

normalreasonremedymeaning
FAL_ERR_WRITE

normalreasonremedymeaning
FAL_ERR_VERIFY

normalreasonremedymeaning

FAL_BUSY

normalreasonremedymeaning

FAL_OK

normalreasonremedyR01US0034ED0110

User Manual

request cannot be
accepted
word index is outside
the corresponding poolset correct word index
and try again
FDL driver cannot
accept the request
FDL driver is busy with
an other wordcommand or blockcommand (in case ofsame block).
Call FAL_Handler aslong as request isn’t
accepted.
specified flash-word inpool is not blank, write
was not performed, thecontent of flash-word
remains untouchedoverwriting of nonerased flash words is
not allowed
erase the block before
writing again into thisblock
flash word addressedby word index couldn’t
be written correctly
after performing themax. number of retries
flash problems
erase the block and try
to write again into thisblock
after writing the data
the flash word could
not be verified
flash problems
erase the block and try
to write again into thisblock
request is being
processedrequest checked andaccepted
nothing, call
FAL_Handler until
status changes
request was finishedregularno problems duringcommand execution
happens
nothing36

Data Flash Access Library

4.5

Erase
The erase operation can be used to erase one block of the related pool. After
starting the erase-command the hardware is checking if the addressed block isalready blank to avoid unnecessary erase cycles. After that the erasecommand is initiated.

Table 4-5 Status of FAL_CMD_ERASE_BLOCK command
StatusR01US0034ED0110

User ManualClass

FAL_ERR_INITIALIZATION

heavy

FAL_ERR_PROTECTION

heavy

FAL_ERR_REJECTED

normalFAL_ERR_ERASE

fatal

FAL_BUSY

normalFAL_OK

normalBackground and Handling
FDL not initialized or
meaning
not opened
wrong handling on user
reasonside
Initialize and open FDL
remedybefore using it
request cannot bemeaning
accepted
block number outside
reasonthe corresponding poolcorrect block number
remedyand try again
FDL driver cannot
meaning
accept the request
FDL driver is busy with
an other word
reason command or blockcommand (in case ofsame block).
Call FAL_Handler as
remedylong as request isn’t
accepted.
specified flash block
meaning
could not be erased
reasoninternal flash problems
do not use this block
remedyanymorerequest is being
meaning
processedrequest checked andreasonaccepted
nothing, call
remedyFAL_Handler until
status changes
request was finishedmeaning
regularno problems during
reasoncommand execution
happens
remedynothing37

Data Flash Access Library

Chapter 5 FDL usage by user application
5.1

First steps
It is very important to have theoretic background about the Data Flash and the
FDL in order to successfully implement the library into the user application.
Therefore it is important to read this user manual in advance especiallychapter “Cautions”.

5.2

Special considerations

5.2.1

Reset consistency
During the execution of FDL commands a reset could occur and the data could
be damaged. In such cases it should be considered whether to uses twovariables for same data and so on. In other words please consider such reset
scenarios to avoid invalid data. The EEL provided by Renesas Electronics isdesigned to avoid read of invalid data cause by such reset scenarios. The
following chapter describes the applications where the EEL should be used.

5.2.2

EEL+FDL or FDL only
Depending on the security level of the application, write frequency of variables
and variables count it should be considered whether to uses the EEL+FDL or
the FDL only.

5.2.2.1 FDL only
By using the FDL only the application has to take care about all reset
scenarios and writing flow of different variables with different sizes.
Application scenarios- Programming of initial or calibration data
- user specific EEPROM emulation
5.2.2.2 EEL+FDL
The duo of EEL and FDL allows the user to uses the EEL for high write
frequency of different variables with different sizes in a secure way andadditionally the USER pool is available for free usage.
Application scenarios- Programming of initial or calibration data
- Large count of variables and high write frequency by using the EEL- Secure data handling completely handled by EEL

R01US0034ED0110

User Manual38Data Flash Access Library

5.3

File structure

5.3.1

Library for IAR V1.xx Compiler[root]
Release.txt
support.txt

Library release notes
Library support information[root]\[IAR_1xx]\[FDL]\[lib]fdl.h
fdl_types.h
fdl.r87

FDL library
FDL interface definition
FDL types definition
Pre-compiled library[root]\[IAR_1xx]\[FDL]\[Sample]\[C]
fdl_descriptor.cDescriptor calculation partfdl_descriptor.hPool configuration partfdl_sample_linker_file.xcl
Sample Linker file

5.3.2

Library for IAR V2.xx Compiler[root]
Release.txt
support.txt

Library release notes
Library support information[root]\[IAR_2xx]\[FDL]\[lib]fdl.h
fdl_types.hfdl.a

FDL library
FDL interface definition
FDL types definition
Pre-compiled library[root]\[IAR_2xx]\[FDL]\[Sample]\[C]
fdl_descriptor.cDescriptor calculation partfdl_descriptor.hPool configuration partfdl_sample_linker_file.icf
Sample Linker file

R01US0034ED0110

User Manual39Data Flash Access Library

5.3.3

Library for CA78K0R Compiler[root]
Release.txt
support.txt

Library release notes
Library support information[root]\[CA78K0R_xxx]\[FDL]\[lib] FDL libraryfdl.h
FDL interface definition (Compiler)
fdl.inc
FDL interface definition (Assembler)
fdl_types.h
FDL types definition
fdl.lib
Pre-compiled library[root]\[CA78K0R_xxx]\[FDL]\[Sample]\[C]
Sample folder for C-Compiler projects
fdl_descriptor.cDescriptor calculation partfdl_descriptor.hPool configuration partfdl_sample_linker_file.dr
Sample Linker file[root]\[CA78K0R_xxx]\[FDL]\[Sample]\[asm]Sample folder for Assembler projects
fdl_descriptor.asm
Descriptor calculation partfdl_descriptor.inc
Pool configuration partfdl_sample_linker_file.dr
Sample Linker file

R01US0034ED0110

User Manual40Data Flash Access Library

5.4

Configuration

5.4.1

Linker sections
Following segments are defined by the library and must be configured via thelinker description file.
FAL_CODE

Segment for library code.
Can be located anywhere in the code flash.

FAL_CNST

Segment for library constants like descriptor.
Can be located anywhere in the code flash.

FAL_DATA

Segment for library data.
Must be located inside the SADDR RAM

NOTE: FAL_CODE and FAL_CNST segments must be located anywhere in
the Code Flash but inside the same 64 KByte page.

5.4.2

Descriptor configuration (partitioning of the data flash)
Before the FDL can be used the FDL pool and it’s partitioning has to be
configured first. The descriptor is defining the physical/virtual addresses andparameter of the pool which will be automatically calculated by using the
FAL_POOL_SIZE and EEL_POOL_SIZE definition.
Because the physical starting address of the data flash is fixed by the
hardware the user can only determine the total size of the pool expressed inblocks. Also the physical size of the pool is limited by the hardware and mustnot be defined by the user. Also the physical size of a flash block is apredefined constant determined by the used hardware.
The first configuration parameter is FAL_POOL_SIZE. The minimum value is 0
and means any access to the FDL-pool is closed. The maximum value is thedata flash size expressed in blocks.
The other configuration parameter is EEL_POOL_SIZE, the size of the EELpool within the FDL-pool used exclusively for Renesas EEPROM emulation
library only. The minimum size of the EEL-pool is 0. This means the complete
FDL pool is occupied by the user for storing data. But also when a proprietary
EEPROM emulation is implemented by the user the complete pool has to bereserved for it by specifying EEL_POOL_SIZE=0. The maximum size of the
EEL-pool is FAL_POOL_SIZE.
Notes:- The USER pool and EEL pool are complementary. This means: the USER
pool is always the remaining none-EEL-pool (in other words
USER_POOL_SIZE = FAL_POOL_SIZE – EEL_POOL_SIZE).
- The virtual address 0 of the user-pool corresponds with the successor of thelast EEL-pool word.

R01US0034ED0110

User Manual41

Data Flash Access Library

5.4.3

Request structure
Depending on the user application architecture more than one request variable
could be necessary. For example if an immediate write is necessary duringrunning erase. In such a case two request variables (one for write and one forerase) are necessary. Please take care that each request variable is locatedon an even address.

5.5

General flow

5.5.1

General flow: Initialization
The following figure illustrates the initialization flow.

Figure 5-1 Initialization flow

FAL_Init

status?

FAL_ERR_CONFIGURATIONFAL_OK

FAL_Open

Execute any FAL
commands

FAL_Close

R01US0034ED0110

User Manual

Error handler

42

Data Flash Access Library

5.5.2

General flow: commands except read
After initialization of the environment the application can uses the commands
provided by the library. The following figure illustrates the general flow ofcommand (except read command) execution.

Figure 5-2 FAL command execution (except read command)................

fill request
CMD
FAL_Execute(CMD)

FAL_Handler()
FAL_ERR_REJECTED

status?

OTHER

FAL_BUSYFAL_Handler()

FAL_BUSY

status?

OTHER

FAL_OK................

Error handler

In case the requested command is rejected the application has to call the
FAL_Handler() for finishing/suspend the background command and try to
execute the command again.

R01US0034ED0110

User Manual43

Data Flash Access Library

5.5.3

General flow: read command
The difference between the read command and other commands(erase/write/verify/blank-check) is that the read command will be completed
directly during FAL_Execute() function. That means no additionally
FAL_Handler() calls are required.

Figure 5-3 FAL read command execution................

fill request
CMD(read)
FAL_Execute(CMD)

FAL_Handler()
FAL_ERR_REJECTED

status?

OTHER

FAL_OK................

Error handler

In case the requested command is rejected the application has to call the
FAL_Handler() for finishing/suspend the background command and try to
execute the command again.

R01US0034ED0110

User Manual44Data Flash Access Library

5.6

Example of FDL used in operating-systems
The possibility of background operation and request-response structure of the
FDL allows the user to uses the FDL in an efficient way in operating systems.
Note: Please read the chapter “Cautions” carefully before using the FDL
in such operating systems.
The following figure illustrates a sample operating system where the FDL is
used for Data Flash access.

Figure 5-4 FDL used in an operating system

operating system
Task 1 (each 50ms)
if(req1.status != FAL_BUSY)
FAL_Execute(req1)

Task 2 (each 100ms)
if(req2.status != FAL_BUSY)
FAL_Execute(req2)

IDLE Task (each 2ms)
FAL_Handler()

Task 3 (emergency task)do{
FAL_Execute(req_et)
FAL_Handler();} while(req_et.status == rejected);
while(req_et.status == FAL_BUSY)FAL_Handler()This sample operating system shows three different task types which aredescribed below.
Task 1 and Task 2This task type is a requesting task like Task 1 and 2. Such tasks just start any
FDL command via the FAL_Execute function and assume that it will befinished in the background via the IDLE task.
IDLE task
The IDLE task will be used by the application for continuing any running FAL
command. That means the FAL_Handler must be called inside of such a task.
R01US0034ED0110

User Manual45Data Flash Access Library

Emergency task
The difference between this task type and the requesting type (Task 1 andTask 2) is that this task performs any FAL commands completely without
waiting in the background. Such task can be used in case of voltage drop
where important data must be saved before the device is off.

5.7

Example: Simple application
The following sample shows how to use each command in a simple way.

extern __far const fal_descriptor_t
fal_status_t__near fal_request_t

fal_descriptor_str;
my_fal_status_enu;
request;/* initialization */my_fal_status_enu = FAL_Init((__far fal_descriptor_t*)&fal_descriptor_str );if(my_fal_status_enu != FAL_OK) ErrorHandler();
FAL_Open();/* erase block 0 */request.index_u16= 0x0000;
request.command_enu = FAL_CMD_ERASE_BLOCK;FAL_Execute(&request);
while(request.status_enu == FAL_BUSY) FAL_Handler();if(request.status_enu != FAL_OK)
ErrorHandler();/* write patter 0x12345678 into the widx = 0 */request.index_u16= 0x0000;
request.data_u32= 0x12345678;
request.command_enu = FAL_CMD_WRITE_WORD;
FAL_Execute(&request);
while(request.status_enu == FAL_BUSY) FAL_Handler();if(request.status_enu != FAL_OK)
ErrorHandler();/* read value of widx = 0 */request.index_u16= 0x0000;
request.command_enu = FAL_CMD_READ_WORD;
FAL_Execute(&request);
if(request.status_enu != FAL_OK) ErrorHandler();/* check whether the written pattern is correct */if(request.data_u32 != 0x12345678) ErrorHandler();/* blank check widx = 0 */request.index_u16= 0x0000;
request.command_enu = FAL_CMD_BLANKCHECK_WORD;
FAL_Execute(&request);
while(request.status_enu == FAL_BUSY) FAL_Handler();if(request.status_enu != FAL_ERR_BLANKCHECK) ErrorHandler();/* verify widx = 0 */request.index_u16= 0x0000;
request.command_enu = FAL_CMD_IVERIFY_WORD;
FAL_Execute(&request);
while(request.status_enu == FAL_BUSY) FAL_Handler();if(request.status_enu != FAL_OK) ErrorHandler();
FAL_Close();R01US0034ED0110

User Manual46Data Flash Access Library

5.8

Example: Read/Write during background erase
The FDL allows background erase operation, therefore during that time readand write-access to data located in another block of the addressed pool ispossible. To be able to use foreground read/write operation a separate request
variable has to be declared for that purpose. Read and write commands doalways suspend the erase process running in the background. Exception iswhen the word command tries to access the same block as the running erase
in background. In such a case the FAL_Handler() has to be called until therunning erase command is finished. Please refer to the detailed explanation ofcommand suspension to chapter “Suspension of block oriented commands(erase)”.

fal_request_t
fal_u32

my_BCMD_req, my_WCMD_req;
my_data_u32;

void erase_state_0(void){/* specify the BCMD parameter */my_BCMD_req.index_u16= 4;
my_BCMD_req.command_enu = FAL_CMD_ERASE_BLOCK;FAL_Execute(&my_BCMD_req);/* if erase-request accepted goto next state 1 *//* if erase-request rejected remain in state 0 *//* if erase-request error occurs goto error-state */if(my_BCMD_req.status_enu == FAL_BUSY;)
next_state = erase_state_1;
else{
if (my_BCMD_req.status_enu != FAL_ERR_REJECTED)
next_state = erase_state_err;}}/* block erase is running in background here */void erase_state_1(void){/* if read during erase needed, read immediately */if(emergency_read==TRUE){
do {my_WCMD_req.index_u16= 234;
my_WCMD_req.command_enu = FAL_CMD_READ_WORD;
FAL_Execute(&my_WCMD_req);
FAL_Handler();/* enforce eventually blocking command */} while((my_WCMD_req.status_enu==FAL_ERR_REJECTED));/* read-request accepted -> read the data directly */if (my_WCMD_req.status_enu==FAL_OK)
my_data_u32 = my_WCMD_req.data_u32;
else{/* in case of error, goto error-state */next_state = erase_state_err;}} /* ########### NEXT PAGE -----> ############### */R01US0034ED0110

User Manual47

Data Flash Access Library/* if write during erase needed, read immediately */if(emergency_write==TRUE){do {my_data_u32 = 0x12345678;
my_WCMD_req.data_u32 = my_data_u32;
my_WCMD_req.index_u16= 234;
my_WCMD_req.command_enu = FAL_CMD_WRITE_WORD;
FAL_Execute(&my_WCMD_req);
FAL_Handler();/* enforce eventually blocking command */} while((my_WCMD_req.status_enu==FAL_ERR_REJECTED));/* enforce execution of the write-request */do {FAL_Handler();} while((my_WCMD_req.status_enu==FAL_BUSY));/* if error during write -> goto error-state */if (my_WCMD_req.status_enu!=FAL_OK)
next_state = erase_state_err;}/* proceed the BCMD execution */FAL_Handler();/* erase-request finished -> goto state 2 */if(my_BCMD_req.status_enu==FAL_OK))
next_state = erase_state_2;
else{/* in case of error, goto error-state */next_state = erase_state_err;}}

R01US0034ED0110

User Manual48

Data Flash Access Library

Chapter 6 Characteristics
6.1

Resource consumption

Table 6-1 Resource consumption
IAR V1.xx
Compiler

IAR V2.xx
Compiler

CA78K0R
CompilerMax. code size(code flash)

1510 byte

1500 byte

1480 byte

Constants (code flash)

64 byte64 byte64 byteInternal data
(SADDR RAM)

2 byte2 byte2 byteMax. stack (RAM)60 byte60 byte60 byteAll values are based on FDL version V1.12

6.2

Timings
In the following, certain timing characteristics of the FDL are specified. All
timing specifications are based on the following library version:
FDL T01 version V1.12.
Please note that there might be deviations from the specified timings in case
you are using other library versions than the ones mentioned.

6.2.1

Maximum Function Execution Times
The maximum function execution times are listed in the following tables. Thesetimings can be seen as worst case durations of the specific Tiny FDL function
calls and therefore can aid the developer for time critical considerations, e.g.
when setting up the watchdog timer. Please note however, that the typical andminimum function execution times can be much shorter.

Table 6-2 Maximum function execution times (full speed mode)
Function
FAL_Init(no command running)

Maximum function execution time
1758/fclk

FAL_Init **1(command running in background)2092/fclk + 60µs

FAL_Open

83/fclk + 12µs

FAL_Close(no command running)

42/fclk

FAL_Close **1(command running in background)388/fclk + 60µs

FAL_Execute1259/fclk + 28µs

FAL_Handler

974/fclk + 15µs

FAL_GetVersionString

14/fclk

Note **1
It is not recommended to call FAL_Init or FAL_Close in case of any command
running in background.
R01US0034ED0110

User Manual49Data Flash Access Library

Table 6-3 Maximum function execution times (wide voltage mode)
Function

Maximum function execution time

FAL_Init(no command running)

1758/fclk

FAL_Init **1(command running in background)2086/fclk + 114µs

FAL_Open

83/fclk + 12µs

FAL_Close(no command running)

42/fclk

FAL_Close **1(command running in background)382/fclk + 114µs

FAL_Execute1259/fclk + 40µs

FAL_Handler

974/fclk + 15µs

FAL_GetVersionString

14/fclk

Note **1
It is not recommended to call FAL_Init or FAL_Close in case of any command
running in background.

6.2.2

Command execution times
The command execution times are listed in the following tables. These timings
are divided into the typical timings, which will appear during the normal
operation, and the maximum timings for worst case considerations.

Table 6-4 Command execution times (full speed mode)
Command

Typical execution time

Maximum execution time

11597/fclk + 5800µs

282428/fclk + 264819µs

blank check1257/fclk + 32µs

1952/fclk + 66µs

internal verify

1051/fclk + 39µs

1704/fclk + 75µs

write

3381/fclk + 240µs

6340/fclk + 1847µs

read

347/fclk

606/fclk + 23µs

erase

Table 6-5 Command execution times (wide voltage mode)
Command

Typical execution time

Maximum execution time

10272/fclk + 7195µs

249108/fclk + 299308µs

blank check1250/fclk + 67µs

1943/fclk + 120µs

internal verify

1015/fclk + 145µs

1661/fclk + 214µs

write

3325/fclk + 554µs

6108/fclk + 4125µs

read347/fclk

606/fclk + 33µs

erase

R01US0034ED0110

User Manual50Data Flash Access Library

Chapter 7 Cautions
Following cautions must be considered before developing of an application.
•

Library code and constants must be located completely in the same 64k
flash page.

•

Initialization by FAL_Init must be performed before execution of
FAL_Open/FAL_Close/FAL_Handler/FAL_Execute functions.

•

Do not read data flash directly (means without FAL) during commandexecution of FAL•

Each request variable must be located from an even address•

Before executing any command, all members of the request variable must
be initialized. If there are any unused members in the request variable,please set arbitrary values to these members.

•

All functions are not re-entrant. That means don’t call FAL functions inside
the ISRs while any FAL function is already running.

•

Task switches, context changes and synchronization between FDL
functions
All FDL functions depend on FDL global available information and areable to modify this. In order to avoid synchronization problems, it isnecessary that at any time only one FDL function is executed. So, it is notallowed to start an FDL function, then switch to another task context andexecute another FDL function while the last one has not finished.
Example of not allowed sequence:- Task 1: Start an FDL operation with FDL_Execute- Interrupt the function execution and switch to task 2, executing
FDL_Handler function.
- Return to task 1 and finish FDL_Execute function

R01US0034ED0110

User Manual•

After execution of FAL_Close or FAL_Init function all requested/runningcommands will be aborted and cannot be resumed. Please take care that
all running commands are finished before calling this functions.

•

It is not possible to modify the Data Flash parallel to modification of theCode Flash•Suspension of word commands like read, write, verify, and blank-check is
not possible•

Internal high-speed oscillator must be started before using of the FDL.

•

It is not allowed to locate any arguments and stack memory to address of
0xFFE20 and above.

•

In case the application requires a frequency of less than 4MHz, thefollowing frequencies are allowed: 1MHz, 2MHz, 3MHz. It is not allowed
to use a frequency of e.g. 1.5MHz.

•

In case the Data Transfer Controller(DTC) is used in parallel to the FDL,
do not locate RAM area for DTC to address 0xFFE20 and above•

Please check the restrictions of your target device described in the device
user’s manual in case of accessing the data flash via the FDL.

51

Data Flash Access Library•

Additional cautions on using the FDL for IAR V2.xx.
•

Library code and constants must be located completely in the same
32KB memory range.

•

Each segment (FAL_DATA, FAL_CNST) must be located from aneven address.

•

Do not align the members of any structure (by padding betweenthem) that is to be used in the argument of an FDL library function.
Refer to the fdl_types.h file for more information about the size ofeach structure.

•

If you wish to use a linker configuration file included of the IAR V2.2x
compiler (instead of a sample linker configuration file in the flash
library package), specify flash libraries sections with special names
for Renesas objects (R_TEXTF_UNIT64KP, R_SBSS) in the linker
configuration file.
e.g.)
ro section FAL_CODE -> ro code R_TEXTF_UNIT64KP section FAL_CODE
rw section FAL_DATA -> rw data R_SBSS section FAL_DATA
Note: Section FAL_CNST does not require special names for Renesas
objects since this section is defined in the sample source file
(fdl_descriptor.c). Simply declare this flash library section in a linker
configuration file as if it is normal section.
e.g.)
ro section FAL_CNST

R01US0034ED0110

User Manual52Data Flash Access Library

Revision History

Chapter

Page

All

Description
Initial document

3.2.5

21-22

3.3.2.2
6.2
7

25
45-46
47

Rev. 1.01:
Adding description of fal_descriptor_t element
wide_voltage_mode_u08
Extending description of FAL_Open Update of execution
times for functions and commands
List of cautions extended
Rev. 1.10:

All

All

“Renesas Version” and “Renesas Compiler” unified to“CA78K0R Compiler”

All

All

Adding description of IAR V2.xx compiler API

5.3.2

39

Adding file structure for IAR V2.xx compiler

6.1

49

Resource consumption updated and added informationof the IAR V2.xx compiler

6.2.2

50

Corrected the Table 6-5

751

List of cautions extended

R01US0034ED0110

User Manual53

Data Flash Access Library

Data Flash Access Library

R01US0034ED0110

User Manual54