User Manual

16

Data Flash Access Library
Type T02 (Tiny), European Release

16 Bit Single-chip Microcontroller
RL78 Family
Installer:
RENESAS_RL78_EEL-FDL_T02_PACK02_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

R01US0061ED0140
22.04.2024

Notice1.

Descriptions of circuits, software and other related information in this document are provided only to illustrate the operation of semiconductor 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 yourproduct or system. Renesas Electronics disclaims any and all liability for any losses and damages 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, orother intellectual property rights of third parties, by or arising from the use of Renesas Electronics products or technical information described in thisdocument, including but not limited to, the product data, drawings, charts, programs, algorithms, and application examples.
3. No license, express, implied or otherwise, is granted hereby under any patents, copyrights or other intellectual property rights of Renesas Electronics orothers.
4. You shall be responsible for determining what licenses are required from any third parties, and obtaining such licenses for the lawful import, export,
manufacture, sales, utilization, distribution or other disposal of any products incorporating Renesas Electronics products, if required.
5. 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.
6. Renesas Electronics products are classified according to the following two quality grades: “Standard” and “High Quality”. The intended applications foreach 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; homeelectronic appliances; machine tools; personal electronic equipment; industrial robots; etc.
"High Quality": Transportation equipment (automobiles, trains, ships, etc.); traffic control (traffic lights); large-scale communication equipment; 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 other Renesas
Electronics document, Renesas Electronics products are not intended or authorized for use in products or systems that may pose a direct threat tohuman 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; military equipment; etc.). Renesas Electronics disclaims
any and all liability for any damages or losses incurred by you or any third parties arising from the use of any Renesas Electronics product that isinconsistent with any Renesas Electronics data sheet, user’s manual or other Renesas Electronics document.
7. No semiconductor product is absolutely secure. Notwithstanding any security measures or features that may be implemented in Renesas Electronics
hardware or software products, Renesas Electronics shall have absolutely no liability arising out of any vulnerability or security breach, including but notlimited to any unauthorized access to or use of a Renesas Electronics product or a system that uses a Renesas Electronics product. RENESASELECTRONICS DOES NOT WARRANT OR GUARANTEE THAT RENESAS ELECTRONICS PRODUCTS, OR ANY SYSTEMS CREATED USINGRENESAS ELECTRONICS PRODUCTS WILL BE INVULNERABLE OR FREE FROM CORRUPTION, ATTACK, VIRUSES, INTERFERENCE,
HACKING, DATA LOSS OR THEFT, OR OTHER SECURITY INTRUSION (“Vulnerability Issues”). RENESAS ELECTRONICS DISCLAIMS ANY AND
ALL RESPONSIBILITY OR LIABILITY ARISING FROM OR RELATED TO ANY VULNERABILITY ISSUES. FURTHERMORE, TO THE EXTENTPERMITTED BY APPLICABLE LAW, RENESAS ELECTRONICS DISCLAIMS ANY AND ALL WARRANTIES, EXPRESS OR IMPLIED, WITHRESPECT TO THIS DOCUMENT AND ANY RELATED OR ACCOMPANYING SOFTWARE OR HARDWARE, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES OF MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
8. 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 the ranges specified byRenesas 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 suchspecified ranges.
9. Although Renesas Electronics endeavors to improve the quality and reliability of Renesas Electronics products, semiconductor products have specificcharacteristics, such as the occurrence of failure at a certain rate and malfunctions under certain use conditions. Unless designated 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 event of 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 areresponsible for evaluating the safety of the final products or systems manufactured by you.
10. 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 ofcontrolled substances, including without limitation, the EU RoHS Directive, and using Renesas Electronics products in compliance with all theseapplicable laws and regulations. Renesas Electronics disclaims any and all liability for damages or losses occurring as a result of your noncompliancewith applicable laws and regulations.
11. Renesas Electronics products and technologies shall not be used for or incorporated into any products or systems whose manufacture, use, or sale isprohibited 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 or transactions.
12. It is the responsibility of the buyer or distributor of Renesas Electronics products, or any other party who distributes, disposes of, or otherwise sells ortransfers the product to a third party, to notify such third party in advance of the contents and conditions set forth in this document.
13. This document shall not be reprinted, reproduced or duplicated in any form, in whole or in part, without prior written consent of Renesas Electronics.
14. Please contact a Renesas Electronics sales office if you have any questions regarding the information contained in this document or Renesas
Electronics products.
(Note1)(Note2)“Renesas Electronics” as used in this document means Renesas Electronics Corporation and also includes its directly or indirectly controlledsubsidiaries.
“Renesas Electronics product(s)” means any product developed or manufactured by or for Renesas Electronics.
(Rev.5.0-1 October 2020)

Corporate Headquarters

Contact information

TOYOSU FORESIA, 3-2-24 Toyosu,
Koto-ku, Tokyo 135-0061, JapanFor further information on a product, technology, the most up-to-dateversion of a document, or your nearest sales office, please visit:www.renesas.com/contact/.

www.renesas.com

Trademarks
Renesas and the Renesas logo are trademarks of Renesas
Electronics Corporation. All trademarks and registered trademarks
are the property of their respective owners.

© 2024 Renesas Electronics Corporation. All rights reserved.

Data Flash Access Library - Type T02 (Tiny), European Release

Regional information

Regional information
Some information contained in this document may vary from country to country. Before using any Renesas
Electronics product in your application, please contact the Renesas Electronics office in your country to obtain alist of authorized representatives and distributors. They will verify:•

Device availability•

Ordering information•

Product release schedule•

Availability of related technical literature•

Development environment specifications (for example, specifications for third-party tools andcomponents, host computers, power plugs, AC supply voltages, and so forth)•

Network requirements

In addition, trademarks, registered trademarks, export restrictions, and other legal issues may also vary fromcountry to country.
Visit
http://www.renesas.com
to get in contact with your regional representatives and distributors.

R01US0061ED0140
User Manual3

Data Flash Access Library - Type T02 (Tiny), European Release

Preface

Preface
Readers This manual is intended for users who want to understand the functions of the concerned
libraries.
Purpose This manual presents the software manual for the concerned libraries.
Numeric Binary:
notation
Decimal:Hexadecimalxxxx or xxxB
xxxx
xxxxH or 0x xxxx

Numeric Representing powers of 2 (address space, memory capacity):
prefixK (kilo)
210 = 1024
M (mega):

220 = 10242 = 1,048,576

G (giga):

230 = 10243 = 1,073,741,824

Register X, x = don’t care
Diagrams Block diagrams do not necessarily show the exact software flow but the functional structure.
Timing diagrams are for functional explanation purposes only, without any relevance to the real
hardware implementation.

R01US0061ED0140
User Manual4Data Flash Access Library - Type T02 (Tiny), European Release

How to Use This Document

How to Use This Document(1) Purpose and Target ReadersThis manual is designed to provide the user with an understanding of the hardware functions and electricalcharacteristics of the MCU. It is intended for users designing application systems incorporating the MCU. A
basic knowledge of electric circuits, logical circuits, and MCUs is necessary in order to use this manual. The
manual comprises an overview of the product; descriptions of the CPU, system control functions, peripheral
functions, and electrical characteristics; and usage notes.
Particular attention should be paid to the precautionary notes when using the manual. These notes occur within
the body of the text, at the end of each section, and in the Usage Notes section.
The revision history summarizes the locations of revisions and additions. It does not list all revisions. Refer tothe text of the manual for details.
(2) Related documents
Document number

Description
EEPROM Emulation Library Type T02 (Tiny), European
ReleaseR01US0070EDxxxx(3) List of Abbreviations and Acronyms
Abbreviation

Full form

Block

Smallest erasable unit of a flash macro

Code Flash

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.

Data Flash

Embedded Flash where mainly the data of the
EEPROM emulation are stored. Beside that also code
operation might be possible.

Dual Operation

Dual operation is the capability to fetch code during
reprogramming of the flash memory. Current limitationis that dual operation is only available between different
flash macros. Within the same flash macro it is notpossible!

EEL

EEPROM Emulation Library

EEPROM emulation

In distinction to a real EEPROM the EEPROM
emulation uses some portion of the flash memory toemulate the EEPROM behavior. To gain a similar
behavior some side parameters have to be taken inaccount.

FDL

Data Flash Library (Data Flash access layer)

Flash“Flash EPROM” - Electrically erasable andprogrammable nonvolatile memory. The difference to
ROM is, that this type of memory can be reprogrammed several times.

Flash Block

A flash block is the smallest erasable unit of the flash
memory.

R01US0061ED0140
User Manual5Data Flash Access Library - Type T02 (Tiny), European Release

Abbreviation

How to Use This Document

Full form

Flash Macro

A flash comprises of the cell array, the sense amplifier
and the charge pump (CP). For address decoding andaccess some additional logic is needed.

NVM

Non volatile memory. All memories that hold the value,even when the power is cut off. E.g. Flash memory,
EEPROM, MRAM...

RAM“Random access memory” - volatile memory withrandom access

ROM“Read only memory” - nonvolatile memory. The content
of that memory can not be changed.

Serial programming

The onboard programming mode is used to program
the device with an external programmer tool.

Single Voltage

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.

All trademarks and registered trademarks are the property of their respective owners.

R01US0061ED0140
User Manual

6Data Flash Access Library - Type T02 (Tiny), European Release

Table of Contents

Table of Contents
Chapter 1

Introduction........................................................................... 9

1.1 Components of the EEPROM Emulation System ........................................ 10
1.1.1 Physical Flash Layer ............................................................................. 10
1.1.2 Flash Access Layer ............................................................................... 10
1.1.3 EEPROM Access Layer ......................................................................... 10
1.1.4 Application Layer ................................................................................... 10

Chapter 2

Architecture ........................................................................ 11

2.1 Data Flash Fragmentation ............................................................................. 11
2.1.1 EEL Pool ................................................................................................. 11
2.1.2 FDL Pool ................................................................................................. 11
2.2 Address Virtualization ................................................................................... 11
2.3 Access Right Supervision ............................................................................. 12
2.4 Request-Response Architecture................................................................... 14
2.5 Background Operation .................................................................................. 15
2.5.1 Background Operation: Erase .............................................................. 15
2.5.2 Background Operation: Internal Verify and Blankcheck .................... 16
2.5.3 Background Operation: Write ............................................................... 17
2.6 Abortion of Commands ................................................................................. 18
2.7 StandBy and WakeUp Functionality ............................................................. 20

Chapter 3User Interface (API) ............................................................ 21

3.1 Run-time Configuration ................................................................................. 21
3.2 Data Types ...................................................................................................... 22
3.2.1 Library-specific simple Type Definitions ............................................. 22
3.2.2 Enumeration Type “fdl_command_t”................................................... 22
3.2.3 Enumeration Type “fdl_status_t” ......................................................... 23
3.2.4 Structured Type “fdl_request_t” .......................................................... 24
3.2.5 Structured Type “fdl_descriptor_t” ...................................................... 25
3.3 Functions ........................................................................................................ 27
3.3.1 FDL_Init .................................................................................................. 27
3.3.2 FDL_Open............................................................................................... 30
3.3.3 FDL_Close .............................................................................................. 32
3.3.4 FDL_Execute .......................................................................................... 34
3.3.5 FDL_Handler .......................................................................................... 37
3.3.6 FDL_Abort .............................................................................................. 39
3.3.7 FDL_StandBy ......................................................................................... 42
R01US0061ED0140
User Manual7

Data Flash Access Library - Type T02 (Tiny), European Release

Table of Contents

3.3.8 FDL_WakeUp .......................................................................................... 45
3.3.9 FDL_GetVersionString .......................................................................... 47
3.4 Commands ..................................................................................................... 50
3.4.1 Blankcheck ............................................................................................. 50
3.4.2 Internal Verify ......................................................................................... 51
3.4.3 Read ........................................................................................................ 52
3.4.4 Write ........................................................................................................ 53
3.4.5 Erase ....................................................................................................... 54
3.5 Basic functional Workflow ............................................................................ 55

Chapter 4

FDL Usage by User Application ........................................ 56

4.1 First Steps ...................................................................................................... 56
4.2 Special Considerations ................................................................................. 56
4.2.1 Reset Consistency ................................................................................. 56
4.2.2 EEL+FDL or FDL only ............................................................................ 56
4.3 File Structure .................................................................................................. 57
4.4 Configuration ................................................................................................. 59
4.4.1 Linker Sections ...................................................................................... 59
4.4.2 Descriptor Configuration (Partitioning of the Data Flash) ................. 59
4.4.3 Prohibited RAM Area ............................................................................. 60
4.4.4 Register Bank......................................................................................... 60
4.4.5 Stack and Data Buffer............................................................................ 60
4.4.6 Request Structure .................................................................................. 60
4.5 General Flow .................................................................................................. 61
4.5.1 Initialization ............................................................................................ 61
4.5.2 Read ........................................................................................................ 62
4.5.3 Blankcheck/Write/Internal Verify/Erase ............................................... 63
4.6 Example of FDL used in Operating Systems ............................................... 64
4.7 Example: Simple application......................................................................... 65

Chapter 5

Characteristics.................................................................... 66

5.1 Resource Consumption................................................................................. 66
5.2 Library Timings .............................................................................................. 66
5.2.1 Maximum Function Execution Times ................................................... 66
5.2.2 Command Execution Times .................................................................. 68

Chapter 6

Cautions .............................................................................. 69

R01US0061ED0140
User Manual8Data Flash Access Library - Type T02 (Tiny), European Release

Chapter 1

Introduction

Introduction

This user’s manual describes the overall structure, functionality and software interfaces (API) of the Data
Flash Library T02 (Tiny) accessing the physical Data Flash separated and independent from the CodeFlash. 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 T02 provides APIs for the C and assembly language of the CA78K0R, IAR V1.xx,
IAR V2.xx, GNU, CC-RL and LLVM tool chains. (APIs for the assembly language are provided by the
CA78K0R and CC-RL tool chains only.)
The Data Flash Library T02 for IAR V2.xx tool chain (except linker sample file) can also be used with the
IAR V3.xx or later version tool chains.
The flash access layer is a layer of the EEPROM emulation system and encapsulates the low-level
access to the physical flash a secure way. In case of Data Flash, this layer is using the FDL. It provides afunctional socket for Renesas EEPROM emulation software.

user application

application layer

EEL API

hardwaresoftware

EEPROM emulation library(EEL)

EEPROM layer

FDL API

Data Flash library(FDL)

flash access layer

Data Flashphysical flash layer

Figure 1-1: Components of the EEPROM emulation system
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 accesscommands some maintenance functionality to check the quality of the flash content is also provided by
the library.

R01US0061ED0140
User Manual9Data Flash Access Library - Type T02 (Tiny), European Release

Introduction

1.1 Components of the EEPROM Emulation System
To achieve a high degree of encapsulation the EEPROM emulation system is divided into several layerswith 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 that can be accessed independent of the Code Flashmemory. This allows background access to data stored in the Data Flash during program execution
located in the code flash.

1.1.2 Flash Access Layer
The flash access layer is represented by the flash access library provided by Renesas. In case of devices
incorporating data-flash the Data Flash Library (FDL) is representing this layer. It offers all atomic
functionality to access the Data Flash. To isolate the data-flash access from the used flash-media thislayer (the FDL) is transforming the 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 on an abstract level. It is represented bya Renesas EEPROM Emulation Library (EEL) or alternatively any other, user specific implementation.

1.1.4 Application Layer
The application layer represents user’s application software that can freely access all visible (specified by
the API definition) commands. The EEPROM layer and the flash access layer can be usedsimultaneously. The FDL manages the access rights to it in a proper way.

R01US0061ED0140
User Manual10Data Flash Access Library - Type T02 (Tiny), European Release

Chapter 2

Architecture

ArchitectureThis chapter describes the overall architecture of the Tiny FDL.

2.1 Data Flash Fragmentation
The physical address range of the Data Flash depends on the utilized hardware (e.g. for RL78/G13:
0xF1000 – 0xF1FFF). However, the logical fragmentation of the Data Flash can be configured within thegiven range.
Following figure shows the logical fragmentation of RL78/G13 physical Data Flash.

0xF1FFF

Data FlashFDL pool

Access byapplication only

EEL pool
Access by
EEL only

0xF1000

Figure 2-1: Logical fragmentation of physical Data Flash2.1.1 EEL Pool
The EEL pool is exclusively used by the Renesas EEPROM Emulation Library (EEL). In case the EEL is
not used the whole Data Flash can be reserved as FDL pool.

2.1.2 FDL Pool
The FDL pool is exclusively used by the application. In case of a proprietary EEPROM emulation
implementation (user specific), the complete FDL pool has to be configured as FDL-pool.

2.2 Address Virtualization
To facilitate the access to the FDL pool, the physical addresses were virtualized. The virtualized poollooks like a simple one-dimensional array.

R01US0061ED0140
User Manual11Data Flash Access Library - Type T02 (Tiny), European Release

Architecture

FDL/EEL
Pool

Data Flash

0x0FFF

0xF2FFF

Block 7Block 30xF2C00

0x0C00

0xF2BFF

0x0BFF

Block 6Block 2

0xF2800

0x0800

0xF27FF

0x07FF

Block 50xF2400
0xF23FF

Block 4
0xF2000

FDL pool

Block 1
Flash blockand addresstransformation

0x04000x03FF

Block 00x00000xF1FFF

Block 30xF1C00
0xF1BFF

Block 2
0xF1800

EEL pool

0xF17FF

Block 1
0xF1400
0xF13FF

Block 0
0xF1000

Physicaladdress

virtualbyte
index

Figure 2-2: Relationship between physical and virtual pool addresses

2.3 Access Right Supervision
As mentioned before, the complete Data Flash is divided into two parts which are accessible by poolowner (FDL does not allow user access to the EEL-pool and vice versa).

R01US0061ED0140
User Manual12Data Flash Access Library - Type T02 (Tiny), European Release

Architecture

USER

N-1
FDL pool

FDL pool access

0(N

-1
)

N flash bytes
0x0000FDL
EEL pool
EEL pool access

EEL
Figure 2-3: FDL pool access supervision

R01US0061ED0140
User Manual13Data Flash Access Library - Type T02 (Tiny), European Release

Architecture

2.4 Request-Response Architecture
The communication between the requester (user) and the executor (here the FDL) is a structured request
variable. The requester can specify the request and pass it to the FDL. After acceptance, the progress ofthe 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:••

commands that can be aborted: block oriented commands like erase taking relatively long time forits executioncommands that cannot be aborted: byte-oriented commands like write, read ... taking very shorttime for its execution

Depending on the real-time requirements, the user can decide if independent, quasi-parallel execution ofblock and byte 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 “Basic functional Workflow” for details.
Following figure shows the access from requester and FDL point of view.

Requester

INDEX
DATA POINTERBYTE COUNTCOMMANDSTATUS

FDL

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

R01US0061ED0140
User Manual14

Data Flash Access Library - Type T02 (Tiny), European Release

Architecture

2.5 Background Operation
The flash technology provided by Renesas enables the application to write/erase the Data Flash inparallel to the CPU execution. Such a feature is a powerful especially in operation systems were eachtask could start FDL commands which will be executed in the background during task switching.

2.5.1 Background Operation: Erase
The erase command is the longest command. Once started, the erase command is executed in the
background leaving the user the option to execute other application tasks in the meantime. By calling the
FDL_Handler, the current progress of the command can be checked via the status of the used request
structure. As shown in the figure below, the application has the possibility to execute other user code
during the background operation.

USER

FDL

Data Flash
hardware(background)

FDL_Execute(req.command_enu =FDL_CMD_ERASE_BLOCK)

req.status_enu =FDL_BUSY
FDL_Handler()req.status_enu =FDL_BUSY
FDL_Handler()Erase
req.status_enu =FDL_BUSY

FDL_Handler()req.status_enu =FDL_BUSY
FDL_Handler()req.status_enu =FDL_OK

Figure 2-5: Background operation (Erase)

R01US0061ED0140
User Manual15

Data Flash Access Library - Type T02 (Tiny), European Release

Architecture

2.5.2 Background Operation: Internal Verify and Blankcheck
Just like the erase command, also the internal verify and the blankcheck are performed in the background,
once they have been triggered.

USER

FDL

Data Flash
hardware(background)

FDL_Execute(req.command_enu =FDL_CMD_IVERIFY_BYTES or
FDL_CMD_BLANKCHECK_BYTES)
req.status_enu =FDL_BUSY

BlankCheck(x bytes)
OR
Internal Verify (x bytes)

FDL_Handler()req.status_enu =FDL_BUSY
FDL_Handler()req.status_enu =FDL_OK

Figure 2-6: Background operation (Internal Verify/Blankcheck)

R01US0061ED0140
User Manual16

Data Flash Access Library - Type T02 (Tiny), European Release

Architecture

2.5.3 Background Operation: Write
Compared to the erase/internal verify/blankcheck command the write commands, is running only partiallyin the background. Each byte is written in the background whereas the administrative part of selecting thenext byte is done by the FDL_Handler(). Therefore, it is mandatory to call the FDL_Handler not only forchecking the current progress, but also to drive the command forward.

USER

FDL

Data Flash
hardware(background)

FDL_Execute(req.command_enu =FDL_CMD_WRITE_BYTES)
req.status_enu =FDL_BUSY

Write
Byte (1)

FDL_Handler()req.status_enu =FDL_BUSY

Write
Byte (2)

FDL_Handler()req.status_enu =FDL_BUSY

FDL_Handler()

Write
Byte (3)

::::
::::

req.status_enu =FDL_BUSY

::::
::::
Write
Byte (x)FDL_Handler()req.status_enu =FDL_OK

Figure 2-7: Background operation (Write)

R01US0061ED0140
User Manual17Data Flash Access Library - Type T02 (Tiny), European Release

Architecture

2.6 Abortion of Commands
Some application scenarios require an immediate abort of running data flash operations e.g. in cases ofvoltage drop or emergency data write to the data flash. For that reason the FDL provides an abortmechanism where a running erase command can be aborted immediately. The following figure showssuch a scenario.

USER

FDL

Data Flash
hardware(background)

FDL_Execute(req.command_enu =FDL_CMD_ERASE_BLOCK)

Erase
req.status_enu =FDL_BUSY
FDL_Abort()::::
req.status_enu =FDL_ERR_ABORTED
FDL_Abort() returns
FDL_OK

Figure 2-8: Abort erase commandAs shown in the figure above, the erase command will be immediately aborted in case of calling the
FDL_Abort function and the requester of the erase command will be informed that the requested
command was aborted. In such a case, the command shall be re-started by requester later. In contrast,
the blankcheck/write/internal verify commands cannot be aborted immediately and therefore have to befinished by repeated calls of the FDL_Abort function. The following figure shows the abort functions incase of blankcheck/write/internal verify commands.

R01US0061ED0140
User Manual18Data Flash Access Library - Type T02 (Tiny), European Release

USER

FDL

Architecture

Data Flash
hardware(background)

FDL_Execute(req.command_enu =FDL_CMD_BLANKCHECK_BYTES**)

req.status_enu =FDL_BUSY

FDL_Abort()

::::
::::

FDL_Abort()
returns FDL_BUSY

BlankCheck
or
Write
or
Internal Verify

FDL_Abort()

FDL_Abort()
returns FDL_BUSY
FDL_Abort()

FDL_Abort()
returns FDL_OK** same procedure for FDL_CMD_WRITE_BYTES and FDL_CMD_IVERIFY_BYTES

Figure 2-9: Abort Blankcheck/Write/Internal Verify command

R01US0061ED0140
User Manual19Data Flash Access Library - Type T02 (Tiny), European Release

Architecture

2.7 StandBy and WakeUp Functionality
The StandBy and WakeUp feature provides the possibility to temporarily turn off the data flash
functionality including the hardware (e.g. for power consumption) and resume the functionality. The
StandBy mode is active in case the FDL_StandBy function returns FDL_OK. In case the return status is
FDL_BUSY any command is running and FDL_StandBy function has to be re-called. The following figure
shows the sequence of using the StandBy/WakeUp feature.

USER

FDL

Data Flash
hardware(background)

FDL_Execute(req.command_enu =FDL_CMD_BLANKCHECK_BYTES**)

req.status_enu =FDL_BUSY

FDL_StandBy()

::::
::::

BlankCheck
or
Write
or

FDL_StandBy()
returns FDL_BUSY
FDL_StandBy()

Internal Verify
or
Erase

FDL_StandBy()
returns FDL_OK
FDL_WakeUp()

DFLEN* = 1
FDL_WakeUp()
returns FDL_OK* Data Flash enable SFR** same procedure for FDL_CMD_ERASE_BLOCK, FDL_CMD_WRITE_BYTES and
FDL_CMD_IVERIFY_BYTES

Figure 2-10: StandBy and WakeUp sequence
Note: It is not allowed to call any FDL function other than FDL_WakeUp and FDL_Handler when FDL isin StandBy mode.

R01US0061ED0140
User Manual20Data Flash Access Library - Type T02 (Tiny), European Release

Chapter 3User Interface (API)User Interface (API)

3.1 Run-time Configuration
The configuration of the FDL can be changed dynamically at runtime. Thereby, more than one descriptor
constant has to be defined by the user in advance. Depending on the application different descriptors canbe used for the FDL_Init(...) function.

/*
/*
/*

................... */some code*/................... *//* load standard descriptor */my_status=FDL_Init(&fdl_descriptor_str);
/*
/*
/*

................... */some code*/................... */EEL_Close();FDL_Close();/* load alternative descriptor*/
my_status=FDL_Init(&fdl_descr_2_str);
/*
/*
/*

................... */some code*/................... */Note: Before changing FDL pool configuration by using a different FDL pool-descriptor, the user has tofinish all running FDL and EEL commands and close the FDL via the FDL_Close() function.

R01US0061ED0140
User Manual21Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)

3.2 Data Types
This chapter describes all data definitions used by the Tiny FDL. In order to reduce the probability of typemismatches in the user application, please make strict usage of the provided types and avoid using
standard data types instead.

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

fdl_u08;
fdl_u16;
fdl_u32;

3.2.2 Enumeration Type “fdl_command_t”
The enumeration type fdl_command_t defines all allowed codes used to specify library commands. This
type is used within the structure fdl_request_t (see Section 3.2.4) in order to specify which command shallbe executed via the function FDL_Execute. A detailed description of each command can be found in
Section 3.4.
typedef enum{
FDL_CMD_READ_BYTES
FDL_CMD_IVERIFY_BYTES
FDL_CMD_BLANKCHECK_BYTES
FDL_CMD_WRITE_BYTES
FDL_CMD_ERASE_BLOCK} fdl_command_t;= (0x00),= (0x01),= (0x02),= (0x03),= (0x04)

Note: Due to the fact that the library has been implemented in Assembler, it is mandatory that theenumeration type fdl_command_t has a size of exactly 1 byte. The GNU and LLVM compilers use 16-bit
enumeration types by default. Therefore, for GNU and LLVM compilers, the declaration of theenumeration type has to be extended with an attribute in order to be compiled to 1 byte:“__attribute__ ((__packed__))”.
Table 3-1: Command codes
Command

Description

FDL_CMD_READ_BYTES

reads data from flash memory

FDL_CMD_IVERIFY_BYTES

verifies data if flash provides full data retention

FDL_CMD_BLANKCHECK_BYTES

checks if flash content is erased

FDL_CMD_WRITE_BYTES

writes data into flash memory

FDL_CMD_ERASE_BLOCK

erases one flash block

R01US0061ED0140
User Manual22Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)3.2.3 Enumeration Type “fdl_status_t”
This enumeration type defines all possible status- and error-codes can be generated during data-flash
access via the FDL. The FDL_OK and FDL_BUSY status are returned to the requester during normal
operation. Other codes signalize problems.
On the one hand, fdl_status_t is used as return type of the functions FDL_Init (see Section 3.3.1),
FDL_Abort (see Section 3.3.6), FDL_StandBy (see Section 3.3.7) and FDL_WakeUp (see Section 3.3.8).
On the other hand, fdl_status_t is used within the structure fdl_request_t (see Section 3.2.4) in order tocapture the processing of currently running command. Thereby, the possible error codes are commandspecific and described in detail in Section 3.4 along with the commands.

typedef enum{
FDL_OK
FDL_BUSY
FDL_ERR_INITIALIZATION
FDL_ERR_REJECTED
FDL_ERR_ABORTED
FDL_ERR_PARAMETER
FDL_ERR_STANDBY
FDL_ERR_ERASE
FDL_ERR_BLANK_VERIFY
FDL_ERR_WRITE
FDL_ERR_CONFIGURATION} fdl_status_t;= (0x00),= (0xFF),= (0x02),= (0x03),= (0x04),= (0x05),= (0x06),= (0x1A),= (0x1B),= (0x1C),= (0x01)

Note: Due to the fact that the library has been implemented in Assembler, it is mandatory that theenumeration type fdl_status_t has a size of exactly 1 byte. The GNU and LLVM compilers use 16-bit
enumeration types by default. Therefore, for GNU and LLVM compilers, the declaration of theenumeration type has to be extended with an attribute in order to be compiled to 1 byte:“__attribute__ ((__packed__))”.
Table 3-2: Enumeration type "fdl_status_t" details
Status value

Description

FDL_OK

Command finished without problems

FDL_BUSY

Command is being processed

FDL_ERR_INITIALIZATION

FDL_Init()/FDL_Open() missing

FDL_ERR_REJECTED

Request could not be accepted

FDL_ERR_ABORTED

Erase command has been aborted

FDL_ERR_PARAMETER

Parameter error

FDL_ERR_STANDBY

FDL_WakeUp missing

FDL_ERR_ERASE

Erase error

FDL_ERR_BLANK_VERIFY

Blankcheck or verify error

FDL_ERR_WRITE

Write error

FDL_ERR_CONFIGURATION

Pool or frequency configuration wrong

R01US0061ED0140
User Manual23

Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)3.2.4 Structured Type “fdl_request_t”
This type is used for definition of request variables and used for information exchange between theapplication and the FDL. A request variable is passed to the FDL to initiate a command and can be usedby the requester (EEL, application...) to check the status of its execution. Not every element of thisstructure is required for each command. However, all members of the request variable must be initialized
once before usage. Please refer to Section 3.4 for a more detailed description and the command-specificusage of the structure elements.
/* FDL request type (base type for any FDL access) */typedef struct{
fdl_u16
index_u16;_near fdl_u08*
data_pu08;
fdl_u16bytecount_u16;
fdl_command_t
command_enu;
fdl_status_t
status_enu;} fdl_request_t;

Note: The GNU compiler does not require the “__near” keyword to declare near pointers. All pointers arenear by default as long as the “__far” keyword is not used.
Table 3-3: Structured type "fdl_request_t" details
Struct member

Description
Start address of the target area:index_u16•

Erase: virtual block number inside FDL-pool•

Read/write/blankcheck/internal verify: virtual
byte number inside FDL-pool

data_pu08

Pointer to the first byte of the data buffer to be
written or read. Only used for read/write commands.

bytecount_u16

Number of bytes to be transferred starting from thestart byte specified in index_u16. The byte countrange is from 1 byte to 1024 bytes. Please note, thatthe execution of the read/write/blankcheck/internalverify command across block boundaries is notallowed. This struct member is not required for erasecommand.

command_enu

Command code to be executed

status_enu

Request status code (feedback)

R01US0061ED0140
User Manual24Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)

3.2.5 Structured Type “fdl_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 sample file for definition of the ROM constant fdl_descriptor_str.
Based on configuration data inside the fdl_descriptor.h the initialization data of descriptor constant isgenerated automatically in the fdl_descriptor.c.
/* FDL descriptor type */typedef struct{
fdl_u16
eel_pool_bytes_u16;
fdl_u16
fdl_pool_bytes_u16;
fdl_u16
fdl_delay_u16;
fdl_u08
eel_pool_blocks_u08;
fdl_u08
fdl_pool_blocks_u08;
fdl_u08
fx_MHz_u08;
fdl_u08
wide_voltage_mode_u08;} fdl_descriptor_t;

Table 3-4: Structured type "fdl_descriptor_t" details
Struct member

Description

eel_pool_bytes_u16

EEL-pool size in bytes.
It shall be computed by the compiler pre-processor based on
the following formula:
DATA_FLASH_BLOCK_SIZE* eel_pool_blocks_u08
DATA_FLASH_BLOCK_SIZE is the physical size of a Flashblock specified in the device HW user manual.

fdl_pool_bytes_u16

FDL-pool size in bytes
It shall be computed by the compiler pre-processor based on
the following formula:
DATA_FLASH_BLOCK_SIZE* fdl_pool_blocks_u08
DATA_FLASH_BLOCK_SIZE is the physical size of a Flashblock specified in the device HW user manual.

fdl_delay_u16

Constant delay depending on configured frequency.
It shall be computed by the compiler pre-processor by thefollowing formula:(10 * fx_MHz_u08) / 6

eel_pool_blocks_u08

EEL-pool size in blocks.
It shall be chosen by the user with the condition that
(fdl_pool_blocks_u08 + eel_pool_blocks_u08) may not exceed
the size of the data flash specified in the device HW user
manual.

fdl_pool_blocks_u08

FDL-pool size in blocks.
It shall be chosen by the user with the condition that
(fdl_pool_blocks_u08 + eel_pool_blocks_u08) may not exceed
the size of the data flash specified in the device HW user
manual.

R01US0061ED0140
User Manual25Data Flash Access Library - Type T02 (Tiny), European Release
Struct member

User Interface (API)
Description

CPU frequency

fx_MHz_u08

Frequency must be rounded up as follows:
descr.fx_MHz_u08 =((FDL_SYSTEM_FREQUENCY+999999)/1000000)
FDL_SYSTEM_FREQUENCY specifies the device frequency
and not the HOCO (internal high-speed on-chip oscillator)
frequency.
In case the frequency is smaller than 4MHz the only supported
physically frequencies by FDL are the following:
1MHz=1000000Hz, 2MHz=2000000Hz and 3MHz=3000000Hz
Flash memory programming mode (full/wide).
It shall be chosen by the user:•

wide_voltage_mode_u08

R01US0061ED0140
User Manualwide_voltage_mode_u08 shall be set to 1 for widevoltage mode

wide_voltage_mode_u08 shall be set to 0 for full speedmode.
For details of the flash memory programming mode, refer to theuser’s manual of the target RL78 microcontroller.
•

26

Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)3.3 Functions
3.3.1 FDL_Init
Outline: Initialization of the Flash Data Library.
Interface: C Interface for CA78K0R Compiler
fdl_status_t__far FDL_Init(const __far fdl_descriptor_t*
descriptor_pstr)

C Interface for IAR V1.xx Compiler__far_func fdl_status_t FDL_Init(const __far fdl_descriptor_t __far*
descriptor_pstr)

C Interface for IAR V2.xx Compiler__far_func fdl_status_t FDL_Init(const fdl_descriptor_t __far *descriptor_pstr)

C Interface for GNU Compiler
fdl_status_t

FDL_Init(const fdl_descriptor_t __far* descriptor_pstr)__attribute__ ((section ("FDL_CODE")))C Interface for CC-RL Compiler
fdl_status_t __far FDL_Init(const __far fdl_descriptor_t*
descriptor_pstr)

C Interface for LLVM Compiler
fdl_status_t __far FDL_Init(const __far fdl_descriptor_t*
descriptor_pstr)__attribute__ ((section ("FDL_CODE")))ASM function label
FDL_Init

R01US0061ED0140
User Manual27

Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)Arguments: Parameters
Argument

Accessdescriptor_pstr
Type
fdl_descriptor_t* (far)R
Passed via
CA78K0R

IAR
V1.xx

IAR
V2.xx

GNU

CC-RL

LLVM

BC(highw),
AX(loww)stack

A(high),DE(loww)stack

A(high),DE(loww)A(high),DE(loww)

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

Return valueType
fdl_status_t

Passed via
CA78K0R

IAR
V1.xx

IAR
V2.xx

GNU

CC-RL

LLVM

C

A

A

R8
(X bank 1)

AA

FDL_ERR_CONFIGURATION when descriptor is not plausible.
FDL_OK when descriptor is plausible and initialization was successful.
Destructed registers
Tool chain

Destructed registers

CA78K0R

AX, B

IAR V1.xx

AX, HL, CS, ES

IAR V2.xx

X, BC, DE, HL

GNU

None

CC-RL

X, BC, DE, HL

LLVM

X, BC, DE, HL

Pre- Internal high-speed oscillator is running.
conditions:Post- Initialization is done.
conditions:

R01US0061ED0140
User Manual28Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)

Description: Several checks are performed during the initialization:•

plausibility check of the pool configuration•

frequency parameter check against supported device-specific range•

initialization of all internal variables•

initialization of the flash firmware•

configuration of HOCO

After initialization, the FDL remains passive. FDL_Open() has to be executed to open
access to the FDL pool.
Note: It is not allowed to call FDL_Init in case of any running FDL command.
Example:fdl_status_t my_status;
my_status = FDL_Init(&fdl_descriptor_str);
if(my_status == FDL_OK){/* FDL can be used */}else{/* error handler */}R01US0061ED0140
User Manual29Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)3.3.2 FDL_Open
Outline: Activation of the data-flash.
Interface: C Interface for CA78K0R Compiler
void __far FDL_Open(void)

C Interface for IAR V1.xx Compiler__far_func void FDL_Open(void)

C Interface for IAR V2.xx Compiler__far_func void FDL_Open(void)

C Interface for GNU Compiler
void

FDL_Open(void) __attribute__ ((section ("FDL_CODE")))C Interface for CC-RL Compiler
void __far FDL_Open(void)

C Interface for LLVM Compiler
void __far FDL_Open(void) __attribute__ ((section ("FDL_CODE")))ASM function label
FDL_Open

Arguments: Parameters
none
Return value
none

R01US0061ED0140
User Manual30Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)

Destructed registers
Tool chain

Destructed registers

CA78K0R

None

IAR v1.xx

None

IAR v2.xx

AX

GNU

None

CC-RL

AX

LLVM

AX

Pre- The initialization shall be done before. However, no check is performed here. If the FDL isconditions: not yet initialized, FDL_Open() has no functionality.
Post- Data flash clock is switched on.
conditions:
Description: This function must be used by the application to activate the data-flash.
Example:FDL_Open();

R01US0061ED0140
User Manual31Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)3.3.3 FDL_Close
Outline: Deactivation of the data-flash.
Interface: C Interface for CA78K0R Compiler
void __far FDL_Close(void)

C Interface for IAR V1.xx Compiler__far_func void FDL_Close(void)

C Interface for IAR V2.xx Compiler__far_func void FDL_Close(void)

C Interface for GNU Compiler
void FDL_Close(void) __attribute__ ((section ("FDL_CODE")))C Interface for CC-RL Compiler
void __far FDL_Close(void)

C Interface for LLVM Compiler
void __far FDL_Close(void) __attribute__ ((section ("FDL_CODE")))ASM function label
FDL_Close

Arguments: Parameters
none
Return value
none

R01US0061ED0140
User Manual32

Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)

Destructed registers
Tool chain

Destructed registers

CA78K0R

None

IAR V1.xx

None

IAR V2.xx

C

GNU

None

CC-RL

C

LLVM

C

Pre- The library initialization and open via FDL_Init and FDL_Open shall be done before
conditions: calling this function. If FDL is not yet activated the FDL_Close() has no functionality.
Post- Data flash clock is switched off. All hardware background activities will be stopped
conditions: immediately.
Description: This function must be used by the application to deactivate the data-flash.
Example:FDL_Close();R01US0061ED0140
User Manual33

Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)3.3.4 FDL_Execute
Outline: Initiates the execution of an FDL command.
Interface: C Interface for CA78K0R Compiler
void __far FDL_Execute(__near fdl_request_t* request_pstr)

C Interface for IAR V1.xx Compiler__far_func void FDL_Execute(__near fdl_request_t __near* request_pstr)

C Interface for IAR V2.xx Compiler__far_func void FDL_Execute(fdl_request_t __near * request_pstr)

C Interface for GNU Compiler
void FDL_Execute(fdl_request_t* request_pstr)__attribute__ ((section ("FDL_CODE")))C Interface for CC-RL Compiler
void __far FDL_Execute(__near fdl_request_t* request_pstr)

C Interface for LLVM Compiler
void __far FDL_Execute(__near fdl_request_t* request_pstr)__attribute__ ((section ("FDL_CODE")))ASM function label
FDL_Execute

Arguments: Parameters
Argument

Accessrequest_pstr

RW
Passed via

Type
fdl_request_t* (near)

CA78K0R

IAR
V1.xx

IAR
V2.xx

GNU

CC-RL

LLVM

AX

AX

AX

stack

AX

AX

This argument defines the command which should be executed by FDL. It is a request
variable which is used for bidirectional information exchange before and during execution
between FDL and the application. For details please refer to the “Request-Response
Architecture” chapter.

R01US0061ED0140
User Manual34

Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)Return value
none
Destructed registers
Tool chain

Destructed registers

CA78K0RAX

IAR V1.xx

AX, HL, CS, ES

IAR V2.xx

AX, BC, DE, HL

GNU

None

CC-RL

AX, BC, DE, HL

LLVM

AX, BC, DE, HL

Pre- The library initialization and open via FDL_Init and FDL_Open shall be done before
conditions: calling this function.
Post- Noneconditions:
Description: This is the main function of the FDL which can be used inside of the application to initiate
the execution of any command. Please refer to the chapter “Commands” for detailed
explanation of each command.
Note 1: Although there are commands that do not require all request structure elements
to be specified, the whole structure needs to be initialized before calling EEL_Execute.
Otherwise, a RAM parity error may cause a reset of the device. For details, please referto the document “User's Manual: Hardware” of your RL78 product.
Note 2: The request structure used for execution has to be word-aligned, i.e. located at
an even memory address.

R01US0061ED0140
User Manual35Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)

Example:__near fdl_request_t my_fdl_request_str;__near fdl_u08 buffer[4];buffer[0] = {0x01, 0x23, 0x45, 0x67};
my_fdl_request.index_u16 = 0x0000;
my_fdl_request.data_pu08 = (__near fdl_u08*)buffer;
my_fdl_request.bytecount_u16 = 0x0004;
my_fdl_request.command_enu = FDL_CMD_WRITE_BYTES;/* command initiation */do{
FDL_Execute(&my_fdl_request);
FDL_Handler(); /* proceed background process */}while (my_fdl_request.status_enu == FDL_ERR_REJECTED);/* command execution */do{
FDL_Handler();}while (my_fdl_request.status_enu == FDL_BUSY);
if(my_fdl_request.status_enu != FDL_OK){
error_handler();}

R01US0061ED0140
User Manual36Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)3.3.5 FDL_Handler
Outline: Function for command proceeding.
Interface: C Interface for CA78K0R Compiler
void __far FDL_Handler(void)

C Interface for IAR V1.xx Compiler__far_func void FDL_Handler(void)

C Interface for IAR V2.xx Compiler__far_func void FDL_Handler(void)

C Interface for GNU Compiler
void FDL_Handler(void) __attribute__ ((section ("FDL_CODE")))C Interface for CC-RL Compiler
void __far FDL_Handler(void)

C Interface for LLVM Compiler
void __far FDL_Handler(void) __attribute__ ((section ("FDL_CODE")))ASM function label
FDL_Handler

Arguments: Parameters
none
Return value
none

R01US0061ED0140
User Manual37

Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)

Destructed registers
Tool chain

Destructed registers

CA78K0R

None

IAR V1.xx

None

IAR V2.xx

A, C, HL

GNU

None

CC-RL

A, C, HL

LLVM

A, C, HL

Pre- The library initialization and open via FDL_Init and FDL_Open shall be done before
conditions: calling this function.
Post- In case of finished command the status is written to the request structure associated toconditions: the currently running command.
Description: This function is used by the application to proceed the execution of a running command
initiated by FDL_Execute function.

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

R01US0061ED0140
User Manual38Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)3.3.6 FDL_Abort
Outline: Function for erase command abortion.
Interface: C Interface for CA78K0R Compiler
fdl_status_t __far FDL_Abort(void)

C Interface for IAR V1.xx Compiler__far_func fdl_status_t FDL_Abort(void)

C Interface for IAR V2.xx Compiler__far_func fdl_status_t FDL_Abort(void)

C Interface for GNU Compiler
fdl_status_t FDL_Abort(void) __attribute__ ((section ("FDL_CODE")))C Interface for CC-RL Compiler
fdl_status_t __far FDL_Abort(void)

C Interface for LLVM Compiler
fdl_status_t __far FDL_Abort(void)__attribute__ ((section ("FDL_CODE")))ASM function label
FDL_AbortArguments: Parameters
none

R01US0061ED0140
User Manual39Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)Return valueType
fdl_status_t

Passed via
CA78K0R

IAR
V1.xx

IAR
V2.xx

GNU

CC-RL

LLVM

C

A

A

R8
(X bank 1)

A

A

FDL_OK when either no command is running or erase has been aborted.
FDL_BUSY when byte oriented command is still running.

Destructed registers
Tool chain

Destructed registers

CA78K0R

None

IAR V1.xx

None

IAR V2.xx

BC, HL

GNU

None

CC-RL

BC, HL

LLVM

BC, HL

Pre- The library initialization and open via FDL_Init and FDL_Open shall be done before
conditions: calling this function.
Post- In case of a running erase the command will be aborted and requester will be informed
conditions: via the request status FDL_ERR_ABORTED.
Description: This function enables the application to abort a running erase command (independent of
the affected pool) immediately. The requester will be informed regarding the stopped
erase via the request status FDL_ERR_ABORTED. In such a case the application shallre-start the erase command otherwise the block cannot be used. Other commands likeblankcheck, write and internal verify cannot be aborted and therefore have to be finishedproperly. If the application calls this function during the above described byte commands
the return value FDL_BUSY will be returned. That means a byte command is still running.
Please re-call the FDL_Abort functions as long as the status is FDL_BUSY. Only when
the return value is changed to FDL_OK the command is properly finished.

Example:__near fdl_request_t__near fdl_u08

my_fdl_request_str;
cmd_finished = 0;/* request structure initialization */my_fdl_request.index_u16= 0x0000;
my_fdl_request.data_pu08= (__near fdl_u08*) 0x0000;
my_fdl_request.bytecount_u16= 0x0000;
my_fdl_request.command_enu= (fdl_command_t)0xFF;
my_fdl_request.status_enu= FDL_ERR_PARAMETER;/* set erase command */my_fdl_request.index_u16
my_fdl_request.command_enu

R01US0061ED0140
User Manual= 0x0000;= FDL_CMD_ERASE_BLOCK;40

Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)/* ################# TASK 1 #################### *//* ######## TRY TO ERASE HERE ONE BLOCK ######## *//* ############################################# */FDL_Execute(&my_fdl_request);
cmd_finished = 0;
while (cmd_finished == 0){
switch (my_fdl_request.status_enu){
case FDL_BUSY:
FDL_Handler();break;
case FDL_ERR_ABORTED:/* start erase again in case it was aborted */FDL_Execute(&my_fdl_request);
FDL_Handler();break;
case FDL_ERR_REJECTED:/* try again if request not accepted */FDL_Execute(&my_fdl_request);
FDL_Handler();break;
default:
cmd_finished = 1;
break;}}
if (my_fdl_request.status_enu != FDL_OK){
error_handler();}/* #################### TASK 2 ####################### *//* ######## WILL BE USED FOR EMERGENCY WRITE ######## */
.....
do
{

abort_status = FDL_Abort();}while( abort_status != FDL_OK);
DRIVER IS NO MORE BUSY HERE.
PERFORM EMERGENCY WRITE HERE ....................

R01US0061ED0140
User Manual41

Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)3.3.7 FDL_StandBy
Outline: Function to drive the library into StandBy mode.
Interface: C Interface for CA78K0R Compiler
fdl_status_t __far FDL_StandBy(void)

C Interface for IAR V1.xx Compiler__far_func fdl_status_t FDL_StandBy(void)

C Interface for IAR V2.xx Compiler__far_func fdl_status_t FDL_StandBy(void)

C Interface for GNU Compiler
fdl_status_t FDL_StandBy(void) __attribute__ ((section ("FDL_CODE")))C Interface for CC-RL Compiler
fdl_status_t __far FDL_StandBy(void)

C Interface for LLVM Compiler
fdl_status_t __far FDL_StandBy(void)__attribute__ ((section ("FDL_CODE")))ASM function label
FDL_StandBy

Arguments: Parameters
none

R01US0061ED0140
User Manual42Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)Return value
Type

Passed via
CA78K0R

IAR
V1.xx

IAR
V2.xx

GNU

CC-RL

LLVM

C

A

A

R8
(X bank 1)

AA

fdl_status_t

FDL_OK when FDL entered StandBy mode.
FDL_BUSY any command is still running.

Destructed registers
Tool chain

Destructed registers

CA78K0R

None

IAR V1.xx

None

IAR V2.xx

C, HL

GNU

None

CC-RL

C, HL

LLVM

C, HL

Pre- The library initialization and open via FDL_Init and FDL_Open shall be done before
conditions: calling this function.
Post- Data flash clock is switched off and library is in StandBy mode.
conditions:
Description: The main purpose of this function is to drive the library and Data Flash into the StandBy
mode. StandBy mode means that•the Data Flash hardware is switched off (the DFLEN bit of the Data flash control
register is cleared), and•the library does not accept any command requests

Note: It is not allowed to call any FDL function other than FDL_WakeUp and
FDL_Handler when FDL is in StandBy mode.
Example:do{standby_status = FDL_StandBy();}
while (standby_status != FDL_OK);#######################################
E.G. ENTER STOP/HALT MODE HERE ........
#######################################
wakeup_status = FDL_WakeUp();

R01US0061ED0140
User Manual43

Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)if(wakeup_status != FDL_OK){
flow_error_handler();}
E.G. CONTINUE WITH LIBRARY/APPLICATION EXECUTION HERE ...............

R01US0061ED0140
User Manual44Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)3.3.8 FDL_WakeUp
Outline: Function to wake up the library from StandBy mode.
Interface: C Interface for CA78K0R Compiler
fdl_status_t __far FDL_WakeUp(void)

C Interface for IAR V1.xx Compiler__far_func fdl_status_t FDL_WakeUp(void)

C Interface for IAR V2.xx Compiler__far_func fdl_status_t FDL_WakeUp(void)

C Interface for GNU Compiler
fdl_status_t FDL_WakeUp(void) __attribute__ ((section ("FDL_CODE")))C Interface for CC-RL Compiler
fdl_status_t__far FDL_WakeUp(void)

C Interface for LLVM Compiler
fdl_status_t__far FDL_WakeUp(void)__attribute__ ((section ("FDL_CODE")))ASM function label
FDL_WakeUp

Arguments: Parameters
none

R01US0061ED0140
User Manual45Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)Return value
Type

Passed via
CA78K0R

IAR
V1.xx

IAR
V2.xx

GNU

CC-RL

LLVM

C

A

A

R8
(X bank 1)

AA

fdl_status_t

FDL_OK when FDL is up and running.
FDL_ERR_REJECTED when library isn't in StandBy mode.

Destructed registers
Tool chain

Destructed registers

CA78K0R

None

IAR V1.xx

None

IAR V2.xx

X

GNU

None

CC-RL

X

LLVM

X

Pre- The library initialization and open via FDL_Init and FDL_Open shall be done before
conditions: calling this function.
Post- Data flash clock is switched on and library is up and running.
conditions:
Description: The main purpose of this function is to wake-up the library and Data Flash hardware fromthe StandBy mode. After successful execution of this function,•

the Data Flash hardware is switched on(the DFLEN bit of the Data flash control
register is set), and•the FDL accepts new command requests.

Example:wakeup_status = FDL_WakeUp();if(wakeup_status != FDL_OK){
flow_error_handler();}
E.G. CONTINUE WITH LIBRARY EXECUTION HERE ...............

R01US0061ED0140
User Manual46Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)3.3.9 FDL_GetVersionString
Outline: Function for reading library version information.
Interface: C Interface for CA78K0R Compiler__far fdl_u08* __far FDL_GetVersionString(void)

C Interface for IAR V1.xx Compiler__far_func fdl_u08 __far* FDL_GetVersionString(void)

C Interface for IAR V2.xx Compiler__far_func fdl_u08 __far * FDL_GetVersionString(void)

C Interface for GNU Compiler
fdl_u08 __far* FDL_GetVersionString(void)__attribute__ ((section ("FDL_CODE")))C Interface for CC-RL Compiler__far fdl_u08* __far FDL_GetVersionString(void)

C Interface for LLVM Compiler__far fdl_u08* __far FDL_GetVersionString(void)__attribute__ ((section ("FDL_CODE")))ASM function label
FDL_GetVersionStringArguments: Parameters
none

R01US0061ED0140
User Manual47

Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)Return valueType

fdl_u08* (far)Passed via
CA78K0R

IAR
V1.xx

IAR
V2.xx

GNU

CC-RL

LLVM

DE(highw),
BC(loww)

A, HLA(high),DE(loww)

R8-R11(AX,BC
bank 1)A(high),DE(loww)A(high),DE(loww)

Pointer to the first character of a zero terminated version string.

Destructed registers
Tool chain

Destructed registers

CA78K0R

None

IAR V1.xx

None

IAR V2.xx

None

GNU

None

CC-RL

None

LLVM

None

Pre- Noneconditions:Post- Noneconditions:

R01US0061ED0140
User Manual48

Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)

Description: For version control at runtime the developer can use this function to find the starting
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 ‘T02’)

•

CCCCC

: compiler information•‘Rxyy_’ for CA78K0R compiler version x.yy•

‘Ixyy_’ for IAR V1.xx compiler version x.yy
‘Uxxyy’ for GNU compiler version xx.yy••‘Lxyyz’ for CC-RL compiler version x.yy.0z
Note: The version string of IAR V2.xx and LLVM indicates that the supported
compiler is CC-RL because the library file for IAR V2.xx and LLVM are
identical to the one for CC-RL.

•G: all memory models (here ‘G’ for general)•

VVV..V: library version•‘Vxyy’ for release version x.yy•

‘Exyyy’ for engineering version x.yyy

Examples:The version string of the Tiny FDL V1.00 for the CA78K0R compiler version 1.10 is:"DRL78T02R110_GV100"
The version string of the Tiny FDL V1.00 for the IAR V1.xx compiler version 1.20 is:"DRL78T02I120_GV100"
The version string of the Tiny FDL V1.01 for the GNU compiler version 13.02 is:"DRL78T02U1302GV101"
The version string of the Tiny FDL V1.01 for the CC-RL compiler version 1.23.04 is:"DRL78T02L1234GV101"
Example:my_version_string_pointer = FDL_GetVersionString();

R01US0061ED0140
User Manual49Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)

3.4 Commands
3.4.1 Blankcheck
The blankcheck command can be used to check if all bits within the addressed range are still “erased”
e.g. before initiating a write. The blankcheck command is initiated by FDL_Execute() and must becontinued by FDL_Handler() as long as command is not finished (request status updated).
Note: Due to the fact that the blankcheck command execution across block boundaries is not allowed thebyte count range vary between 1 byte up to 1024 bytes.
Table 3-5: Request variable usage for blankcheck commandindex_u16

data_pu08

bytecount_u16

command_enu

byte index
inside the FDL pool

unusedbyte count(1 byte to 1024 bytes)

FDL_CMD_BLANKCHECK_BYTESTable 3-6: Status of FDL_CMD_BLANKCHECK_BYTESStatusFDL_ERR_INITIALIZATION

FDL_ERR_STANDBY

FDL_ERR_PARAMETER

FDL_ERR_BLANK_VERIFY

FDL_ERR_REJECTED

FDL_BUSYFDL_OK

R01US0061ED0140
User Manual

Class
heavy

heavy

heavy

light

normalnormalnormalStatus meaning and handlingmeaning

FDL not initialized or not opened

reasonwrong handling on user side

remedyinitialize and open FDL before using it

meaning

FDL is in standby and cannot accept newcommands

reasonwrong handling on user side

remedycall FDL_WakeUp() before initiating newcommands

meaning

request cannot be accepted

reasonwrong command code, index outside the usedpool or request data structure on odd address

remedycorrect affected request member and try again

meaning

at least one byte within the specified pool area
is not “blank”

reasonany bit in the addressed flash area is noterasedremedynothing, free interpretation at requester side

meaning

request cannot be accepted

reasonother command is being executed

remedycall FDL_Handler() and try again

meaning

request is being processedreasonrequest checked and accepted

remedynothing, call FDL_Handler() until statuschangesmeaning

request was finished regularreasonno problems during execution

remedynothing50

Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)3.4.2 Internal Verify
The internal verify command can be used to check if all bits (0’s and 1’s) are electronically correct written.
Inconsistent and weak data caused by an asynchronous RESET can be detected by using the internalverify command. The user can use the internal verify command freely to check the quality of user data.
The internal verify command is initiated by FDL_Execute() and must be continued by FDL_Handler() aslong as command is not finished (request-status updated).
Note: An execution of internal verify commands across block boundaries is not allowed. As a result thebyte count can range from 1 byte up to 1024 byte.
Table 3-7: Request variable usage for internal verify commandindex_u16

data_pu08

bytecount_u16

command_enu

byte index
inside the FDL pool

unusedbyte count(1 byte to 1024 bytes)

FDL_CMD_IVERIFY_BYTESTable 3-8: Status of FDL_CMD_IVERIFY_BYTESStatusFDL_ERR_INITIALIZATION

FDL_ERR_STANDBY

FDL_ERR_PARAMETER

FDL_ERR_BLANK_VERIFY

FDL_ERR_REJECTED

FDL_BUSYFDL_OK

R01US0061ED0140
User Manual

Class
heavy

heavy

heavy

light

normalnormalnormalStatus meaning and handlingmeaning

FDL not initialized or not opened

reasonwrong handling on user side

remedyinitialize and open FDL before using it.

meaning

FDL is in standby and cannot accept newcommands

reasonwrong handling on user side

remedycall FDL_WakeUp() before initiating newcommands

meaning

request cannot be accepted

reasonwrong command code, index outside the usedpool or request data structure on odd address

remedycorrect affected request member and try again

meaning

at least one byte within the specified pool area
could not be verified

reasonany bit in the addressed flash word is notelectrically correct

remedynothing, free interpretation at requester side

meaning

request cannot be accepted

reasonother command is being executed

remedycall FDL_Handler() and try again

meaning

request is being processedreasonrequest checked and accepted

remedynothing, call FDL_Handler() until statuschangesmeaning

request was finished regularly

reasonno problems during execution

remedynothing51

Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)3.4.3 Read
The READ command can be used to read a number of bytes from a specific address range. It is initiatedand finished directly by FDL_Execute(). FDL_Handler() is not needed in that case unless the FDL is busy
with another command.
Note: An execution of read commands across block boundaries is not allowed. As a result the byte countcan range from 1 byte up to 1024 byte.
Table 3-9: Request variable usage for read commandindex_u16

data_pu08

bytecount_u16

command_enu

byte index
inside the FDL pool

pointer to the read buffer

byte count(1 byte to 1024 bytes)

FDL_CMD_READ_BYTESTable 3-10: Status of FDL_CMD_READ_BYTESStatusFDL_ERR_INITIALIZATION

FDL_ERR_STANDBY

FDL_ERR_PARAMETER

FDL_ERR_REJECTED

FDL_OK

R01US0061ED0140
User Manual

Class
heavy

heavy

heavy

normalnormalStatus meaning and handlingmeaning

FDL not initialized or not opened

reasonwrong handling on user side

remedyinitialize and open FDL before using it.

meaning

FDL is in standby and cannot accept newcommands

reasonwrong handling on user side

remedycall FDL_WakeUp() before initiating newcommands

meaning

request cannot be accepted

reasonwrong command code, index outside the usedpool or request data structure on odd address

remedycorrect affected request member and try again

meaning

request cannot be accepted

reasonother command is being executed

remedycall FDL_Handler() and try again

meaning

request was finished regularreasonno problems during execution

remedynothing52

Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)3.4.4 Write
The write command can be used for writing a number of bytes located in a RAM buffer to the data-flash. It
is initiated by FDL_Execute() and must be continued by FDL_Handler() as long as command is notfinished (request-status updated).
Note 1: An execution of write commands across block boundaries is not allowed. As a result the byte
count can range from 1 byte up to 1024 byte.
Note 2: For a regular write, please follow the suggested sequence of blankcheck, write, internal verify inorder to ensure full data retention.
Table 3-11: Request variable usage for write commandindex_u16

data_pu08

bytecount_u16

command_enu

byte index
inside the FDL pool

pointer to the write buffer

byte count(1 byte to 1024 bytes)

FDL_CMD_WRITE_BYTESTable 3-12: Status of FDL_CMD_WRITE_BYTESStatusFDL_ERR_INITIALIZATION

FDL_ERR_STANDBY

FDL_ERR_PARAMETER

FDL_ERR_WRITE

FDL_ERR_REJECTED

FDL_BUSYFDL_OK

R01US0061ED0140
User Manual

Class
heavy

heavy

heavy

heavy

normalnormalnormalStatus meaning and handlingmeaning

FDL not initialized or not opened

reasonwrong handling on user side

remedyinitialize and open FDL before using it.

meaning

FDL is in standby and cannot accept newcommands

reasonwrong handling on user side

remedycall FDL_WakeUp() before initiating newcommands

meaning

request cannot be accepted

reasonwrong command code, index outside the usedpool or request data structure on odd address

remedycorrect affected request member and try again

meaning

at least one byte within the specified pool area
is not “blank”

reasonany bit in the addressed flash word is notelectrically correct

remedynothing, free interpretation at requester side

meaning

request cannot be accepted

reasonother command is being executed

remedycall FDL_Handler() and try again

meaning

request is being processedreasonrequest checked and accepted

remedynothing, call FDL_Handler() until statuschangesmeaning

request was finished regularly

reasonno problems during execution

remedynothing53

Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)3.4.5 Erase
The erase operation can be used to erase one block of the pool. After starting the erase-command, thehardware is checking if the addressed block is already blank to avoid unnecessary erase cycles. In casethe block is not blank the erase pulse is initiated, otherwise the erase command will be finished
immediately.
Table 3-13: Request variable usage for erase commandindex_u16

data_pu08

bytecount_u16

command_enu

block index
inside the FDL pool

unusedunusedFDL_CMD_ERASE_
BLOCK

Table 3-14: Status of FDL_CMD_ERASE_BLOCK
StatusFDL_ERR_INITIALIZATION

FDL_ERR_STANDBY

FDL_ERR_PARAMETER

FDL_ERR_ERASE

FDL_ERR_REJECTED

FDL_ERR_ABORTED

FDL_BUSYFDL_OK

R01US0061ED0140
User Manual

Class
heavy

heavy

heavy

heavy

normalnormalnormalnormalStatus meaning and handlingmeaning

FDL not initialized or not opened

reasonwrong handling on user side

remedyinitialize and open FDL before using it

meaning

FDL is in standby and cannot accept newcommands

reasonwrong handling on user side

remedycall FDL_WakeUp() before initiating newcommands

meaning

request cannot be accepted

reasonwrong command code, index outside the usedpool or request data structure on odd address

remedycorrect affected request member and try again

meaning

at least one byte within the specified pool area
is not “blank”

reasoninternal flash problems

remedydo not use this block anymore

meaning

request cannot be accepted

reasonother command is being executed

remedycall FDL_Handler() and try again

meaning

block oriented command has been aborted

reasonFDL_Abort() has been called by the user
during block command execution

remedyrestart the erase command via FDL_Execute()

meaning

request is being processedreasonrequest checked and accepted

remedynothing, call FDL_Handler() until statuschangesmeaning

request was finished regularly

reasonno problems during execution

remedynothing54

Data Flash Access Library - Type T02 (Tiny), European Release

User Interface (API)

3.5 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.
Power OFFON
POWER OFF
FDL_Init()

closedstandby
FDL_Close()

FDL_WakeUp()
FDL_StandBy()

FDL_Open()

openedrequest.status<> busy

FDL_Execute(CMD)

FDL_Abort()(erase command only)busy

FDL_Handler()(also indirectly via FDL_StandBy() and FDL_Abort() )Figure 3-1: Basic flowchart

R01US0061ED0140
User Manual55

Data Flash Access Library - Type T02 (Tiny), European Release

Chapter 4

FDL Usage by User Application

FDL Usage by User Application

4.1 First Steps
It is very important to have theoretic background about the Data Flash and the FDL in order tosuccessfully integrate the library into the user application. Therefore, it is important to read this user
manual completely in advance especially chapter “Cautions”.

4.2 Special Considerations
4.2.1 Reset Consistency
During the execution of FDL commands (write and erase), a reset could occur and the data flash content
could be damaged. It is designers duty to take care of reset and failure scenarios, e.g. by a proper failuremode and effect analysis. The EEL provided by Renesas Electronics is designed to avoid read of invalid
data caused by such reset scenarios. The following chapter describes the applications where the FDL
and EEL should be used.

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

4.2.2.1 FDL only
By using the FDL only the application has to take care about all reset scenarios and writing flow ofdifferent variables with different sizes.
Application scenarios•

programming of initial or calibration data•

user specific EEPROM emulation

4.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 and additionally the FDL pool for e.g. application data or application
specific EEPROM emulation.
Application scenarios•

programming of initial or calibration data (FDL should be preferred)•large count of variables with high write frequency (EEL should be preferred)•

reset safe data handling (EEL should be preferred)

Please refer to the R01US0070EDxxxx manual for detailed EEL description.

R01US0061ED0140
User Manual56

Data Flash Access Library - Type T02 (Tiny), European Release

FDL Usage by User Application

4.3 File Structure
The Tiny FDL is delivered as precompiled library for CA78K0R, IAR V1.xx, IAR V2.xx, GNU, CC-RL and
LLVM tool chains. The library and its header files are stored in the lib subdirectory inside the installation
folder. The Sample directory contains sample setups which are no integral part of the library itself andshould be modified according to the project needs. The structure of the files in each tool chain is shown in
the table.
Table 4-1: Common files of the Tiny FDL
FileDescription<installation folder>
Release.txt

contains release-specific information about the installed librarysupport.txt

library support information

Table 4-2: File structure of the Tiny FDL for CA78K0R tool chain<installation folder>/CA78K0R_xxx/FDL/lib
fdl.h

FDL header file, FDL interface definition (Compiler)

fdl.inc

FDL header file, FDL interface definition (Assembler)

fdl_types.h

FDL header file, FDL types definition

fdl.lib

precompiled library file

<installation folder>/ CA78K0R_xxx/FDL/Sample/C
fdl_descriptor.cdescriptor calculation partfdl_descriptor.hpool configuration partfdl_sample_linker_file.dr

linker sample file

<installation folder>/ CA78K0R_xxx/FDL/Sample/asm
fdl_descriptor.asm

descriptor calculation partfdl_descriptor.inc

pool configuration partfdl_sample_linker_file.dr

linker sample file

Table 4-3: File structure of the Tiny FDL for IAR V1.xx tool chain<installation folder>/IAR_1xx/FDL/lib
fdl.h

FDL header file, FDL interface definition (Compiler)

fdl_types.h

FDL header file, FDL types definition

fdl.r87

precompiled library file

<installation folder>/IAR_1xx/FDL/Sample/C
fdl_descriptor.cdescriptor calculation partfdl_descriptor.hpool configuration partfdl_sample_linker_file.xcl

linker sample file

R01US0061ED0140
User Manual57

Data Flash Access Library - Type T02 (Tiny), European Release

FDL Usage by User Application

Table 4-4: File structure of the Tiny FDL for IAR V2.xx tool chain<installation folder>/IAR_2xx/FDL/lib
fdl.h

FDL header file, FDL interface definition (Compiler)

fdl_types.h

FDL header file, FDL types definition

fdl.a

precompiled library file

<installation folder>/IAR_2xx/FDL/Sample/C
fdl_descriptor.cdescriptor calculation partfdl_descriptor.hpool configuration partfdl_sample_linker_file.icf

linker sample file

Table 4-5: File structure of the Tiny FDL for CC-RL tool chain<installation folder>/CCRL_xxx/FDL/lib
fdl.h

FDL header file, FDL interface definition (Compiler)

fdl.inc

FDL header file, FDL interface definition (Assembler)

fdl_types.h

FDL header file, FDL types definition

fdl.lib

precompiled library file

<installation folder>/ CCRL_xxx/FDL/Sample/C
fdl_descriptor.cdescriptor calculation partfdl_descriptor.hpool configuration partfdl_sample_linker_file.sub

linker sample file

<installation folder>/ CCRL_xxx/FDL/Sample/asm
fdl_descriptor.asm

descriptor calculation partfdl_descriptor.inc

pool configuration partfdl_sample_linker_file.sub

linker sample file

Table 4-6: File structure of the Tiny FDL for GNU tool chain<installation folder>/GNU_xxxx/FDL/lib
fdl.h

FDL header file, FDL interface definition (Compiler)

fdl_types.h

FDL header file, FDL types definition

fdl.a

precompiled library file

<installation folder>/GNU_xxxx/FDL/Sample/C
fdl_descriptor.cdescriptor calculation partfdl_descriptor.hpool configuration partfdl_sample_linker_file.ld

linker sample file

R01US0061ED0140
User Manual58

Data Flash Access Library - Type T02 (Tiny), European Release

FDL Usage by User Application

Table 4-7: File structure of the Tiny FDL for LLVM tool chain<installation folder>/LLVM_xxxxxx/FDL/lib
fdl.h

FDL header file, FDL interface definition (Compiler)

fdl_types.h

FDL header file, FDL types definition

libfdl.aprecompiled library file

<installation folder>/LLVM_xxxxxx/FDL/Sample/C
fdl_descriptor.cdescriptor calculation partfdl_descriptor.hpool configuration partfdl_sample_linker_file.ld

linker sample file

4.4 Configuration
4.4.1 Linker Sections
Following segments are defined by the library and must be configured via the linker description file.
FDL_CODE

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

FDL_CNST

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

FDL_SDAT

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

Note: Please refer to the Chapter 6 and device user’s manual for restrictions of RAM and ROM usage.

4.4.2 Descriptor Configuration (Partitioning of the Data Flash)
Before the FDL can be used, the FDL pool and its partitioning have to be configured first. The descriptor
is defining the physical/virtual addresses and parameter of the pool which will be automatically calculated
by using the FDL_POOL_BLOCKS and EEL_POOL_BLOCKS 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 in blocks. Also the physical size of the pool is limited by the
hardware and must not be defined by the user. Also, the physical size of a flash block is a predefinedconstant determined by the used hardware.
The first configuration parameter is FDL_POOL_BLOCKS. The minimum value is 0 and means any
access to the FDL-pool is closed. The maximum value is the data flash size expressed in blocks in case
EEL pool is not used.
The second configuration parameter is EEL_POOL_BLOCKS, the size of the EEL-pool used exclusively
for Renesas EEPROM emulation library only. When proprietary EEPROM emulation library is used the
EEL-pool shall be set to 0. The maximum size of the EEL-pool is the data flash size build on the device.
Note:- The virtual address 0 of the FDL pool corresponds with the successor of the last EEL-pool bytes.

R01US0061ED0140
User Manual59Data Flash Access Library - Type T02 (Tiny), European Release

FDL Usage by User Application

4.4.3 Prohibited RAM Area
The Tiny FDL may use a fraction of the user RAM as working area, referred as prohibited RAM area. The
size and position of this area is strictly device dependent (many devices do not even have this area) andvary between the different RL78 products. For details, please refer to the document “User's Manual:
Hardware” of your RL78 product.
If a prohibited RAM area is specified for the utilized device, it is not allowed to access this area while theTiny FDL is active. Whenever FDL functions are called, the data in the prohibited area may be rewritten.

4.4.4 Register BankThe CA78K0R, IAR V1.xx, IAR V2.xx, CC-RL and LLVM releases of the FDL use the registers of thecurrently selected register bank. No implicit register bank switch is performed by the library.
For the GNU release of the FDL, it is mandatory that register bank 0 is active on function entry. No implicit
register bank switch is performed by the library. Return values are placed in register bank 1. For details
on GNU calling conventions, please refer to the GNU documentation for RL78 devices.

4.4.5 Stack and Data Buffer
The Tiny FDL utilizes the same stack as specified in the user application. It is the developer’s duty toreserve enough free stack for the operation of both, user application and FDL.
The data buffer used by the Tiny FDL refers to the RAM area in which data is located that is to be written
into the data flash and where data is to be copied to when read is performed. These buffers need to beallocated and managed by the user.
Note: In order to allocate the stack and data buffer to a user-specified address, please utilize the link
directives of your framework.
Caution: In contrast to the internal FDL data (FDL_SDAT segment), both stack and data buffer may not
be allocated in the short address range from 0xFFE20 to 0xFFEFF—and also not in the prohibited RAM
area, if it exists in the target device.

4.4.6 Request Structure
Depending on the user application architecture more than one request variable could be necessary.
e.g.: in case of accessing the EEL from different tasks.

R01US0061ED0140
User Manual60Data Flash Access Library - Type T02 (Tiny), European Release

FDL Usage by User Application

4.5 General Flow
4.5.1 Initialization
The following figure illustrates the initialization flow.
................

FDL_Init()

FDL_ERR_CONFIGURATION

status?

FDL_OK
FDL_Open()

Execute any FDL
commands

FDL_Close()

Error handler

Figure 4-1: Initialization flow

R01US0061ED0140
User Manual61Data Flash Access Library - Type T02 (Tiny), European Release

FDL Usage by User Application

4.5.2 Read
The following figure illustrates the read command handling.
................

fill request
CMD(read)

FDL_Execute(CMD)
FDL_Handler()YES

status ==FDL_ERR_RE
JECTED….............
FDL_WakeUp()….............

NO

status ==FDL_ERR_ST
ANDBY

YES

NO

status?

OTHER

FDL_OK
Error handler................

Figure 4-2: FDL read command execution

R01US0061ED0140
User Manual62

Data Flash Access Library - Type T02 (Tiny), European Release

FDL Usage by User Application

4.5.3 Blankcheck/Write/Internal Verify/Erase
The following figure illustrates the blankcheck/write/internal verify/erase command flow.
................
fill request
CMD

FDL_Execute(CMD)

FDL_Handler()

YES….............
FDL_WakeUp()….............

status ==FDL_ERR_RE
JECTEDNO
status ==FDL_ERR_ST
ANDBY

YES

NO
status ==FDL_BUSYNOYES

FDL_Handler()YES

status ==FDL_BUSY?
NO

YES(erase command only)

status ==FDL_ERR_AB
ORTED?
NO
status !=FDL_OK?

YES

Error handler

NO................

Figure 4-3: Background operation (Internal Verify/Blankcheck)

R01US0061ED0140
User Manual63

Data Flash Access Library - Type T02 (Tiny), European Release

FDL Usage by User Application

4.6 Example of FDL used in Operating Systems
The background-operation feature and request-response structure of the FDL allow the user to use 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.

Task 1 (each 50ms)
if(req1.status != FDL_BUSY){
FDL_Execute(req1);}

operating system

IDLE Task
FDL_Handler();

Task 2 (each 100ms)
if(req2.status != FDL_BUSY){
FDL_Execute(req2);}do{Task 3 (emergency task)
FDL_Execute(req_et)
FDL_Handler();}while(req_et.status == FDL_ERR_REJECTED);
while(req_et.status == FDL_BUSY){
FDL_Handler();}

Figure 4-4: FDL used in an operating system
This operating system example shows three different task types which are described below.
Requesting tasks
Examples of this type of task are Task 1 and 2. Such tasks just start any FDL command via the
FDL_Execute function and assume that it will be finished in the background via the IDLE task. Please
note that the mandatory error handling is not shown in this example for the sake of readability.
IDLE task
The IDLE task will be used by the application for continuing any running FDL command. That means the
FDL_Handler must be called inside of such a task.
Emergency task
The difference between this task type and the requesting type (Task 1 and Task 2) is that this task
performs any FDL commands completely without waiting in the background. Such task can be used incase of voltage drop where important data must be saved before the device is off. Please note thatdesigner could use the abort feature here(for details see Chapter 2.6).

R01US0061ED0140
User Manual64Data Flash Access Library - Type T02 (Tiny), European Release

FDL Usage by User Application

4.7 Example: Simple application
The following sample shows how to use each command in a simple way.
extern __far const fdl_descriptor_t
fdl_status_t__near fdl_request_t
fdl_u08

fdl_descriptor_str;
my_fdl_status_enu;
request;buffer[5];/* initialization */my_fdl_status_enu = FDL_Init((__far fdl_descriptor_t*)&fdl_descriptor_str );if(my_fdl_status_enu != FDL_OK) ErrorHandler();
FDL_Open();/* request structure initialization */request.index_u16= 0x0000;
request.data_pu08= (__near fdl_u08*) 0x0000;
request.bytecount_u16= 0x0000;
request.command_enu= (fdl_command_t)0xFF;
request.status_enu= FDL_ERR_PARAMETER;/* erase block 0 */request.index_u16= 0x0000;
request.command_enu= FDL_CMD_ERASE_BLOCK;FDL_Execute(&request);
while(request.status_enu == FDL_BUSY) FDL_Handler();if(request.status_enu != FDL_OK)
ErrorHandler();/* write pattern 0x123456789A to idx = 0 */buffer[0] = 0x12;
buffer[1] = 0x34;
buffer[2] = 0x56;
buffer[3] = 0x78;
buffer[4] = 0x9A;
request.index_u16= 0x0000;
request.data_pu08= (__near fdl_u08*)&buffer[0];request.bytecount_u16= 0x0005;
request.command_enu= FDL_CMD_WRITE_BYTES;FDL_Execute(&request);
while(request.status_enu == FDL_BUSY) FDL_Handler();if(request.status_enu != FDL_OK)
ErrorHandler();/* set initial values */buffer[0] = 0xFF;
buffer[1] = 0xFF;
buffer[2] = 0xFF;
buffer[3] = 0xFF;
buffer[3] = 0xFF;
request.index_u16= 0x0000;
request.data_pu08= (__near fdl_u08*)&buffer[0];request.bytecount_u16= 0x0005;
request.command_enu= FDL_CMD_READ_BYTES;FDL_Execute(&request);
if(request.status_enu != FDL_OK)
ErrorHandler();
FDL_Close();R01US0061ED0140
User Manual65Data Flash Access Library - Type T02 (Tiny), European Release

Chapter 5

Characteristics

Characteristics

5.1 Resource Consumption
All values are based on the FDL version V1.01 for CA78K0R, IAR V2.xx, GNU, CC-RL and LLVM
Compiler and FDL version V1.02 for IAR V1.xx Compiler.
Table 5-1: Resource consumption
CA78K0R IAR V1.xx IAR V2.xx
Compiler Compiler Compiler

GNU
Compiler

CC-RL
Compiler

LLVM
CompilerMax. code size (code flash)

572 bytes

591 bytes

548 bytes

596 bytes

548 bytes

548 bytes

Constants (code flash)

10 bytes

10 bytes

10 bytes

10 bytes

10 bytes

10 bytes

Internal data
(SADDR RAM)

2 bytes

2 bytes

2 bytes

2 bytes

2 bytes

2 bytesMax. stack (RAM)56 bytes

56 bytes

48 bytes

60 bytes

48 bytes

48 bytes

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

5.2.1 Maximum Function Execution Times
The maximum function execution times are listed in the following tables. These timings 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 5-2: Maximum function execution times (full speed mode)
Function
FDL_Init
FDL_Execute(read command)
FDL_Execute(non-read command)

MAX
1199/fclk
167/fclk +(17/fclk × BYTE_COUNT)
646/fclk

FDL_Handler

284/fclk + 15us

FDL_Open

27/fclk + 14us

FDL_Close(no command running)

30/fclk

FDL_Close**1(running command in background)836/fclk + 444us

FDL_StandBy

305/fclk + 15us

FDL_WakeUp

32/fclk + 14us

FDL_Abort

350/fclk + 28us

FDL_GetVersionString
14/fclk
Note **1: It is not recommended to call the FDL_Close function in case of any running command inbackground.
R01US0061ED0140
User Manual66

Data Flash Access Library - Type T02 (Tiny), European Release

Characteristics

Table 5-3: Maximum function execution times (wide voltage mode)
Function
FDL_Init
FDL_Execute(read command)
FDL_Execute(non-read command)

MAX
1199/fclk
167/fclk +(17/fclk × BYTE_COUNT)
646/fclk

FDL_Handler

284/fclk + 15us

FDL_Open

27/fclk + 14us

FDL_Close(no command running)

30/fclk

FDL_Close**1(running command in background)791/fclk + 969us

FDL_StandBy

305/fclk + 15us

FDL_WakeUp

32/fclk + 14us

FDL_Abort

350/fclk + 40us

FDL_GetVersionString
14/fclk
Note **1: It is not recommended to call the FDL_Close function in case of any running command inbackground.

R01US0061ED0140
User Manual67

Data Flash Access Library - Type T02 (Tiny), European Release

Characteristics

5.2.2 Command Execution Times
The command execution times are listed in the following tables. These timings are divided into the typicaltimings which will appear during the normal operation and the max timings for worst case considerations.
Table 5-4: Command execution times (full speed mode)
Command

TYP

MAX

blankcheck1000/fclk + 30us
+ (5/fclk + 0.26us) × BYTE_COUNT

1200/fclk + 36us
+ (6/fclk + 0.31us) × BYTE_COUNT

internal verify

715/fclk + 25us+ (24/fclk + 3.33us) × BYTE_COUNT

858/fclk + 30us
+ (29/fclk + 4.00us) × BYTE_COUNT

139/fclk+ (14/fclk × BYTE_COUNT)

167/fclk+ (17/fclk × BYTE_COUNT)

read

580/fclk + 12us696/fclk + 14us+ (212/fclk + 39.17us) × BYTE_COUNT + (714/fclk + 430.00us) × BYTE_COUNT

write

erase
11344/fclk + 5800us
281674/fclk + 264790us
Remarks. fclk: CPU operating frequency. (For example, when using a 20 MHz clock, fclk is 20.)
Table 5-5: Command execution times (wide voltage mode)
Command

TYP

MAX

blankcheck996/fclk + 63us
+ (5/fclk + 0.90us) × BYTE_COUNT

1196/fclk + 75us+ (6/fclk + 1.05us) × BYTE_COUNT

internal verify

715/fclk + 49us+ (15/fclk + 24.17us) × BYTE_COUNT

858/fclk + 58us+ (18/fclk + 29.00us) × BYTE_COUNT

Read

139/fclk+ (14/fclk × BYTE_COUNT)

167/fclk+ (17/fclk × BYTE_COUNT)

Write

580/fclk + 12us+ (209/fclk + 82.50us) × BYTE_COUNT

696/fclk + 14us
+ (670/fclk + 954.00us) × BYTE_COUNT

Erase
10019/fclk + 7195us249113/fclk + 299307us
Remarks. fclk: CPU operating frequency. (For example, when using a 20 MHz clock, fclk is 20.)

R01US0061ED0140
User Manual68Data Flash Access Library - Type T02 (Tiny), European Release

Chapter 6•

Cautions

Cautions

Library code and constants must be located completely in the same 64k flash page.
For CA78K0R compiler, the library takes care in the code to define these sections with UNIT64KP
relocation attribute.
• For CC-RL compiler, the library takes care in the code to define these sections withTEXTF_UNIT64KP relocation attribute.
• For IAR V1.xx and IAR V2.xx compiler, the user has to ensure that the linker file specifies theFlash page size equal to 64k when defining FDL_CODE and FDL_CNST sections.
• For GNU and LLVM compilers, the user shall take care that FDL_CODE and FDL_CNST sections
are not mapped across any boundary of 64k Flash page.
The library initialization by FDL_Init must be performed before the execution of FDL_Open,FDL_Close, FDL_Handler, FDL_Execute, FDL_Abort, FDL_StandBy and FDL_WakeUp.
It is not allowed to read the data flash directly (meaning without FDL) during a command executionof the FDL.
Each request variable must be located at 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 it is not allowed to call FDL functions inside the ISRs
while any FDL function is already running.
Task switches, context changes and synchronization between FDL functions:• All FDL functions depend on FDL global available information and are able to modify thisinformation. In order to avoid synchronization problems, it is necessary that at any time only one
FDL function is executed. So, it is not allowed to start an FDL function, then switch to anothertask context and execute another FDL function while the last one is not yet finished.
• Example for a not allowed sequence:• Task 1: Start an FDL operation with FDL_Execute.
• Interrupt the execution and switch to task 2, executing FDL_Handler.
• Return to task 1 and finish the FDL_Execute function.
After the execution of FDL_Close, all requested/running commands will be aborted and cannot be
resumed. The designer has to take care that all running commands are finished before calling
FDL_Close.
It is not possible to modify the Data Flash via FDL in parallel to a modification of the Code Flash via
FSL.
An abortion of the byte commands read, write, internal verify, and blankcheck is not possible.
Internal high-speed on-chip oscillator (HOCO) must be started before using 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, the following frequencies areallowed: 1MHz, 2MHz, 3MHz. It is not allowed to use the frequency of e.g. 1.5MHz. The libraryconfiguration parameter FDL_SYSTEM_FREQUENCY in "FDL_descriptor.h" shall be adapted
according to the above definition (e.g. 1000000, 2000000, 3000000).
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 device restrictions described in the device user’s manual in case of accessing thedata flash via the FDL
Execution of byte commands (blankcheck, internal verify, write and read) across block boundaries is
not allowed
The watchdog timer does not stop during the execution of the FDL.
Do not use the RAM area used by the FDL (including the prohibited RAM area) before libraries havebeen closed. Please see also "Self RAM list of Flash Self-Programming Library for RL78 Family"(R20UT2944EJxxxx).
•

•
•
•
•
•
•

•
•
•
•
•
•

•
•
•
•
•

R01US0061ED0140
User Manual69

Data Flash Access Library - Type T02 (Tiny), European Release

Cautions

When using an assembler of the CC-RL compiler from Renesas Electronics, the hexadecimal prefix
representation (0x..) cannot be mixed together with the suffix representation (..H). Specify the
representation method by editing the symbol definition in fdl.inc to match the user environment.
•
fdl.inc; __FDL_INC_BASE_NUMBER_SUFFIX .SET 1
When symbol "__FDL_INC_BASE_NUMBER_SUFFIX" is not defined (initial state), the prefix
representation will be selected.
•
fdl.inc__FDL_INC_BASE_NUMBER_SUFFIX .SET 1
When symbol "__FDL_INC_BASE_NUMBER_SUFFIX" is defined, the suffix representation will
be selected.
•
Additional cautions on using the Tiny FDL for IAR V2.xx.
•
Library code and constants must be located completely in the same 32KB memory range.
•
The version string provided by the flash library includes the information on the supported compiler.
The string indicates that the supported compiler is CC-RL because the library file for IAR V2.xx is
identical to the one for CC-RL.
•
If you wish to use a linker configuration file included of the IAR V2.2x compiler (instead of asample linker configuration file in the flash library package), specify flash libraries sections withspecial names for Renesas objects (R_TEXTF_UNIT64KP, R_SBSS) in the linker configuration
file.
e.g.) ro section FDL_CODE -> ro code R_TEXTF_UNIT64KP section FDL_CODE
rw section FDL_SDAT -> rw data R_SBSS section FDL_SDAT
Note:
Section FDL_CNST does not require special names for Renesas objects since this section is
generated from the sample source file (fdl_descriptor.c).Simply declare this flash library section ina linker configuration file as if it is normal section.
e.g.) ro section FDL_CNST• Additional caution on using the Tiny FDL for LLVM.
• The version string provided by the flash library includes the information on the supported compiler.
The string indicates that the supported compiler is CC-RL because the library file for LLVM isidentical to the one for CC-RL.
•

R01US0061ED0140
User Manual70Data Flash Access Library - Type T02 (Tiny), European Release

Revision History

Revision History
Chapter

Page

Description
Initial revision
Revision V1.10:

3.2

23

Add a more detailed description of types and their
meaning

3.3

27

Adding description of GNU API

4.3

51

Extend file structure for GNU

4.4.4

52

Add register bank selection chapter

5.1

59

Updated resource consumption information

6

62

Explain how library can be mapped in the same 64K flash
page for each compiler

3.3
4.3
all
3.4.x/3.4
5.1
3.3
4.3
5.1
6
3.3
4.3
5.1
6

R01US0061ED0140
User Manual

28
54
all
all
62

Revision V1.20:
Adding description of CC-RL API
Extended file structure for CC-RL
Renesas (REN) Compiler renamed to CA78K0R
Byte count range specification added
Resource consumption added for CC-RL

27-45
53
61
64

Revision V1.30:
Adding description of IAR V2.xx compiler API
Extended file structure for IAR V2.xx compiler
Resource consumption added for IAR V2.xx compiler
List of cautions extended

27-49
59
66
69

Revision V1.40:
Adding description of LLVM compiler API
Extended file structure for LLVM compiler
Resource consumption added for LLVM compiler
List of cautions extended71

Data Flash Access Library

R01US0061ED0140