Mirrors_BOOKS/Threadx-docs
1
0
Fork 0
mirror of https://github.com/eclipse-threadx/rtos-docs.git synced 2026-02-06 02:52:14 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Eric Wolz
2024-01-04 13:58:00 -08:00
parent b9f7fddc38
commit ac6725870f
1245 changed files with 169762 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
.gitignore vendored Normal file
View File

@@ -0,0 +1,5 @@
################################################################################
# This .gitignore file was automatically created by Microsoft(R) Visual Studio.
################################################################################
/.vs

17
LICENSE-CODE Normal file
View File

@@ -0,0 +1,17 @@
The MIT License (MIT)
Copyright (c) Microsoft Corporation
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
associated documentation files (the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial
portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

174
README.md Normal file
View File

@@ -0,0 +1,174 @@
# What is Eclipse ThreadX?
Eclipse ThreadX is a real time operating system (RTOS) for Internet of Things (IoT) and edge devices powered by microcontroller units (MCUs). Eclipse ThreadX is designed to support most highly constrained devices (battery powered and having less than 64 KB of flash memory).
Eclipse ThreadX provides an EAL4+ Common Criteria security certified environment, including full IP layer security via IPsec and socket layer security via TLS and DTLS. Our software crypto library has achieved FIPS 140-2 certification. We also leverage hardware cryptographic capabilities, memory protection via ThreadX MODULES, and support for ARM's TrustZone ARMv8-M security features.
## Eclipse ThreadX resources
[Eclipse ThreadX repositories](https://github.com/azure-rtos/)
Documentation for components:
- [ThreadX](./rtos-docs/threadx/index.md)
- [ThreadX Modules](./rtos-docs/threadx-modules/index.md)
- [NetX Duo](./rtos-docs/netx-duo/index.md)
- [GUIX](./rtos-docs/guix/index.md)
- [FileX](./rtos-docs/filex/index.md)
- [LevelX](./rtos-docs/levelx/index.md)
- [USBX](./rtos-docs/usbx/index.md)
- [TraceX](./rtos-docs/tracex/index.md)
Other resources:
- [Product Support Policy](./rtos-docs/general/lts.md)
- [Security Updates](./rtos-docs/general/security-updates.md)
## Components of Eclipse ThreadX
The Eclipse ThreadX platform is the collection of run-time solutions including ThreadX, NetX Duo, FileX, GUIX and USBX.
![The diagram of Eclipse ThreadX system components.](./rtos-docs/media/eclipse-threadx-system-components.png)
### ThreadX
ThreadX is an advanced Real-Time Operating System (RTOS) designed specifically for deeply embedded applications. Among the multiple benefits ThreadX provides are advanced scheduling facilities, message passing, interrupt management, and messaging services. ThreadX has many advanced features, including its picokernel architecture, preemption-threshold scheduling, event-chaining, and a rich set of system services.
### FileX
FileX is a high-performance FAT-compatible file system. It is fully integrated with ThreadX and is available for all supported processors. Like ThreadX, FileX is designed to have a small footprint and high performance, making it ideal for today's deeply embedded applications that require file operations. FileX supports most physical media, including RAM disk, USBX, SD CARD, and NAND/NOR flash memories via LevelX.
### GUIX
GUIX is a professional quality graphical user interface package, created to meet the needs of embedded systems developers. Unlike the alternatives, GUIX is small, fast, and easily ported to virtually any hardware configuration capable of supporting graphical output. GUIX also delivers exceptional visual appeal and an intuitive and powerful API for application-level user interface development.
### NetX Duo
NetX Duo is an advanced, Industrial Grade TCP/IP network stacks designed specifically for deeply embedded, real-time, and IoT applications. NetX Duo is a dual IPv4 and IPv6 network stack.
### USBX
USBX is a high-performance USB host, device, and On-The-Go (OTG) embedded stack. It is fully integrated with ThreadX and is available for all ThreadX supported processors. Like ThreadX, USBX is designed to have a small footprint and high performance, making it ideal for deeply embedded applications that require an interface with USB devices.
### Windows tools
GUIX Studio provides a complete GUI application design environment, facilitating the creation and maintenance of all graphical elements in the application's GUI. GUIX Studio automatically generates C code compatible with the GUIX library, ready to be compiled and run on the target.
TraceX is a host-based analysis tool that provides developers with a graphical view of real-time system events and enables them to visualize and better understand the behavior of their real-time systems.
## The Eclipse ThreadX Advantage
Eclipse ThreadX provides the following advantages over other real-time operating systems.
### Most deployed RTOS
Eclipse ThreadX has over 12 billion deployments worldwide. The popularity of Eclipse ThreadX is a testament to its reliability, quality, size, performance, advanced features, ease-of-use, and overall time-to-market advantages.
> _"We have followed the growth trajectory of THREADX in the wireless and IoT markets since the company's founding, and are increasingly impressed by the widespread industry adoption of THREADX."_ – Chris Rommel, Executive Vice President, VDC Research
### Intuitive and consistent API design
- Intuitive and consistent API.
- Noun-verb naming convention.
- All APIs have leading prefix, such as \_tx\_\_ for ThreadX and \_fx\_\_ for FileX, to easily identify the Eclipse ThreadX component they belong to.
- Functional consistency throughout the APIs. For example, all API functions that suspend have an optional timeout that functions in an identical manner.
- Many APIs are directly available from application ISRs.
- Optional user-notification callbacks for media and file operations.
- Event-driven programming model (API).
### High efficiency
- Small code footprint.
- Scalable code footprint based on the services used.
- Fast execution. Eclipse ThreadX is designed for speed and has minimal internal function call layering to help achieve the fastest possible performance.
### Fastest time-to-market
Eclipse ThreadX is easy to install, learn, use, debug, verify, certify, and maintain. As a result, Eclipse ThreadX is one of the most popular real time operating systems for embedded IoT devices, including many SoCs from Broadcom, Gainspan, and so forth. Our consistent time-to-market advantage is built on:
- Complete source code availability.
- Easy-to-use API.
- Comprehensive and advanced feature set.
- Quality documentation.
### One Simple License
There is no cost to use and test the source code and no cost for production licenses when deployed to pre-licensed devices, all other devices need a license.
### Full, highest-quality source code
Throughout the years, Eclipse ThreadX source code has set the bar in quality and ease of understanding. In addition, the convention of having one function per file provides for easy source navigation.
### Pre-certified by TÜV and UL to many safety standards
Eclipse ThreadX has been certified by SGS-TÜV Saar for use in safety-critical systems, according to IEC-61508 SIL 4. The certification confirms that Eclipse ThreadX can be used in the development of safety-related software for the highest safety integrity levels of IEC-61508 for the "Functional Safety of electrical, electronic, and programmable electronic safety-related systems." SGS-TUV Saar, formed through a joint venture of Germany's SGS-Group and TUV Saarland, has become the leading accredited, independent company for testing, auditing, verifying, and certifying embedded software for safety-related systems worldwide.
![SGS-TUV certification](./rtos-docs/media/partener-logo-sgs-tuv-saar.png)
Eclipse ThreadX has been recognized by UL for compliance with UL 60730-1 Annex H, CSA E60730-1 Annex H, IEC 60730-1 Annex H, UL 60335-1 Annex R, IEC 60335-1 Annex R, and UL 1998 safety standards for software in programmable components. UL is a global, independent, safety-science company with more than a century of expertise innovating safety solutions, ranging from the public adoption of electricity to breakthroughs in sustainability, renewable energy, and nanotechnology.
![CRU UL certification](./rtos-docs/media/cru-logo-certification.png)
Artifacts (Certificate, Safety Manual, Test Report, etc.) associated with the TUV and UL certifications are available to license.
In cases where the application needs additional certification, a certification service is available through Eclipse Foundation for providing turn-key certification to various standards using the actual hardware platform and even covering the application code. Contact us for more details on our certification service.
### EAL4+ Common Criteria security certification
ThreadX has achieved EAL4+ Common Criteria security certification. The Target of Evaluation (TOE) covers ThreadX, NetX Duo, NetX Secure TLS, and NetX MQTT. This represents the most typical IoT protocols required by deeply embedded sensors, devices, edge routers, and gateways.
![EAL certification](./rtos-docs/media/eal-logo-certification.png)
The IT Security Evaluation Facility used for the Eclipse ThreadX SC security certification is Brightsight BV and the Certification Authority is SERTIT.
### FIPS 140-2 Validated
Eclipse ThreadX Crypto libraries have achieved Federal Information Processing Standardization 140-2 (FIPS 140-2) Certification for software, which specifies requirements for cryptography modules. FIPS 140-2 requires all federal government agencies and departments that use cryptographic-based security to meet specific standards related to encryption strength and capabilities. These cryptographic-based security standards are also recognized in Canada and the European Union.
The Information Security evaluation lab used for Eclipse ThreadX Crypto libraries was atsec and the certification authority is [The National Institute of Standards and Technology (NIST)](https://csrc.nist.gov/projects/cryptographic-module-validation-program/Certificate/3394).
### Supports most popular architectures
Eclipse ThreadX works on most popular 32/64-bit microprocessors, out-of-the-box, fully tested and fully supported, including the following advanced architectures:
- **Analog Devices**: SHARC, Blackfin, CM4xx
- **Andes Core**: RISC-V
- **Ambiqmicro**: Apollo MCUs
- **ARM**: ARM7, ARM9, ARM11, Cortex-M0/M3/M4/M7/A15/A5/A7/A8/A9/A5x 64-bi/A7x 64-bit/R4/R5, TrustZone ARMv8-M
- **Cadence**: Xtensa, Diamond
- **CEVA**: PSoC, PSoC 4, PSoC 5, PSoC 6, FM0+, FM3, MF4, WICED WiFi
- **Cypress**: RISC-V
- **EnSilica**: eSi-RISC
- **Infineon**: XMC1000, XMC4000, TriCore
- **Intel; Intel FPGA**: x36/Pentium, XScale, NIOS II, Cyclone, Arria 10
- **Microchip**: AVR32, ARM7, ARM9, Cortex-M3/M4/M7, SAM3/4/7/9/A/C/D/E/G/L/SV, PIC24/PIC32
- **Microsemi**: RISC-V
- **NXP**: i.MX RT10xx and RT116x/7x series crossover MCUs, LPC5500 series
- **Renesas**: SH, HS, V850, RX, RZ, Synergy
- **Silicon Labs**: EFM32
- **Synopsys**: ARC 600, 700, ARC EM, ARC HS
- **ST**: STM32, ARM7, ARM9, Cortex-M3/M4/M7
- **Tl**: C5xxx, C6xxx, Stellaris, Sitara, Tiva-C
- **Wave Computing**: MIPS32 4K, 24 K, 34 K, 1004 K, MIPS64 5K, microAptiv, interAptiv, proAptiv, M-Class
- **Xilinx**: MicroBlaze, PowerPC 405, ZYNQ, ZYNQ UltraSCALE
_All timing and size figures listed are estimates and may be different on your development platform._

75
rtos-docs/filex/about-this-guide.md Normal file
View File

@@ -0,0 +1,75 @@
---
title: FileX user guide
description: This guide contains comprehensive information about FileX, the high-performance real-time file system from Eclipse Foundation.
---
# About This FileX User Guide
This guide contains comprehensive information about FileX, the high-performance, real-time embedded file system from Eclipse Foundation. To gain the most from this guide, you should be familiar with standard real-time operating system functions, FAT file system services, and the C programming language.
## Organization
[Chapter 1](chapter1.md) - Introduces FileX
[Chapter 2](chapter2.md) - Gives the basic steps to install and use FileX with your ThreadX application
[Chapter 3](chapter3.md) - Provides a functional overview of the FileX system and basic information about FAT file system formats
[Chapter 4](chapter4.md) - Details the application's interface to FileX
[Chapter 5](chapter5.md) - Describes the supplied FileX RAM driver and how to write your own custom FileX drivers
[Chapter 6](chapter6.md) - Describes the FileX Fault Tolerant Module
[Appendix A](appendix-a.md) - FileX Services
[Appendix B](appendix-b.md) - FileX Constants
[Appendix C](appendix-c.md) - FileX Data Types
[Appendix D](appendix-d.md) - ASCII Chart
## Guide Conventions
*Italics* - Typeface denotes book titles, emphasizes important words, and indicates variables.
**Boldface** - Typeface denotes file names,
key words, and further emphasizes important words and variables.
> **Note:** Information symbols draw attention to important or additional information that could affect performance or function.
> **Important:** Warning symbols draw attention to situations that developers should avoid because they could cause fatal errors.
## FileX Data Types
In addition to the custom FileX control structure data types, there is a series of special data types that are used in FileX service call interfaces. These special data types map directly to data types of the underlying C compiler. This is done to ensure portability between different C compilers. The exact implementation is inherited from ThreadX and can be found in the tx_port.h file included in the ThreadX distribution.
The following is a list of FileX service call data types and their associated meanings.
| Type | Description |
|---|---|
| **UINT** | Basic unsigned integer. This type must support 8-bit unsigned data; however, it is mapped to the most convenient unsigned data type. |
| **ULONG** | Unsigned long type. This type must support 32-bit unsigned data. |
| **VOID** | Almost always equivalent to the compiler's void type. |
| **CHAR** | Most often a standard 8-bit character type. |
| **ULONG64** | 64-bit unsigned integer data type. |
Additional data types are used within the FileX source. They are located in either the ***tx_port.h*** or ***fx_port.h*** files.
## Troubleshooting
For troubleshooting, be sure to collect the following information.
1. A detailed description of the problem, including frequency of occurrence and whether it can be reliably reproduced.
2. A detailed description of any changes to the application and/or FileX that preceded the problem.
3. The contents of the _tx_version_id and
_fx_version_id strings found in the ***tx_port.h*** and ***fx_port.h*** files of your distribution. These strings will provide valuable information regarding your run-time environment.
4. The contents in RAM of the following **ULONG** variables. These variables will give information on how your ThreadX and FileX libraries were built:
**_tx_build_options**
**_fx_system_build_options1**
**_fx_system_build_options2**
**_fx_system_build_options3**

188
rtos-docs/filex/appendix-a.md Normal file
View File

@@ -0,0 +1,188 @@
---
title: Appendix A - FileX services
description: Learn about the FileX Services.
---
# Appendix A - FileX services
## System Services
```c
UINT fx_system_date_get(UINT *year, UINT *month, UINT *day);
UINT fx_system_date_set(UINT year, UINT month, UINT day);
UINT fx_system_time_get(UINT *hour, UINT *minute, UINT *second);
UINT fx_system_time_set(UINT hour, UINT minute, UINT second);
VOID fx_system_initialize(VOID);
```
## Media Services
```c
UINT fx_media_abort(FX_MEDIA *media_ptr);
UINT fx_media_cache_invalidate(FX_MEDIA *media_ptr);
UINT fx_media_check(FX_MEDIA *media_ptr, UCHAR *scratch_memory_ptr,
ULONG scratch_memory_size, ULONG error_correction_option,
ULONG *errors_detected_ptr);
UINT fx_media_close(FX_MEDIA *media_ptr);
UINT fx_media_close_notify_set(FX_MEDIA *media_ptr, VOID (*media_close_notify)(FX_MEDIA *media));
UINT fx_media_exFAT_format(FX_MEDIA *media_ptr, VOID (*driver)(FX_MEDIA *media),
VOID *driver_info_ptr, UCHAR *memory_ptr,
UINT memory_size, CHAR *volume_name,
UINT number_of_fats, ULONG64 hidden_sectors,
ULONG64 total_sectors, UINT bytes_per_sector,
UINT sectors_per_cluster, UINT volume_serial_number,
UINT boundary_unit);
UINT fx_media_extended_space_available(FX_MEDIA *media_ptr, ULONG64 *available_bytes_ptr);
UINT fx_media_flush(FX_MEDIA *media_ptr);
UINT fx_media_format(FX_MEDIA *media_ptr, VOID (*driver)(FX_MEDIA *media),
VOID *driver_info_ptr, UCHAR *memory_ptr,
UINT memory_size, CHAR *volume_name,
UINT number_of_fats, UINT directory_entries,
UINT hidden_sectors, ULONG total_sectors,
UINT bytes_per_sector, UINT sectors_per_cluster,
UINT heads, UINT sectors_per_track);
UINT fx_media_open(FX_MEDIA *media_ptr, CHAR *media_name,
VOID (*media_driver)(FX_MEDIA *),
VOID *driver_info_ptr, VOID *memory_ptr,
ULONG memory_size);
UINT fx_media_open_notify_set(FX_MEDIA *media_ptr, VOID (*media_open_notify)(FX_MEDIA *media));
UINT fx_media_read(FX_MEDIA *media_ptr, ULONG logical_sector, VOID *buffer_ptr);
UINT fx_media_space_available(FX_MEDIA *media_ptr, ULONG *available_bytes_ptr);
UINT fx_media_volume_get(FX_MEDIA *media_ptr, CHAR *volume_name, UINT volume_source);
UINT fx_media_volume_get_extended(FX_MEDIA *media_ptr, CHAR *volume_name,
UINT volume_name_buffer_length, UINT volume_source);
UINT fx_media_volume_set(FX_MEDIA *media_ptr, CHAR *volume_name);
UINT fx_media_write(FX_MEDIA *media_ptr, ULONG logical_sector, VOID *buffer_ptr);
```
## Directory Services
```c
UINT fx_directory_attributes_read(FX_MEDIA *media_ptr, CHAR *directory_name,
UINT *attributes_ptr);
UINT fx_directory_attributes_set(FX_MEDIA *media_ptr, CHAR *directory_name,
UINT attributes);
UINT fx_directory_create(FX_MEDIA *media_ptr, CHAR *directory_name);
UINT fx_directory_default_get(FX_MEDIA *media_ptr, CHAR **return_path_name);
UINT fx_directory_default_set(FX_MEDIA *media_ptr, CHAR *new_path_name);
UINT fx_directory_delete(FX_MEDIA *media_ptr, CHAR *directory_name);
UINT fx_directory_first_entry_find(FX_MEDIA *media_ptr, CHAR *directory_name);
UINT fx_directory_first_full_entry_find(FX_MEDIA *media_ptr, CHAR *directory_name,
UINT *attributes, ULONG *size,
UINT *year, UINT *month, UINT *day,
UINT *hour, UINT *minute, UINT *second);
UINT fx_directory_information_get(FX_MEDIA *media_ptr, CHAR *directory_name,
UINT *attributes, ULONG *size,
UINT *year, UINT *month, UINT *day,
UINT *hour, UINT *minute, UINT *second);
UINT fx_directory_local_path_clear(FX_MEDIA *media_ptr);
UINT fx_directory_local_path_get(FX_MEDIA *media_ptr, CHAR **return_path_name);
UINT fx_directory_local_path_restore(FX_MEDIA *media_ptr, FX_LOCAL_PATH *local_path_ptr);
UINT fx_directory_local_path_set(FX_MEDIA *media_ptr, FX_LOCAL_PATH *local_path_ptr,
CHAR *new_path_name);
UINT fx_directory_long_name_get(FX_MEDIA *media_ptr, CHAR *short_name, CHAR *long_name);
UINT fx_directory_long_name_get_extended( FX_MEDIA *media_ptr, CHAR *short_name,
CHAR *long_name, UINT long_file_name_buffer_length);
UINT fx_directory_name_test(FX_MEDIA *media_ptr, CHAR *directory_name);
UINT fx_directory_next_entry_find(FX_MEDIA *media_ptr, CHAR *directory_name);
UINT fx_directory_next_full_entry_find(FX_MEDIA *media_ptr, CHAR *directory_name,
UINT *attributes, ULONG *size,
UINT *year,UINT *month, UINT *day,
UINT *hour, UINT *minute, UINT *second);
UINT fx_directory_rename(FX_MEDIA *media_ptr, CHAR *old_directory_name,
CHAR *new_directory_name);
UINT fx_directory_short_name_get(FX_MEDIA *media_ptr, CHAR *long_name,
CHAR *short_name);
UINT fx_directory_short_name_get_extended(FX_MEDIA *media_ptr, CHAR *long_name,
CHAR *short_name, UINT short_file_name_length);
```
## File Services
```c
UINT fx_fault_tolerant_enable(FX_MEDIA *media_ptr, VOID *memory_buffer, UINT memory_size);
UINT fx_file_allocate(FX_FILE *file_ptr, ULONG size);
UINT fx_file_attributes_read(FX_MEDIA *media_ptr, CHAR *file_name, UINT *attributes_ptr);
UINT fx_file_attributes_set(FX_MEDIA *media_ptr, CHAR *file_name, UINT attributes);
UINT fx_file_best_effort_allocate(FX_FILE *file_ptr, ULONG size, ULONG *actual_size_allocated);
UINT fx_file_close(FX_FILE *file_ptr);
UINT fx_file_create(FX_MEDIA *media_ptr, CHAR *file_name);
UINT fx_file_date_time_set(FX_MEDIA *media_ptr, CHAR *file_name,
UINT year, UINT month, UINT day,
UINT hour, UINT minute, UINT second);
UINT fx_file_delete(FX_MEDIA *media_ptr, CHAR *file_name);
UINT fx_file_extended_allocate(FX_FILE *file_ptr, ULONG64 size);
UINT fx_file_extended_best_effort_allocate(FX_FILE *file_ptr, ULONG64 size,
ULONG64 *actual_size_allocated);
UINT fx_file_extended_relative_seek(FX_FILE *file_ptr, ULONG64 byte_offset,
UINT seek_from);
UINT fx_file_extended_seek(FX_FILE *file_ptr, ULONG64 byte_offset);
UINT fx_file_extended_truncate(FX_FILE *file_ptr, ULONG64 size);
UINT fx_file_extended_truncate_release(FX_FILE *file_ptr, ULONG64 size);
UINT fx_file_open(FX_MEDIA *media_ptr, FX_FILE *file_ptr,
CHAR *file_name, UINT open_type);
UINT fx_file_read(FX_FILE *file_ptr, VOID *buffer_ptr,
ULONG request_size, ULONG *actual_size);
UINT fx_file_relative_seek(FX_FILE *file_ptr, ULONG byte_offset, UINT seek_from);
UINT fx_file_rename(FX_MEDIA *media_ptr, CHAR *old_file_name,
CHAR *new_file_name);
UINT fx_file_seek(FX_FILE *file_ptr, ULONG byte_offset);
UINT fx_file_truncate(FX_FILE *file_ptr, ULONG size);
UINT fx_file_truncate_release(FX_FILE *file_ptr, ULONG size);
UINT fx_file_write(FX_FILE *file_ptr, VOID *buffer_ptr, ULONG size);
UINT fx_file_write_notify_set(FX_FILE *file_ptr, VOID (*file_write_notify)(FX_FILE *file));
```
## Unicode Services
```c
UINT fx_unicode_directory_create(FX_MEDIA *media_ptr, UCHAR *source_unicode_name,
ULONG source_unicode_length, CHAR *short_name);
UINT fx_unicode_directory_rename(FX_MEDIA *media_ptr, UCHAR *old_unicode_name,
ULONG old_unicode_length, UCHAR *new_unicode_name,
ULONG new_unicode_length, CHAR *new_short_name);
UINT fx_unicode_file_create(FX_MEDIA *media_ptr, UCHAR *source_unicode_name,
ULONG source_unicode_length, CHAR *short_name);
UINT fx_unicode_file_rename(FX_MEDIA *media_ptr, UCHAR *old_unicode_name,
ULONG old_unicode_length, UCHAR *new_unicode_name,
ULONG new_unicode_length, CHAR *new_short_name);
ULONG fx_unicode_length_get(UCHAR *unicode_name);
UINT fx_unicode_length_get_extended(UCHAR *unicode_name, UINT buffer_length);
UINT fx_unicode_name_get(FX_MEDIA *media_ptr, CHAR *source_short_name,
UCHAR *destination_unicode_name, ULONG *destination_unicode_length);
UINT fx_unicode_name_get_extended(FX_MEDIA *media_ptr, CHAR *source_short_name,
UCHAR *destination_unicode_name, ULONG *destination_unicode_length,
ULONG unicode_name_buffer_length);
UINT fx_unicode_short_name_get(FX_MEDIA *media_ptr, UCHAR *source_unicode_name,
ULONG source_unicode_length, CHAR *destination_short_name);
UINT fx_unicode_short_name_get_extended(FX_MEDIA *media_ptr, UCHAR *source_unicode_name,
ULONG source_unicode_length, CHAR *destination_short_name,
ULONG short_name_buffer_length);
```

446
rtos-docs/filex/appendix-b.md Normal file
View File

@@ -0,0 +1,446 @@
---
title: Appendix B - FileX constants
description: Learn about the FileX constants.
---
# Appendix B - FileX constants
## Alphabetic Listings
| Constant (by alphabetic) | Value |
|--------------------------------------|----------------|
|EXFAT_BIT_MAP_FIRST_TABLE |0|
|EXFAT_BOOT_REGION_SIZE |24|
|EXFAT_DEFAULT_BOUNDARY_UNIT |28|
|EXFAT_FAT_BITS |2|
|EXFAT_FAT_BYTES_PER_SECTOR_SHIFT |0x009|
|EXFAT_FAT_DRIVE_SELECT |0x080|
|EXFAT_FAT_FILE_SYS_REVISION |0x100|
|EXFAT_FAT_NUM_OF_FATS |0x001|
|EXFAT_FAT_VOLUME_FLAG |0x000|
|EXFAT_FAT_VOLUME_NAME_FIELD_SIZE |11|
|EXFAT_LAST_CLUSTER_MASK |0xFFFFFFFF|
|EXFAT_MIN_NUM_OF_RESERVED_SECTORS |1|
|EXFAT_NUM_OF_DIR_ENTRIES |2|
|FX_12_BIT_FAT_SIZE |4086|
|FX_12BIT_SIZE |3|
|FX_16_BIT_FAT_SIZE |65525|
|FX_ACCESS_ERROR |0x06|
|FX_ALREADY_CREATED |0x0B|
|FX_ARCHIVE |0x20|
|FX_BAD_CLUSTER |0xFFF7|
|FX_BAD_CLUSTER_32 |0x0FFFFFF7|
|FX_BAD_CLUSTER_EXFAT |0x0FFFFFF7|
|FX_BASE_YEAR |1980|
|FX_BIGDOS |0x06|
|FX_BOOT_ERROR |0x01|
|FX_BOOT_SECTOR |1|
|FX_BOOT_SECTOR_SIZE |512|
|FX_BOOT_SIG |0x026|
|FX_BUFFER_ERROR |0x21|
|FX_BYTES_SECTOR |0x00B|
|FX_CALLER_ERROR |0x20|
|FX_DATA_SECTOR |4|
|FX_DAY_MASK |0x1F|
|FX_DIR_ENTRY_DONE |0x00|
|FX_DIR_ENTRY_FREE |0xE5|
|FX_DIR_ENTRY_SIZE |32|
|FX_DIR_EXT_SIZE |3|
|FX_DIR_NAME_SIZE |8|
|FX_DIR_NOT_EMPTY |0x10|
|FX_DIR_RESERVED |8|
|FX_DIRECTORY |0x10|
|FX_DIRECTORY_ERROR |0x02|
|FX_DIRECTORY_SECTOR |3|
|FX_DRIVE_NUMBER |0x024|
|FX_DRIVER_ABORT |3|
|FX_DRIVER_BOOT_READ |5|
|FX_DRIVER_BOOT_WRITE |7|
|FX_DRIVER_FLUSH |2|
|FX_DRIVER_INIT |4|
|FX_DRIVER_READ |0|
|FX_DRIVER_RELEASE_SECTORS |6|
|FX_DRIVER_UNINIT |8|
|FX_DRIVER_WRITE |1|
|FX_EF_BOOT_CODE |120|
|FX_EF_BYTE_PER_SECTOR_SHIFT |108|
|FX_EF_CLUSTER_COUNT |92|
|FX_EF_CLUSTER_HEAP_OFFSET |88|
|FX_EF_DRIVE_SELECT |111|
|FX_EF_FAT_LENGTH |84|
|FX_EF_FAT_OFFSET |80|
|FX_EF_FILE_SYSTEM_REVISION |104|
|FX_EF_FIRST_CLUSTER_OF_ROOT_DIR |96|
|FX_EF_MUST_BE_ZERO |11|
|FX_EF_NUMBER_OF_FATS |110|
|FX_EF_PARTITION_OFFSET |64|
|FX_EF_PERCENT_IN_USE |112|
|FX_EF_RESERVED |113|
|FX_EF_SECTOR_PER_CLUSTER_SHIFT |109|
|FX_EF_VOLUME_FLAGS |106|
|FX_EF_VOLUME_LENGTH |72|
|FX_EF_VOLUME_SERIAL_NUMBER |100|
|FX_END_OF_FILE |0x09|
|FX_ERROR_FIXED |0x92|
|FX_ERROR_NOT_FIXED |0x93|
|FX_EXFAT |0x07|
|FX_EXFAT_BIT_MAP_NUM_OF_CACHED_SECTORS|1|
|FX_EXFAT_BITMAP_CLUSTER_FREE |0|
|FX_EXFAT_BITMAP_CLUSTER_OCCUPIED |1|
|FX_EXFAT_FAT_CHECK_SUM_OFFSET |11|
|FX_EXFAT_FAT_MAIN_BOOT_SECTOR_OFFSET |1|
|FX_EXFAT_FAT_MAIN_SYSTEM_AREA_SIZE |12|
|FX_EXFAT_FAT_NUM_OF_SYSTEM_AREAS |2|
|FX_EXFAT_FAT_OEM_PARAM_OFFSET |9|
|FX_EXFAT_MAX_DIRECTORY_SIZE |0x10000000|
|FX_EXFAT_SIZE_OF_FAT_ELEMENT_SHIFT |2|
|FX_FALSE |0|
|FX_FAT_CACHE_DEPTH |4|
|FX_FAT_CACHE_HASH_MASK |0x3|
|FX_FAT_CHAIN_ERROR |0x01|
|FX_FAT_ENTRY_START |2|
|FX_FAT_MAP_SIZE |128|
|FX_FAT_READ_ERROR |0x03|
|FX_FAT_SECTOR |2|
|FX_FAT12 |0x01|
|FX_FAT16 |0x04|
|FX_FAT32 |0x0B|
|FX_FAULT_TOLERANT_CACHE_SIZE |1024|
|FX_FILE_ABORTED_ID |0x46494C41UL|
|FX_FILE_CLOSED_ID |0x46494C43UL|
|FX_FILE_CORRUPT |0x08|
|FX_FILE_ID |0x46494C45UL|
|FX_FILE_SIZE_ERROR |0x08|
|FX_FILE_SYSTEM_TYPE |0x036|
|FX_FREE_CLUSTER |0x0000|
|FX_HEADS |0x01A|
|FX_HIDDEN |0x02|
|FX_HIDDEN_SECTORS |0x01C|
|FX_HOUR_MASK |0x1F|
|FX_HOUR_SHIFT |11|
|FX_HUGE_SECTORS |0x020|
|FX_INITIAL_DATE |0x4761|
|FX_INITIAL_TIME |0x0000|
|FX_INVALID_ATTR |0x19|
|FX_INVALID_CHECKSUM |0x95|
|FX_INVALID_DAY |0x14|
|FX_INVALID_HOUR |0x15|
|FX_INVALID_MINUTE |0x16|
|FX_INVALID_MONTH |0x13|
|FX_INVALID_NAME |0x0C|
|FX_INVALID_OPTION |0x24|
|FX_INVALID_PATH |0x0D|
|FX_INVALID_SECOND |0x17|
|FX_INVALID_STATE |0x97|
|FX_INVALID_YEAR |0x12|
|FX_IO_ERROR |0x90|
|FX_JUMP_INSTR |0x000|
|FX_LAST_CLUSTER_1 |0xFFF8|
|FX_LAST_CLUSTER_1_32 |0x0FFFFFF8|
|FX_LAST_CLUSTER_2 |0xFFFF|
|FX_LAST_CLUSTER_2_32 |0x0FFFFFFF|
|FX_LAST_CLUSTER_EXFAT |0x0FFFFFFF|
|FX_LONG_NAME |0xF|
|FX_LONG_NAME_ENTRY_LEN |13|
|FX_LOST_CLUSTER_ERROR |0x04|
|FX_MAX_12BIT_CLUST |0x0FF0|
|FX_MAX_EX_FAT_NAME_LEN |255|
|FX_MAX_FAT_CACHE |256|
|FX_MAX_LAST_NAME_LEN |256|
|FX_MAX_LONG_NAME_LEN |256|
|FX_MAX_SECTOR_CACHE |256|
|FX_MAX_SHORT_NAME_LEN |13|
|FX_MAXIMUM_HOUR |23|
|FX_MAXIMUM_MINUTE |59|
|FX_MAXIMUM_MONTH |12|
|FX_MAXIMUM_PATH |256|
|FX_MAXIMUM_SECOND |59|
|FX_MAXIMUM_YEAR |2107|
|FX_MEDIA_ABORTED_ID |0x4D454441UL|
|FX_MEDIA_CLOSED_ID |0x4D454443UL|
|FX_MEDIA_ID |0x4D454449UL|
|FX_MEDIA_INVALID |0x02|
|FX_MEDIA_NOT_OPEN |0x11|
|FX_MEDIA_TYPE |0x015|
|FX_MINUTE_MASK |0x3F|
|FX_MINUTE_SHIFT |5|
|FX_MONTH_MASK |0x0F|
|FX_MONTH_SHIFT |5|
|FX_NO_FAT |0xFF|
|FX_NO_MORE_ENTRIES |0x0F|
|FX_NO_MORE_SPACE |0x0A|
|FX_NOT_A_FILE |0x05|
|FX_NOT_AVAILABLE |0x94|
|FX_NOT_DIRECTORY |0x0E|
|FX_NOT_ENOUGH_MEMORY |0x91|
|FX_NOT_FOUND |0x04|
|FX_NOT_IMPLEMENTED |0x22|
|FX_NOT_OPEN |0x07|
|FX_NOT_USED |0x0001|
|FX_NULL |0|
|FX_NUMBER_OF_FATS |0x010|
|FX_OEM_NAME |0x003|
|FX_OPEN_FOR_READ |0|
|FX_OPEN_FOR_READ_FAST |2|
|FX_OPEN_FOR_WRITE |1|
|FX_PTR_ERROR |0x18|
|FX_READ_CONTINU |0x96|
|FX_READ_ONLY |0x01|
|FX_RESERVED |0x025|
|FX_RESERVED_1 |0xFFF0|
|FX_RESERVED_1_32 |0x0FFFFFF0|
|FX_RESERVED_1_EXFAT |0xFFFFFFF8|
|FX_RESERVED_2 |0xFFF6|
|FX_RESERVED_2_32 |0x0FFFFFF6|
|FX_RESERVED_2_EXFAT |0xFFFFFFFE|
|FX_RESERVED_SECTOR |0x00E|
|FX_ROOT_CLUSTER_32 |0x02C|
|FX_ROOT_DIR_ENTRIES |0x011|
|FX_SECOND_MASK |0x1F|
|FX_SECTOR_CACHE_DEPTH |4|
|FX_SECTOR_CACHE_HASH_ENABLE |16|
|FX_SECTOR_CACHE_HASH_MASK |0x3|
|FX_SECTOR_INVALID |0x89|
|FX_SECTORS |0x013|
|FX_SECTORS_CLUSTER |0x00D|
|FX_SECTORS_PER_FAT |0x016|
|FX_SECTORS_PER_FAT_32 |0x024|
|FX_SECTORS_PER_TRK |0x018|
|FX_SEEK_BACK |3|
|FX_SEEK_BEGIN |0|
|FX_SEEK_END |1|
|FX_SEEK_FORWARD |2|
|FX_SIG_BYTE_1 |0x55|
|FX_SIG_BYTE_2 |0xAA|
|FX_SIG_OFFSET |0x1FE|
|FX_SIGN_EXTEND |0xF000|
|FX_SUCCESS |0x00|
|FX_SYSTEM |0x04|
|FX_TRUE |1|
|FX_UNKNOWN_SECTOR |0|
|FX_VOLUME |0x08|
|FX_VOLUME_ID |0x027|
|FX_VOLUME_LABEL |0x02B|
|FX_WRITE_PROTECT |0x23|
|FX_YEAR_MASK |0x7F|
|FX_YEAR_SHIFT |9|
## Listings by Value
| Constant (by value) | Value |
|-----------|-----------|
|FX_DIR_ENTRY_DONE|0x00|
|FX_DRIVER_READ|0|
|FX_FALSE|0|
|EXFAT_BIT_MAP_FIRST_TABLE|0|
|FX_FREE_CLUSTER|0x0000|
|FX_INITIAL_TIME|0x0000|
|FX_JUMP_INSTR|0x000|
|FX_NULL|0|
|FX_OPEN_FOR_READ|0|
|FX_SEEK_BEGIN|0|
|FX_SUCCESS|0x00|
|FX_UNKNOWN_SECTOR|0|
|FX_EXFAT_FAT_MAIN_BOOT_SECTOR_OFFSET|0|
|FX_EXFAT_BITMAP_CLUSTER_FREE|0|
|EXFAT_FAT_VOLUME_FLAG|0x000|
|FX_BOOT_ERROR|0x01|
|FX_BOOT_SECTOR|1|
|FX_DRIVER_WRITE|1|
|FX_FAT_CHAIN_ERROR|0x01|
|FX_NOT_USED|0x0001|
|FX_OPEN_FOR_WRITE|1|
|FX_READ_ONLY|0x01|
|FX_FAT12|0x01|
|EXFAT_FAT_NUM_OF_FATS|0x001|
|FX_SEEK_END|1|
|FX_TRUE|1|
|FX_EXFAT_BIT_MAP_NUM_OF_CACHED_SECTORS|1|
|FX_EXFAT_BITMAP_CLUSTER_OCCUPIED|1|
|FX_EXFAT_FAT_EXT_BOOT_SECTOR_OFFSET|1|
EXFAT_MIN_NUM_OF_RESERVED_SECTORS|1|
|FX_DIRECTORY_ERROR|0x02|
|FX_HIDDEN|0x02|
|FX_MEDIA_INVALID|0x02|
|FX_DRIVER_FLUSH|2|
|FX_FAT_ENTRY_START|2|
|FX_FAT_SECTOR|2|
|FX_OPEN_FOR_READ_FAST|2|
|FX_SEEK_FORWARD|2|
|FX_EXFAT_SIZE_OF_FAT_ELEMENT_SHIFT|2|
|FX_EXFAT_FAT_NUM_OF_SYSTEM_AREAS|2|
EXFAT_NUM_OF_DIR_ENTRIES|2|
|FX_12BIT_SIZE|3|
|FX_DIR_EXT_SIZE|3|
|FX_DIRECTORY_SECTOR|3|
|FX_DRIVER_ABORT|3|
|FX_FAT_CACHE_HASH_MASK|0x3|
|FX_FAT_READ_ERROR|0x03|
|FX_OEM_NAME|0x003|
|FX_SECTOR_CACHE_HASH_MASK|0x3|
|FX_SEEK_BACK|3|
|FX_DATA_SECTOR|4|
|FX_DRIVER_INIT|4|
|FX_FAT_CACHE_DEPTH|4|
|FX_FAT16|0x04|
|FX_LOST_CLUSTER_ERROR|0x04|
|FX_NOT_FOUND|0x04|
|FX_SECTOR_CACHE_DEPTH|4|
|FX_SYSTEM|0x04|
|FX_DRIVER_BOOT_READ|5|
|FX_MINUTE_SHIFT|5|
|FX_MONTH_SHIFT|5|
|FX_NOT_A_FILE|0x05|
|FX_ACCESS_ERROR|0x06|
|FX_BIGDOS|0x06|
|FX_DRIVER_RELEASE_SECTORS|6|
|FX_DRIVER_BOOT_WRITE|7|
|FX_NOT_OPEN|0x07|
|FX_EXFAT|0x07|
|FX_DIR_NAME_SIZE|8|
|FX_DIR_RESERVED|8|
|FX_DRIVER_UNINIT|8|
|FX_FILE_CORRUPT|0x08|
|FX_FILE_SIZE_ERROR|0x08|
|FX_VOLUME|0x08|
|FX_END_OF_FILE|0x09|
|EXFAT_FAT_BYTES_PER_SECTOR_SHIFT|0x009|
|FX_YEAR_SHIFT|9|
|FX_EXFAT_FAT_OEM_PARAM_OFFSET|9|
|FX_NO_MORE_SPACE|0x0A|
|FX_EF_MUST_BE_ZERO|11|
|EXFAT_FAT_VOLUME_NAME_FIELD_SIZE|11|
|FX_ALREADY_CREATED|0x0B|
|FX_FAT32|0x0B|
|FX_BYTES_SECTOR|0x00B|
|FX_HOUR_SHIFT|11|
|FX_EXFAT_FAT_CHECK_SUM_OFFSET|11|
|FX_INVALID_NAME|0x0C|
|FX_MAXIMUM_MONTH|12|
|FX_EXFAT_FAT_MAIN_SYSTEM_AREA_SIZE|12|
|FX_INVALID_PATH|0x0D|
|FX_SECTORS_CLUSTER|0x00D|
|FX_LONG_NAME_ENTRY_LEN|13|
|FX_MAX_SHORT_NAME_LEN|13|
|FX_NOT_DIRECTORY|0x0E|
|FX_RESERVED_SECTORS|0x00E|
|FX_LONG_NAME|0xF|
|FX_MONTH_MASK|0x0F|
|FX_NO_MORE_ENTRIES|0x0F|
|FX_DIR_NOT_EMPTY|0x10|
|FX_DIRECTORY|0x10|
|FX_MAX_FAT_CACHE|16|
|FX_MAX_SECTOR_CACHE|16|
|FX_NUMBER_OF_FATS|0x010|
|FX_SECTOR_CACHE_HASH_ENABLE|16|
|FX_MEDIA_NOT_OPEN|0x11|
|FX_ROOT_DIR_ENTRIES|0x011|
|FX_INVALID_YEAR|0x12|
|FX_INVALID_MONTH|0x13|
|FX_SECTORS|0x013|
|FX_INVALID_DAY|0x14|
|FX_INVALID_HOUR|0x15|
|FX_MEDIA_TYPE|0x015|
|FX_INVALID_MINUTE|0x16|
|FX_SECTORS_PER_FAT|0x016|
|FX_INVALID_SECOND|0x17|
|FX_MAXIMUM_HOUR|23|
|FX_PTR_ERROR|0x18|
|EXFAT_BOOT_REGION_SIZE|24|
|FX_SECTORS_PER_TRK|0x018|
|FX_INVALID_ATTR|0x19|
|FX_HEADS|0x01A|
|FX_HIDDEN_SECTORS|0x01C|
|FX_DAY_MASK|0x1F|
|FX_HOUR_MASK|0x1F|
|FX_SECOND_MASK|0x1F|
|FX_ARCHIVE|0x20|
|FX_CALLER_ERROR|0x20|
|FX_DIR_ENTRY_SIZE|32|
EXFAT_FAT_BITS|32|
|FX_HUGE_SECTORS|0x020|
|FX_BUFFER_ERROR|0x21|
|FX_MAX_LONG_NAME_LEN|33|
|FX_NOT_IMPLEMENTED|0x22|
|FX_WRITE_PROTECT|0x23|
|FX_DRIVE_NUMBER|0x024|
|FX_INVALID_OPTION|0x24|
|FX_SECTORS_PER_FAT_32|0x024|
|FX_RESERVED|0x025|
|FX_BOOT_SIG|0x026|
|FX_VOLUME_ID|0x027|
|FX_VOLUME_LABEL|0x02B|
|FX_ROOT_CLUSTER_32|0x02C|
|FX_FILE_SYSTEM_TYPE|0x036|
|FX_MAXIMUM_MINUTE|59|
|FX_MAXIMUM_SECOND|59|
|FX_MINUTE_MASK|0x3F|
|FX_EF_PARTITION_OFFSET|64|
|FX_EF_VOLUME_LENGTH|72|
|FX_EF_FAT_OFFSET|80|
|FX_EF_FAT_LENGTH|84|
|FX_SIG_BYTE_1|0x55|
|FX_EF_CLUSTER_HEAP_OFFSET|88|
|FX_EF_CLUSTER_COUNT|92|
|FX_EF_FIRST_CLUSTER_OF_ROOT_DIR|96|
|FX_EF_VOLUME_SERIAL_NUMBER|100|
|FX_EF_FILE_SYSTEM_REVISION|104|
|FX_EF_VOLUME_FLAGS|106|
|FX_EF_BYTE_PER_SECTOR_SHIFT|108|
|FX_EF_SECTOR_PER_CLUSTER_SHIFT|109|
|FX_EF_NUMBER_OF_FATS|110|
|FX_EF_DRIVE_SELECT|11|
|FX_EF_PERCENT_IN_USE|112|
|FX_EF_RESERVED|113|
|FX_EF_BOOT_CODE|120|
|FX_YEAR_MASK|0x7F|
|EXFAT_FAT_DRIVE_SELECT|0x80|
|FX_FAT_MAP_SIZE|128|
EXFAT_DEFAULT_BOUNDARY_UNIT|128|
|FX_SECTOR_INVALID|0x89|
|FX_IO_ERROR|0x90|
|FX_NOT_ENOUGH_MEMORY|0x91|
|FX_ERROR_FIXED|0x92|
|FX_ERROR_NOT_FIXED|0x93|
|FX_NOT_AVAILABLE|0x94|
|FX_INVALID_CHECKSUM|0x95|
|FX_READ_CONTINUE|0x96|
|FX_INVALID_STATE|0x97|
|FX_SIG_BYTE_2|0xAA|
|FX_DIR_ENTRY_FREE|0xE5|
|FX_NO_FAT|0xFF|
|EXFAT_FAT_FILE_SYS_REVISION|0x100|
|FX_MAX_EX_FAT_NAME_LEN|255|
|FX_MAXIMUM_PATH|256|
|FX_SIG_OFFSET|0x1FE|
|FX_BOOT_SECTOR_SIZE|512|
|FX_FAULT_TOLERANT_CACHE_SIZE|1024|
|FX_BASE_YEAR|1980|
|FX_MAXIMUM_YEAR|2107|
|FX_MAX_12BIT_CLUST|0x0FF0|
|FX_12_BIT_FAT_SIZE|4086|
|FX_INITIAL_DATE|0x4761|
|FX_SIGN_EXTEND|0xF000|
|FX_RESERVED_1|0xFFF0|
|FX_16_BIT_FAT_SIZE|65525|
|FX_RESERVED_2|0xFFF6|
|FX_BAD_CLUSTER|0xFFF7|
|FX_LAST_CLUSTER_1|0xFFF8|
|FX_LAST_CLUSTER_2|0xFFFF|
|FX_RESERVED_1_32|0x0FFFFFF0|
|FX_RESERVED_2_32|0x0FFFFFF6|
|FX_BAD_CLUSTER_32|0x0FFFFFF7|
|FX_LAST_CLUSTER_1_32|0x0FFFFFF8|
|FX_LAST_CLUSTER_2_32|0x0FFFFFFF|
|FX_EXFAT_MAX_DIRECTORY_SIZE|0x10000000|
|FX_FILE_ABORTED_ID|0x46494C41UL|
|FX_FILE_CLOSED_ID|0x46494C43UL|
|FX_FILE_ID|0x46494C45UL|
|FX_MEDIA_ABORTED_ID|0x4D454441UL|
|FX_MEDIA_CLOSED_ID|0x4D454443UL|
|FX_MEDIA_ID|0x4D454449UL|
|FX_RESERVED_1_EXFAT|0xFFFFFFF8|
|FX_RESERVED_2_EXFAT|0xFFFFFFFE|
|FX_BAD_CLUSTER_EXFAT|0xFFFFFFF7|
|FX_LAST_CLUSTER_EXFAT|0xFFFFFFFF|
EXFAT_LAST_CLUSTER_MASK|0xFFFFFFFF|

314
rtos-docs/filex/appendix-c.md Normal file
View File

@@ -0,0 +1,314 @@
---
title: Appendix C - FileX data types
description: Learn about the FileX data types.
---
# Appendix C - FileX data types
## FX_DIR_ENTRY
```c
typedef struct FX_DIR_ENTRY_STRUCT
{
CHAR *fx_dir_entry_name;
CHAR fx_dir_entry_short_name[FX_MAX_SHORT_NAME_LEN];
UINT fx_dir_entry_long_name_present;
UINT fx_dir_entry_long_name_shorted;
UCHAR fx_dir_entry_attributes;
UCHAR fx_dir_entry_reserved;
UCHAR fx_dir_entry_created_time_ms;
UINT fx_dir_entry_created_time;
UINT fx_dir_entry_created_date;
UINT fx_dir_entry_last_accessed_date;
UINT fx_dir_entry_time;
UINT fx_dir_entry_date;
ULONG fx_dir_entry_cluster;
ULONG64 fx_dir_entry_file_size;
ULONG64 fx_dir_entry_log_sector;
ULONG fx_dir_entry_byte_offset;
ULONG fx_dir_entry_number;
ULONG fx_dir_entry_last_search_cluster;
ULONG fx_dir_entry_last_search_relative_cluster;
ULONG64 fx_dir_entry_last_search_log_sector;
ULONG fx_dir_entry_last_search_byte_offset;
ULONG64 fx_dir_entry_next_log_sector;
#ifdef FX_ENABLE_EXFAT
CHAR fx_dir_entry_dont_use_fat;
UCHAR fx_dir_entry_type;
ULONG64 fx_dir_entry_available_file_size;
ULONG fx_dir_entry_secondary_count;
#endif
} FX_DIR_ENTRY;
```
## FX_PATH
```c
typedef struct FX_PATH_STRUCT
{
FX_DIR_ENTRY fx_path_directory;
CHAR fx_path_string[FX_MAXIMUM_PATH];
CHAR fx_path_name_buffer[FX_MAX_LONG_NAME_LEN];
ULONG fx_path_current_entry;
} FX_PATH;
```
## FX_CACHED_SECTOR
```c
typedef FX_PATH FX_LOCAL_PATH;
typedef struct FX_CACHED_SECTOR_STRUCT
{
UCHAR *fx_cached_sector_memory_buffer;
ULONG fx_cached_sector;
UCHAR fx_cached_sector_buffer_dirty;
UCHAR fx_cached_sector_valid;
UCHAR fx_cached_sector_type;
UCHAR fx_cached_sector_reserved;
struct FX_CACHED_SECTOR_STRUCT
*fx_cached_sector_next_used;
} FX_CACHED_SECTOR;
```
## FX_MEDIA
```c
typedef struct FX_MEDIA_STRUCT
{
ULONG fx_media_id;
CHAR *fx_media_name;
UCHAR *fx_media_memory_buffer;
ULONG fx_media_memory_size;
UINT fx_media_sector_cache_hashed;
ULONG fx_media_sector_cache_size;
UCHAR *fx_media_sector_cache_end;
struct FX_CACHED_SECTOR_STRUCT
*fx_media_sector_cache_list_ptr;
ULONG fx_media_sector_cache_hashed_sector_valid;
ULONG fx_media_sector_cache_dirty_count;
UINT fx_media_bytes_per_sector;
UINT fx_media_sectors_per_track;
UINT fx_media_heads;
ULONG64 fx_media_total_sectors;
ULONG fx_media_total_clusters;
#ifdef FX_ENABLE_EXFAT
ULONG fx_media_exfat_volume_serial_number;
UINT fx_media_exfat_file_system_revision;
UINT fx_media_exfat_volume_flag;
USHORT fx_media_exfat_drive_select;
USHORT fx_media_exfat_percent_in_use;
UINT fx_media_exfat_bytes_per_sector_shift;
UINT fx_media_exfat_sector_per_clusters_shift;
UCHAR fx_media_exfat_bitmap_cache[512];
ULONG fx_media_exfat_bitmap_start_sector;
ULONG fx_media_exfat_bitmap_cache_size_in_sectors;
ULONG fx_media_exfat_bitmap_cache_start_cluster;
ULONG fx_media_exfat_bitmap_cache_end_cluster;
UINT fx_media_exfat_bitmap_clusters_per_sector_shift;
UINT fx_media_exfat_bitmap_cache_dirty;
#endif
UINT fx_media_reserved_sectors;
UINT fx_media_root_sector_start;
UINT fx_media_root_sectors;
UINT fx_media_data_sector_start;
UINT fx_media_sectors_per_cluster;
UINT fx_media_sectors_per_FAT;
UINT fx_media_number_of_FATs;
UINT fx_media_12_bit_FAT;
UINT fx_media_32_bit_FAT;
ULONG fx_media_FAT32_additional_info_sector;
UINT fx_media_FAT32_additional_info_last_available;
#ifdef FX_DRIVER_USE_64BIT_LBA
ULONG64 fx_media_hidden_sectors;
#else
ULONG fx_media_hidden_sectors;
#endif
ULONG fx_media_root_cluster_32;
UINT fx_media_root_directory_entries;
ULONG fx_media_available_clusters;
ULONG fx_media_cluster_search_start;
VOID *fx_media_driver_info;
UINT fx_media_driver_request;
UINT fx_media_driver_status;
UCHAR *fx_media_driver_buffer;
#ifdef FX_DRIVER_USE_64BIT_LBA
ULONG64 fx_media_driver_logical_sector;
#else
ULONG fx_media_driver_logical_sector;
#endif
ULONG fx_media_driver_sectors;
ULONG fx_media_driver_physical_sector;
UINT fx_media_driver_physical_track;
UINT fx_media_driver_physical_head;
UINT fx_media_driver_write_protect;
UINT fx_media_driver_free_sector_update;
UINT fx_media_driver_system_write;
UINT fx_media_driver_data_sector_read;
UINT fx_media_driver_sector_type;
VOID (*fx_media_driver_entry)(struct fx_MEDIA_STRUCT *);
VOID (*fx_media_open_notify)(struct fx_MEDIA_STRUCT *);
VOID (*fx_media_close_notify)(struct fx_MEDIA_STRUCT *);
struct FX_FILE_STRUCT
*fx_media_opened_file_list;
ULONG fx_media_opened_file_count;
struct FX_MEDIA_STRUCT
*fx_media_opened_next,
*fx_media_opened_previous;
#ifndef FX_MEDIA_STATISTICS_DISABLE
ULONG fx_media_directory_attributes_reads;
ULONG fx_media_directory_attributes_sets;
ULONG fx_media_directory_creates;
ULONG fx_media_directory_default_gets;
ULONG fx_media_directory_default_sets;
ULONG fx_media_directory_deletes;
ULONG fx_media_directory_first_entry_finds;
ULONG fx_media_directory_first_full_entry_finds;
ULONG fx_media_directory_information_gets;
ULONG fx_media_directory_local_path_clears;
ULONG fx_media_directory_local_path_gets;
ULONG fx_media_directory_local_path_restores;
ULONG fx_media_directory_local_path_sets;
ULONG fx_media_directory_name_tests;
ULONG fx_media_directory_next_entry_finds;
ULONG fx_media_directory_next_full_entry_finds;
ULONG fx_media_directory_renames;
ULONG fx_media_file_allocates;
ULONG fx_media_file_attributes_reads;
ULONG fx_media_file_attributes_sets;
ULONG fx_media_file_best_effort_allocates;
ULONG fx_media_file_closes;
ULONG fx_media_file_creates;
ULONG fx_media_file_deletes;
ULONG fx_media_file_opens;
ULONG fx_media_file_reads;
ULONG fx_media_file_relative_seeks;
ULONG fx_media_file_renames;
ULONG fx_media_file_seeks;
ULONG fx_media_file_truncates;
ULONG fx_media_file_truncate_releases;
ULONG fx_media_file_writes;
ULONG fx_media_aborts;
ULONG fx_media_flushes;
ULONG fx_media_reads;
ULONG fx_media_writes;
ULONG fx_media_directory_entry_reads;
ULONG fx_media_directory_entry_writes;
ULONG fx_media_directory_searches;
ULONG fx_media_directory_free_searches;
ULONG fx_media_fat_entry_reads;
ULONG fx_media_fat_entry_writes;
ULONG fx_media_fat_entry_cache_read_hits;
ULONG fx_media_fat_entry_cache_read_misses;
ULONG fx_media_fat_entry_cache_write_hits;
ULONG fx_media_fat_entry_cache_write_misses;
ULONG fx_media_fat_cache_flushes;
ULONG fx_media_fat_sector_reads;
ULONG fx_media_fat_sector_writes;
ULONG fx_media_logical_sector_reads;
ULONG fx_media_logical_sector_writes;
ULONG fx_media_logical_sector_cache_read_hits;
ULONG fx_media_logical_sector_cache_read_misses;
ULONG fx_media_driver_read_requests;
ULONG fx_media_driver_write_requests;
ULONG fx_media_driver_boot_read_requests;
ULONG fx_media_driver_boot_write_requests;
ULONG fx_media_driver_release_sectors_requests;
ULONG fx_media_driver_flush_requests;
#endif
#ifndef FX_MEDIA_DISABLE_SEARCH_CACHE
ULONG fx_media_directory_search_cache_hits;
#endif
#ifndef FX_SINGLE_THREAD
TX_MUTEX fx_media_protect;
#endif
#ifndef FX_MEDIA_DISABLE_SEARCH_CACHE
UINT fx_media_last_found_directory_valid;
FX_DIR_ENTRY fx_media_last_found_directory;
FX_DIR_ENTRY fx_media_last_found_entry;
CHAR fx_media_last_found_file_name[FX_MAX_LONG_NAME_LEN];
CHAR fx_media_last_found_name[FX_MAX_LAST_NAME_LEN];
#endif
FX_PATH fx_media_default_path;
FX_FAT_CACHE_ENTRY fx_media_fat_cache[FX_MAX_FAT_CACHE];
UCHAR fx_media_fat_secondary_update_map[FX_FAT_MAP_SIZE];
ULONG fx_media_reserved_for_user;
CHAR fx_media_name_buffer[4*FX_MAX_LONG_NAME_LEN];
#ifdef FX_RENAME_PATH_INHERIT
CHAR fx_media_rename_buffer[FX_MAXIMUM_PATH];
struct FX_CACHED_SECTOR_STRUCT
fx_media_sector_cache[FX_MAX_SECTOR_CACHE];
ULONG fx_media_sector_cache_hash_mask;
ULONG fx_media_disable_burst_cache;
#ifdef FX_ENABLE_FAULT_TOLERANT
UCHAR fx_media_fault_tolerant_enabled;
UCHAR fx_media_fault_tolerant_state;
USHORT fx_media_fault_tolerant_transaction_count;
ULONG fx_media_fault_tolerant_start_cluster;
ULONG fx_media_fault_tolerant_clusters;
ULONG fx_media_fault_tolerant_total_logs;
UCHAR *fx_media_fault_tolerant_memory_buffer;
ULONG fx_media_fault_tolerant_memory_buffer_size;
ULONG fx_media_fault_tolerant_file_size;
ULONG fx_media_fault_tolerant_cached_FAT_sector;
fx_media_fault_tolerant_cache[FX_FAULT_TOLERANT_CACHE_SIZE >> 2];
ULONG fx_media_fault_tolerant_cached_FAT_sector;
#endif
ULONG fx_media_fat_reserved;
ULONG fx_media_fat_last;
UCHAR fx_media_FAT_type;
} FX_MEDIA;
```
## FX_FILE
```c
typedef struct FX_FILE_STRUCT
{
ULONG fx_file_id;
CHAR * fx_file_name;
ULONG fx_file_open_mode;
UCHAR fx_file_modified;
ULONG fx_file_total_clusters;
ULONG fx_file_first_physical_cluster;
ULONG fx_file_consecutive_cluster;
ULONG fx_file_last_physical_cluster;
ULONG fx_file_current_physical_cluster;
ULONG64 fx_file_current_logical_sector;
ULONG fx_file_current_logical_offset;
ULONG fx_file_current_relative_cluster;
ULONG fx_file_current_relative_sector;
ULONG64 fx_file_current_file_offset;
ULONG64 fx_file_current_file_size;
ULONG64 fx_file_current_available_size;
#ifdef FX_ENABLE_FAULT_TOLERANT
ULONG64 fx_file_maximum_size_used;
#endif /*FX_ENABLE_FAULT_TOLERANT */
FX_MEDIA *fx_file_media_ptr;
struct FX_FILE_STRUCT
*fx_file_opened_next,
*fx_file_opened_previous;
FX_DIR_ENTRY fx_file_dir_entry;
CHAR fx_file_name_buffer[FX_MAX_LONG_NAME_LEN];
ULONG fx_file_disable_burst_cache;
VOID (*fx_file_write_notify)(struct FX_FILE_STRUCT *);
} FX_FILE;
```

10
rtos-docs/filex/appendix-d.md Normal file
View File

@@ -0,0 +1,10 @@
---
title: Appendix D - FileX ASCII Character Codes
description: Learn about the FileX character codes in HEX by reviewing this ASCII character code chart.
---
# Appendix D - FileX ASCII character codes
## **ASCII Character Codes in HEX**
![ASCII Character Codes in HEX](./media/user-guide/ascii-character-codes-hex.png)

129
rtos-docs/filex/chapter1.md Normal file
View File

@@ -0,0 +1,129 @@
---
title: Chapter 1 - Introduction to FileX
description: FileX is a complete FAT format media and file management system for deeply embedded applications.
---
# Chapter 1 - Introduction to FileX
FileX is a complete FAT format media and file management system for deeply embedded applications. This chapter introduces FileX, describing its applications and benefits.
## FileX Unique Features
FileX supports an unlimited number of media devices at the same time, including RAM disks, FLASH managers, and actual physical devices. It supports 12-, 16-, and 32-bit File Allocation Table (FAT) formats, and also supports Extended File Allocation Table (exFAT), contiguous file allocation, and is highly optimized for both size and performance. FileX also includes fault tolerant support, media open/ close, and file write callback functions.
Designed to meet the growing need for FLASH devices, FileX uses the same design and coding methods as ThreadX. Like all Eclipse Foundation products, FileX is distributed with full ANSI C source code, and it has no run-time royalties.
### Product Highlights
- Complete ThreadX processor support
- No royalties
- Complete ANSI C source code
- Real-time performance
- Responsive technical support
- Unlimited FileX objects (media, directories, and files)
- Dynamic FileX object creation/deletion
- Flexible memory usage
- Size scales automatically
- Small footprint (as low as 6 KBytes) instruction area size: 6-30K
- Complete integration with ThreadX
- Endian neutral
- Easy-to-implement FileX I/O drivers
- 12-, 16-, and 32-bit FAT support
- exFAT support
- Long filename support
- Internal FAT entry cache
- Unicode name support
- Contiguous file allocation
- Consecutive sector and cluster read/write
- Internal logical sector cache
- RAM disk demonstration runs out-of-the-box
- Media format capability
- Error detection and recovery
- Fault tolerant options
- Built-in performance statistics
- Standalone support (No Eclipse ThreadX)
## Safety Certifications
### TÜV Certification
FileX has been certified by SGS-TÜV Saar for use in safety-critical systems, according to IEC-61508 SIL 4. The certification confirms that FileX can be used in the development of safety-related software for the highest safety integrity levels of IEC-61508 for the "Functional Safety of electrical, electronic, and programmable electronic safety-related systems." SGS-TUV Saar, formed through a joint venture of Germany's SGS-Group and TUV Saarland, has become the leading accredited, independent company for testing, auditing, verifying, and certifying embedded software for safety-related systems worldwide.
![SGS TUV Saar logo](./media/user-guide/sgs-tuv-saar-logo.png)
- IEC 61508 up to SIL 4
> **Important:** Please contact us for more information on which version(s) of FileX have been certified by TÜV or for the availability of test reports, certificates, and associated documentation.
### UL Certification
FileX has been certified by UL for compliance with UL 60730-1 Annex H, CSA E60730-1 Annex H, IEC 60730-1 Annex H, UL 60335-1 Annex R, IEC 603351 Annex R, and UL 1998 safety standards for software in programmable components. Along with IEC/UL 60730-1, which has requirements for "Controls Using Software" in its Annex H, the IEC 60335-1 standard describes the requirements for "Programmable Electronic Circuits" in its Annex R. IEC 60730 Annex H and IEC 60335-1 Annex R address the safety of MCU hardware and software used in appliances such as washing machines, dishwashers, dryers, refrigerators, freezers, and ovens.
![C RU US 2](./media/user-guide/c-ru-us-logo.png)
_UL/IEC 60730, UL/IEC 60335, UL 1998_
> **Important:** Please contact us for more information on which version(s) of FileX have been certified by UL or for the availability of test reports, certificates, and associated documentation.
## Powerful Services of FileX
### Multiple Media Management
FileX can support an unlimited number of physical media. Each media instance has its own distinct memory area and associated driver specified on the **_fx_media_open_** call. The default distribution of FileX comes with a simple RAM media driver and a demonstration system that uses this RAM disk.
### Logical Sector Cache
By reducing the number of whole sector transfers, both to and from the media, the FileX logical sector cache significantly improves performance. FileX maintains a logical sector cache for each opened media. The depth of the logical sector cache is determined by the amount of memory supplied to FileX with the **_fx_media_open_** API call.
### Contiguous File Support
FileX offers contiguous file support through the API service **_fx_file_allocate_** to improve and make file access time deterministic. This routine takes the amount of memory requested and looks for a series of adjacent clusters to satisfy the request. If such clusters are found, they are pre-allocated by making them part of the file's chain of allocated clusters. On moving physical media, the FileX contiguous file support results in a significant performance improvement and makes the access time deterministic.
### Dynamic Creation
FileX allows you to create system resources dynamically. This is especially important if your application has
multiple or dynamic configuration requirements. In addition, there are no predetermined limits on the number of FileX resources you can use (media or files). Also, the number of system objects does not have any
impact on performance.
## Easy-to-use API
FileX provides the very best deeply embedded file system technology in a manner that is easy to understand and easy to use! The FileX Application Programming Interface (API) makes the services intuitive and consistent. You won't have to decipher "alphabet soup" services that are all too common with other file systems.
For a complete list of the FileX Version 5 Services, see [Appendix A](appendix-a.md).
## exFAT Support
exFAT (extended File Allocation Table) is a file system designed by Eclipse Foundation to allow file size to exceed 2GB, a limit imposed by FAT32 file systems. It is the default file system for SD cards with capacity over 32GB. SD cards or flash drives formatted with FileX exFAT format are compatible with Windows. exFAT supports file size up to one Exabyte (EB), which is approximately one billion GB.
Users wishing to use exFAT must recompile the FileX library with the symbol **_FX_ENABLE_EXFAT_** defined. When opening media, FileX detects the media type. If the media is formatted with exFAT, FileX reads and writes the file system following exFAT standard. To format new media with exFAT, use the service **_fx_media_exFAT_format_**. By default exFAT is not enabled.
## Fault Tolerant Support
The FileX Fault Tolerant Module is designed to prevent file system corruption caused by interruptions during the file or directory update. For example, when appending data to a file, FileX needs to update the content of the file, the directory entry, and possibly the FAT entries. If this sequence of update is interrupted (such as power glitch, or the media is ejected in the middle of the update), the file system is in an inconsistent state, which may affect the integrity of the entire file system, leading towards corruption of other files.
The FileX Fault Tolerant Module works by recording all steps required to update a file or a directory along the way. This log entry is stored on the media in dedicated sectors (blocks) that FileX can find and access. The location of the log data can be accessed even without a proper file system. Therefore, in case the file system is corrupted, FileX is still able to find the log entry and restore the file system back into a good state.
As FileX updates file or directory, log entries are created. After the update operation is successfully completed, the log entries are removed. If the log entries were not properly removed after a successful file update, if the recovery process determines that the content in the log entry matches the file system, nothing needs to be done, and the log entries can be cleaned up.
In case the file system update operation was interrupted, next time the media is mounted by FileX, the Fault Tolerant Module analyzes the log entries. The information in the log entries allows FileX to back out partial changes already applied to the file system (in case the failure happens during the early stage of the file update operation), or if the log entries contain re-do information, FileX is able to apply the changes required to finish the prior operation.
This fault tolerant feature is available to all FAT file systems supported by FileX, including FAT12, FAT16, FAT32, and exFAT. By default fault tolerant is not enabled in FileX. To enable the fault tolerant feature, FileX must be built with the symbol **FX_ENABLE_FAULT_TOLERANT** and **FX_FAULT_TOLERANT** defined. At run time, the application starts fault tolerant service by calling **_fx_fault_tolerant_enable_**.
After the service starts, all file and directory write operations go through the Fault Tolerant Module.
As fault tolerant service starts, it first detects whether or not the media is protected under the Fault Tolerant Module. If it is not, FileX assumes integrity of the file system, and starts protection by allocating free blocks from the file system to be used for logging and caching. If the Fault Tolerant Module logs are found on the file system, it analyzes the log entries. FileX reverts the prior operation or redoes the prior operation, depending on the content of the log entries. The file system becomes available after all the prior log entries are processed. This ensures that FIleX starts from a known good state.
After a media is protected under the FileX Fault Tolerant Module, the media will not be updated with another file system. Doing so would leave the log entries on the file system inconsistent with the contents in the FAT table, the directory entry. If the media is updated by another file system before moving it back to FileX with the Fault Tolerant Module, the result is undefined.
## Callback Functions
The following three callback functions are added to FileX:
- Media Open callback
- Media Close callback
- File Write callback
After registered, these functions will notify the application when such events occur.
## Easy Integration
FileX is easily integrated with virtually any FLASH or media device. Porting FileX is simple. This guide describes the process in detail, and the RAM driver of the demo system makes for a very good place to start!

133
rtos-docs/filex/chapter2.md Normal file
View File

@@ -0,0 +1,133 @@
---
title: Chapter 2 - Installation and use of FileX
description: This chapter contains an introduction to FileX and a description of installation conditions, procedures, and use, including the following.
---
# Chapter 2 - Installation and use of FileX
This chapter contains an introduction to FileX and a description of installation conditions, procedures, and use.
## Host Considerations
### Computer Type
Embedded development is usually performed on Windows or Linux (Unix) host computers. After the application is compiled, linked, and located on the host, it is downloaded to the target hardware for execution.
### Download Interfaces
Usually the target download is done from within the development tool's debugger. After download, the debugger is responsible for providing target execution control (go, halt, breakpoint, etc.) as well as access to memory and processor registers.
### Debugging Tools
Most development tool debuggers communicate with the target hardware via on-chip debug (OCD) connections such as JTAG (IEEE 1149.1) and Background Debug Mode (BDM). Debuggers also communicate with target hardware through In-Circuit Emulation (ICE) connections. Both OCD and ICE connections provide robust solutions with minimal intrusion on the target resident software.
### Required Hard Disk Space
The source code for FileX is delivered in ASCII format and requires approximately 500 KBytes of space on the host computer's hard disk
## Target Considerations
FileX requires between 6 KBytes and 30 KBytes of Read-Only Memory (ROM) on the target. Another 100 bytes of the target's Random Access Memory (RAM) are required for FileX global data structures. Each opened media also requires 1.5 KBytes of RAM for the control block in addition to RAM for storing data for one sector (typically 512 bytes).
For date/time stamping to function properly, FileX relies on ThreadX timer facilities. This is implemented by creating a FileX-specific timer during FileX initialization. FileX also relies on ThreadX semaphores for multiple thread protection and I/O suspension.
## Product Distribution
FileX can be obtained from our public source code repository at <https://github.com/azure-rtos/filex/>.
The following is a list of several important files in the repository:
- ***fx_api.h*** : This C header file contains all system equates, data structures, and service prototypes.
- ***fx_port.h*** : This C header file contains all development-tool-specific data definitions and structures.
- ***demo_filex.c*** : This C file contains a small demo application.
- ***fx.a (or fx.lib)*** : This is the binary version of the FileX C library. It is distributed with the standard package.
> **Important:** *All file names are in lower-case. This naming convention makes it easier to convert the commands to Linux (Unix) development platforms.*
## FileX Installation
FileX is installed by cloning the GitHub repository to your local machine. The following is typical syntax for creating a clone of the FileX repository on your PC:
```c
git clone https://github.com/azure-rtos/filex
```
Alternatively you can download a copy of the repository using the download button on the GitHub main page.
You will also find instructions for building the FileX library on the front page of the online repository.
> **Important:** Application software needs access to the FileX library file (usually called* usually ***fx.a*** or ***fx.lib***) *and the C include files **fx_api.h** and **fx_port.h**. This is accomplished either by setting the appropriate path for the development tools or by copying these files into the application development area.
## Using FileX
Using FileX is easy. Basically, the application code must include ***fx_api.h*** during compilation and link with the FileX run-time library ***fx.a*** (or ***fx.lib***). Of course, the ThreadX files, namely ***tx_api.h*** and ***tx.a*** (or ***tx.lib***)*,* are also required.
> **Important:** When using FileX in Standalone mode (**FX_STANDALONE_ENABLE** must be defined), ThreadX files/libraries are not required.
Assuming you are already using ThreadX, there are four steps required to build a FileX application:
1. Include the ***fx_api.h*** file in all application files that use FileX services or data structures.
1. Initialize the FileX system by calling ***fx_system_initialize*** from the ***tx_application_define*** function or an application thread.
> **Important:** When using FileX in Standalone mode, ***fx_system_initialize*** should be directly called from application code.
1. Add one or more calls to ***fx_media_open*** to set up the FileX media. This call must be made from the context of an application thread.
> **Important:** *Remember that the **fx_media_open** call requires enough RAM to store data for one sector.*
1. Compile application source and link with the FileX and ThreadX run-time libraries, ***fx.a*** (or ***fx.lib***) and ***tx.a*** (or ***tx.lib***). The resulting image can be downloaded to the target and executed!
## Troubleshooting
Each FileX port is delivered with a demonstration application. It is always a good idea to get the demonstration system running first—either on the target hardware or a specific demonstration environment.
If the demonstration system does not work, try the following things to narrow the problem:
1. Determine how much of the demonstration is running.
1. Increase stack sizes (this is more important in actual application code than it is for the demonstration).
1. Ensure there is enough RAM for the 32KBytes default RAM disk size. The basic system will operate on much less RAM; however, as more of the RAM disk is used, problems will surface if there is not enough memory.
1. Temporarily bypass any recent changes to see if the problem disappears or changes.
## Configuration Options
There are several configuration options when building the FileX library and the application using FileX. The options below can be defined in the application source, on the command line, or within the ***fx_user.h*** include file.
> **Important:** *Options defined in **fx_user.h** are applied only if the application and ThreadX library are built with ***FX_INCLUDE_USER_DEFINE_FILE*** defined.*
> When using FileX in Standalone mode (**FX_STANDALONE_ENABLE** must be defined), ThreadX files/libraries are not required.
The following list describes each configuration option in detail:
|Define|Meaning|
|---------- |-----------|
|FX_MAX_LAST_NAME_LEN |This value defines the maximum file name length, which includes full path name. By default, this value is 256.|
|FX_DONT_UPDATE_OPEN_FILES |Defined, FileX does not update already opened files.|
|FX_MEDIA_DISABLE_SEARCH_CACHE |Defined, the file search cache optimization is disabled.|
|FX_MEDIA_DISABLE_SEARCH_CACHE |Defined, the file search cache optimization is disabled.|
|FX_DISABLE_DIRECT_DATA_READ_CACHE_FILL |Defined, the direct read sector update of cache is disabled.|
|FX_MEDIA_STATISTICS_DISABLE |Defined, gathering of media statistics is disabled.|
|FX_SINGLE_OPEN_LEGACY |Defined, legacy single open logic for the same file is enabled.|
|FX_RENAME_PATH_INHERIT |Defined, renaming inherits path information.|
|FX_DISABLE_ERROR_CHECKING |Removes the basic FileX error checking API and results in improved performance (as much as 30%) and smaller code size.|
|FX_MAX_LONG_NAME_LEN |Specifies the maximum file name size for FileX. The default value is 256, but this can be overridden with a command-line define. Legal values range between 13 and 256.|
|FX_MAX_SECTOR_CACHE|Specifies the maximum number of logical sectors that can be cached by FileX. The actual number of sectors that can be cached is lesser of this constant and how many sectors can fit in the amount of memory supplied at fx_media_open. The default value is 256. All values must be a power of 2.|
|FX_FAT_MAP_SIZE |Specifies the number of sectors that can be represented in the FAT update map. The default value is 256, but this can be overridden with a command-line define. Larger values help reduce unneeded updates of secondary FAT sectors.|
|FX_MAX_FAT_CACHE |Specifies the number of entries in the internal FAT cache. The default value is 16, but this can be overridden with a command-line define. All values must be a power of 2.|
|FX_FAULT_TOLERANT |When defined, FileX immediately passes write requests of all system sectors (boot, FAT, and directory sectors) to the media's driver. This potentially decreases performance, but helps limit corruption to lost clusters. Note that enabling this feature does not automatically enable FileX Fault Tolerant Module, which is enabled by defining|
|FX_FAULT_TOLERANT_DATA |When defined, FileX immediately passes all file data write requests to the media's driver. This potentially decreases performance, but helps limit lost file data. Note that enabling this feature does not automatically enable FileX Fault Tolerant Module, which is enabled by defining ***FX_ENABLE_FAULT_TOLERANT***|
|FX_NO_LOCAL_PATH|Removes local path logic from FileX, resulting in smaller code size.|
|FX_NO_TIMER|Eliminates the ThreadX timer setup to update the FileX system time and date. Doing so causes default time and date to be placed on all file operations.|
|FX_UPDATE_RATE_IN_SECONDS |Specifies rate at which system time in FileX is adjusted. By default, value is 10, specifying that the FileX system time is updated every 10 seconds.|
|FX_ENABLE_EXFAT| When defined, the logic for handling exFAT file system is enabled in FileX. By default this symbol is not defined.|
|FX_UPDATE_RATE_IN_TICKS| Specifies the same rate as ***FX_UPDATE_RATE_IN_SECONDS*** (see above), except in terms of the underlying ThreadX timer frequency. The default is 1000, which assumes a 10ms ThreadX timer rate and a 10 second interval.|
|FX_SINGLE_THREAD|Eliminates ThreadX protection logic from the FileX source. It should be used if FileX is being used only from one thread or if FileX is being used without ThreadX.|
|FX_DRIVER_USE_64BIT_LBA|When defined, enables 64-bit sector addresses used in I/O driver. By default this option is not defined.|
|FX_ENABLE_FAULT_TOLERANT| When defined, enables FileX Fault Tolerant Module. Enabling Fault Tolerant automatically defines the symbol ***FX_FAULT_TOLERANT*** and ***FX_FAULT_TOLERANT_DATA***. By default this option is not defined.|
|FX_FAULT_TOLERANT_BOOT_INDEX|Defines byte offset in the boot sector where the cluster for the fault tolerant log is. By default this value is 116. This field takes 4 bytes. Bytes 116 through 119 are chosen because they are marked as reserved by FAT 12/16/32/exFAT specification.|
|FX_FAULT_TOLERANT_MINIMAL_CLUSTER|This symbol is deprecated. It is no longer being used by FileX Fault Tolerant.|
|FX_STANDALONE_ENABLE|Defined, enables FileX to be used in standalone mode (without Eclipse ThreadX). By default this symbol is not defined.|
> **Important:** When **FX_STANDALONE_ENABLE** is defined, Local path logic and ThreadX timer setup are disabled.
## FileX Version ID
The current version of FileX is available both to the user and the application software during run-time. The programmer can obtain the FileX version from examination of the **fx_port.h** file. In addition, this file also contains a version history of the corresponding port. Application software can obtain the FileX version by examining the global string ***_fx_version_id***.

586
rtos-docs/filex/chapter3.md Normal file
View File

File diff suppressed because it is too large Load Diff

6152
rtos-docs/filex/chapter4.md Normal file
View File

File diff suppressed because it is too large Load Diff

411
rtos-docs/filex/chapter5.md Normal file
View File

@@ -0,0 +1,411 @@
---
title: Chapter 5 - I/O Drivers for FileX
description: This chapter contains a description of I/O drivers for FileX and is designed to help developers write application-specific drivers.
---
# Chapter 5 - I/O Drivers for FileX
This chapter contains a description of I/O drivers for FileX and is designed to help developers write application-specific drivers.
## I/O Driver Introduction
FileX supports multiple media devices. The FX_MEDIA structure defines everything required to manage a media device. This structure contains all media information, including the media-specific I/O driver and associated parameters for passing information and status between the driver and FileX. In most systems, there is a unique I/O driver for each FileX media instance.
## I/O Driver Entry
Each FileX I/O driver has a single entry function that is defined by the ***fx_media_open*** service call. The driver entry function has the following format:
```c
void my_driver_entry(FX_MEDIA *media_ptr);
```
FileX calls the I/O driver entry function to request all physical media access, including initialization and boot sector reading. Requests made to the driver are done sequentially; i.e., FileX waits for the current request to complete before another request is sent.
## I/O Driver Requests
Because each I/O driver has a single entry function, FileX makes specific requests through the media control block. Specifically, the **fx_media_driver_request** member of **FX_MEDIA** is used to specify the exact driver request. The I/O driver communicates the success or failure of the request through the **fx_media_driver_status** member of **FX_MEDIA**. If the driver request was successful, **FX_SUCCESS** is placed in this field before the driver returns. Otherwise, if an error is detected, FX_IO_ERROR is placed in this field.
### Driver Initialization
Although the actual driver initialization processing is application specific, it usually consists of data structure initialization and possibly some preliminary hardware initialization. This request is the first made by FileX and is done from within the fx_media_open service.
If media write protection is detected, the driver fx_media_driver_write_protect member of FX_MEDIA should be set to FX_TRUE.
The following FX_MEDIA members are used for the I/O driver initialization request:
|FX_MEDIA member|Meaning|
|-----------|-----------|
|fx_media_driver_request|FX_DRIVER_INIT|
FileX provides a mechanism to inform the application driver when sectors are no longer being used. This is especially useful for FLASH memory managers that must manage all in-use logical sectors mapped to the FLASH.
If such notification of free sectors is required, the application driver simply sets the *fx_media_driver_free_sector_update* field in the associated **FX_MEDIA** structure to **FX_TRUE**. After set, FileX makes a ***FX_DRIVER_RELEASE_SECTORS*** I/O driver call indicating when one or more consecutive sectors becomes free.
### Boot Sector Read
Instead of using a standard read request, FileX makes a specific request to read the media's boot sector. The following **FX_MEDIA** members are used for the I/O driver boot sector read request:
|FX_MEDIA member|Meaning|
|-----------|-----------|
|fx_media_driver_request| FX_DRIVER_BOOT_READ|
|fx_media_driver_buffer| Address of destination for boot sector.|
### Boot Sector Write
Instead of using a standard write request, FileX makes a specific request to write the media's boot sector. The following **FX_MEDIA** members are used for the I/O driver boot sector write request:
|FX_MEDIA member|Meaning|
|-----------|-----------|
|fx_media_driver_request| FX_DRIVER_BOOT_WRITE|
|fx_media_driver_buffer| Address of source for boot sector.|
### Sector Read
FileX reads one or more sectors into memory by issuing a read request to the I/O driver. The following **FX_MEDIA** members are used for the I/O driver read request:
|FX_MEDIA member|Meaning|
|-----------|-----------|
|fx_media_driver_request| FX_DRIVER_READ|
|fx_media_driver_logical_sector|Logical sector to read|
|fx_media_driver_sectors|Number of sectors to read|
|fx_media_driver_buffer|Destination buffer for sector(s) read|
|fx_media_driver_data_sector_read|Set to FX_TRUE if a file data sector is requested. Otherwise, FX_FALSE if a system sector (FAT or directory sector) is requested.|
|fx_media_driver_sector_type|Defines the explicit type of sector requested, as follows:<br />FX_FAT_SECTOR (2)<br />FX_DIRECTORY_SECTOR (3)<br />FX_DATA_SECTOR (4)|
### Sector Write
FileX writes one or more sectors to the physical media by issuing a write request to the I/O driver. The following FX_MEDIA members are used for the I/O driver write request:
|FX_MEDIA member| Meaning|
|-----------|-----------|
|fx_media_driver_request|FX_DRIVER_WRITE|
|fx_media_driver_logical_sector|Logical sector to write|
|fx_media_driver_sectors|Number of sectors to write|
|fx_media_driver_buffer|Source buffer for sector(s) to write|
|fx_media_driver_system_write| Set to FX_TRUE if a system sector is requested (FAT or directory sector). Otherwise, FX_FALSE if a file data sector is requested.|
|fx_media_driver_sector_type|Defines the explicit type of sector requested, as follows:<br> <br>FX_FAT_SECTOR (2) <br> FX_DIRECTORY_SECTOR (3) <br>FX_DATA_SECTOR (4).|
### Driver Flush
FileX flushes all sectors currently in the driver's sector cache to the physical media by issuing a flush request to the I/O driver. Of course, if the driver is not caching sectors, this request requires no driver processing. The following FX_MEDIA members are used for the I/O driver flush request:
|FX_MEDIA member| Meaning|
|-----------|-----------|
|fx_media_driver_request|FX_DRIVER_FLUSH|
### Driver Abort
FileX informs the driver to abort all further physical I/O activity with the physical media by issuing an abort request to the I/O driver. The driver should not perform any I/O again until it is re-initialized. The following FX_MEDIA members are used for the I/O driver abort request:
|FX_MEDIA member| Meaning|
|-----------|-----------|
|fx_media_driver_request| FX_DRIVER_ABORT|
### Release Sectors
If previously selected by the driver during initialization, FileX informs the driver whenever one or more consecutive sectors become free. If the driver is actually a FLASH manager, this information can be used to tell the FLASH manager that these sectors are no longer needed. The following **FX_MEDIA** members are used for the I/O release sectors request:
|FX_MEDIA member| Meaning|
|-----------|-----------|
|fx_media_driver_request|FX_DRIVER_RELEASE_SECTORS|
|fx_media_driver_logical_sector|Start of free sector|
|fx_media_driver_sectors|Number of free sectors|
### Driver Suspension
Because I/O with physical media may take some time, suspending the calling thread is often desirable. Of course, this assumes completion of the underlying I/O operation is interrupt driven. If so, thread suspension is easily implemented with a ThreadX semaphore. After starting the input or output operation, the I/O driver suspends on its own internal I/O semaphore (created with an initial count of zero during driver initialization). As part of the driver I/O completion interrupt processing, the same I/O semaphore is set, which in turn wakes up the suspended thread.
### Sector Translation
Because FileX views the media as linear logical sectors, I/O requests made to the I/O driver are made with logical sectors. It is the driver's responsibility to translate between logical sectors and the physical geometry of the media, which may include heads, tracks, and physical sectors. For FLASH and RAM disk media, the logical sectors typically map directory to physical sectors. In any case, here are the typical formulas to perform the logical to physical sector
mapping in the I/O driver:
```c
media_ptr -> fx_media_driver_physical_sector =
(media_ptr -> fx_media_driver_logical_sector % media_ptr -> fx_media_sectors_per_track) + 1;
media_ptr -> fx_media_driver_physical_head =
(media_ptr -> fx_media_driver_logical_sector/ media_ptr ->
fx_media_sectors_per_track) % media_ptr -> fx_media_heads;
media_ptr -> fx_media_driver_physical_track =(media_ptr ->
fx_media_driver_logical_sector/ (media_ptr -> fx_media_sectors_per_track *
media_ptr -> fx_media_heads)));
```
Note that physical sectors start at one, while logical sectors start at zero.
### Hidden Sectors
Hidden sectors resided prior to the boot record on the media. Because they are really outside the scope of the FAT file system layout, they must be accounted for in each logical sector operation the driver does.
### Media Write Protect
The FileX driver can turn on write protect by setting the fx_media_driver_write_protect field in the media control block. This will cause an error to be returned if any FileX calls are made in an attempt to write to the media.
## Sample RAM Driver
The FileX demonstration system is delivered with a small RAM disk
driver, which is defined in the file fx_ram_driver.c. The driver assumes a 32K memory space and creates a
boot record for 256 128-byte sectors. This file provides a good
example of how to implement application specific FileX I/O
drivers.
```c
/*FUNCTION: _fx_ram_driver
RELEASE: PORTABLE C 5.7
AUTHOR: William E. Lamie, Eclipse Foundation, Inc.
DESCRIPTION: This function is the entry point to the generic
RAM disk driver that is delivered with all versions of FileX.
The format of the RAM disk is easily modified by calling fx_media_format prior to opening the media.
This driver also serves as a template for developing FileX drivers
for actual devices. Simply replace the read/write sector logic
with calls to read/write from the appropriate physical device.
FileX RAM/FLASH structures look like the following:
Physical Sector Contents
0 Boot record
1 FAT Area Start
+FAT Sectors Root Directory Start
+Directory Sectors Data Sector Start
INPUT: media_ptr Media control block pointer
OUTPUT: None
CALLS: _fx_utility_memory_copy Copy sector memory
_fx_utility_16_unsigned_read Read 16-bit unsigned
CALLED BY: FileX System Functions
RELEASE HISTORY:
DATE NAME DESCRIPTION
12-12-2005 William E. Lamie Initial Version 5.0
07-18-2007 William E. Lamie Modified comment(s),
resulting in version 5.1
03-01-2009 William E. Lamie Modified comment(s),
resulting in version 5.2
11-01-2015 William E. Lamie Modified comment(s),
resulting in version 5.3
04-15-2016 William E. Lamie Modified comment(s),
resulting in version 5.4
04-03-2017 William E. Lamie Modified comment(s),
fixed compiler warnings,
resulting in version 5.5
12-01-2018 William E. Lamie Modified comment(s),
checked buffer overflow,
resulting in version 5.6
08-15-2019 William E. Lamie Modified comment(s),
resulting in version 5.7
*/
VOID _fx_ram_driver(FX_MEDIA *media_ptr) { UCHAR *source_buffer;
UCHAR *destination_buffer;
UINT bytes_per_sector;
/* There are several useful/important pieces of information contained
in the media structure, some of which are supplied by FileX and
others are for the driver to setup. The following
is a summary of the necessary FX_MEDIA structure members:
FX_MEDIA Member Meaning
fx_media_driver_request FileX request type.
Valid requests from FileX are as follows:
FX_DRIVER_READ
FX_DRIVER_WRITE
FX_DRIVER_FLUSH
FX_DRIVER_ABORT
FX_DRIVER_INIT
FX_DRIVER_BOOT_READ
FX_DRIVER_RELEASE_SECTORS
FX_DRIVER_BOOT_WRITE FX_DRIVER_UNINIT
fx_media_driver_status This value is RETURNED by the driver.
If the operation is successful, this field should be set to FX_SUCCESS
for before returning. Otherwise, if an error occurred, this field should be set to FX_IO_ERROR.
fx_media_driver_buffer Pointer to buffer to read or write sector data. This is supplied by FileX.
fx_media_driver_logical_sector Logical sector FileX is requesting.
fx_media_driver_sectors Number of sectors FileX is requesting.
The following is a summary of the optional FX_MEDIA structure members: FX_MEDIA Member Meaning
fx_media_driver_info Pointer to any additional information or memory.
This is optional for the driver use and is setup from the fx_media_open call.
The RAM disk uses this pointer for the RAM disk memory itself.
fx_media_driver_write_protect The DRIVER sets this to FX_TRUE when media is write protected.
This is typically done in initialization, but can be done anytime.
fx_media_driver_free_sector_update The DRIVER sets this to FX_TRUE when it needs
to know when clusters are released. This is important for FLASH wear-leveling drivers.
fx_media_driver_system_write FileX sets this flag to FX_TRUE if the sector
being written is a system sector, e.g., a boot, FAT, or directory sector.
The driver may choose to use this to initiate error recovery logic for greater fault
tolerance. fx_media_driver_data_sector_read FileX sets this flag to FX_TRUE
if the sector(s) being read are file data sectors, i.e., NOT system sectors.
fx_media_driver_sector_type FileX sets this variable to the specific type of
sector being read or written. The following sector types are identified:
FX_UNKNOWN_SECTOR
FX_BOOT_SECTOR
FX_FAT_SECTOR
FX_DIRECTORY_SECTOR
FX_DATA_SECTOR */
/* Process the driver request specified in the media control block. */
switch (media_ptr -> fx_media_driver_request){
case FX_DRIVER_READ: {
/* Calculate the RAM disk sector offset. Note the RAM disk memory
is pointed to by the fx_media_driver_info pointer, which is supplied
by the application in the call to fx_media_open. */
source_buffer = ((UCHAR *)media_ptr -> fx_media_driver_info) +
((media_ptr -> fx_media_driver_logical_sector +
media_ptr -> fx_media_hidden_sectors) * media_ptr -> fx_media_bytes_per_sector);
/* Copy the RAM sector into the destination. */
_fx_utility_memory_copy(source_buffer,
media_ptr -> fx_media_driver_buffer, media_ptr -> fx_media_driver_sectors *
media_ptr -> fx_media_bytes_per_sector);
/* Successful driver request. */
media_ptr -> fx_media_driver_status = FX_SUCCESS; break; }
case FX_DRIVER_WRITE: {
/* Calculate the RAM disk sector offset. Note the RAM disk memory
is pointed to by the fx_media_driver_info pointer, which is supplied
by the application in the call to fx_media_open. */
destination_buffer = ((UCHAR *)media_ptr -> fx_media_driver_info) +
((media_ptr -> fx_media_driver_logical_sector +
media_ptr -> fx_media_hidden_sectors) * media_ptr -> fx_media_bytes_per_sector);
/* Copy the source to the RAM sector. */
_fx_utility_memory_copy(media_ptr -> fx_media_driver_buffer,
destination_buffer, media_ptr -> fx_media_driver_sectors *
media_ptr -> fx_media_bytes_per_sector);
/* Successful driver request. */
media_ptr -> fx_media_driver_status = FX_SUCCESS; break; }
case FX_DRIVER_FLUSH: {
/* Return driver success. */
media_ptr -> fx_media_driver_status = FX_SUCCESS; break; }
case FX_DRIVER_ABORT: {
/* Return driver success. */
media_ptr -> fx_media_driver_status = FX_SUCCESS; break; }
case FX_DRIVER_INIT: {
/* FLASH drivers are responsible for setting several fields
in the media structure, as follows:
media_ptr -> fx_media_driver_free_sector_update media_ptr ->
fx_media_driver_write_protect
The fx_media_driver_free_sector_update flag is used to instruct
FileX to inform the driver whenever sectors are not being used.
This is especially useful for FLASH managers so they don't have
maintain mapping for sectors no longer in use.
The fx_media_driver_write_protect flag can be set anytime by
the driver to indicate the media is not writable. Write attempts
made when this flag is set are returned as errors. */
/* Perform basic initialization here... since the boot record is going
to be read subsequently and again for volume name requests. */
/* Successful driver request. */
media_ptr -> fx_media_driver_status = FX_SUCCESS; break; }
case FX_DRIVER_UNINIT: {
/* There is nothing to do in this case for the RAM driver.
For actual devices some shutdown processing may be necessary. */
/* Successful driver request. */
media_ptr -> fx_media_driver_status = FX_SUCCESS; break; }
case FX_DRIVER_BOOT_READ: {
/* Read the boot record and return to the caller. */
/* Calculate the RAM disk boot sector offset, which is at the
very beginning of the RAM disk. Note the RAM disk memory is pointed
to by the fx_media_driver_info pointer, which is supplied by the
application in the call to fx_media_open. */
source_buffer = (UCHAR *)media_ptr -> fx_media_driver_info;
/* For RAM driver, determine if the boot record is valid. */
if ((source_buffer[0] != (UCHAR)0xEB) ||
((source_buffer[1] != (UCHAR)0x34) &&
(source_buffer[1] != (UCHAR)0x76)) || /* exFAT jump code. */
(source_buffer[2] != (UCHAR)0x90)) {
/* Invalid boot record, return an error! */
media_ptr -> fx_media_driver_status = FX_MEDIA_INVALID; return; }
/* For RAM disk only, pickup the bytes per sector. */
bytes_per_sector =
_fx_utility_16_unsigned_read(&source_buffer[FX_BYTES_SECTOR]); #ifdef FX_ENABLE_EXFAT
/* if byte per sector is zero, then treat it as exFAT volume. */
if (bytes_per_sector == 0 && (source_buffer[1] == (UCHAR)0x76)) {
/* Pickup the byte per sector shift, and calculate byte per sector. */
bytes_per_sector = (UINT)(1 << source_buffer[FX_EF_BYTE_PER_SECTOR_SHIFT]);
}
#endif /* FX_ENABLE_EXFAT */
/* Ensure this is less than the media memory size. */
if (bytes_per_sector \media_ptr -> fx_media_memory_size) {
media_ptr -> fx_media_driver_status = FX_BUFFER_ERROR; break; }
/* Copy the RAM boot sector into the destination. */
_fx_utility_memory_copy(source_buffer, media_ptr -> fx_media_driver_buffer, bytes_per_sector);
/* Successful driver request. */
media_ptr -> fx_media_driver_status = FX_SUCCESS; break; }
case FX_DRIVER_BOOT_WRITE: {
/* Write the boot record and return to the caller. */
/* Calculate the RAM disk boot sector offset, which is at the
very beginning of the RAM disk. Note the RAM disk memory is
pointed to by the fx_media_driver_info pointer, which is supplied
by the application in the call to fx_media_open. */
destination_buffer = (UCHAR *)media_ptr -> fx_media_driver_info;
/* Copy the RAM boot sector into the destination. */
_fx_utility_memory_copy(media_ptr -> fx_media_driver_buffer,
destination_buffer, media_ptr -> fx_media_bytes_per_sector);
/* Successful driver request. */
media_ptr -> fx_media_driver_status = FX_SUCCESS; break; }
default: {
/* Invalid driver request. */
media_ptr -> fx_media_driver_status = FX_IO_ERROR; break;}
}
}
```

123
rtos-docs/filex/chapter6.md Normal file
View File

@@ -0,0 +1,123 @@
---
title: Chapter 6 - FileX fault tolerant module
description: This chapter contains a description of the FileX Fault Tolerant Module that is designed to maintain file system integrity if the media loses power or is ejected in the middle of a file write operation.
---
# Chapter 6 - FileX fault tolerant module
This chapter contains a description of the FileX Fault Tolerant Module that is designed to maintain file system integrity if the media loses power or is ejected in the middle of a file write operation.
## FileX Fault Tolerant Module Overview
When an application writes data into a file, FileX updates both data clusters and system information. These updates must be completed as an atomic operation to keep information in the file system coherent. For example, when appending data to a file, FileX needs to find an available cluster in the media, update the FAT chain, update the length filed in the directory entry, and possibly update the starting cluster number in the directory entry. Either a power failure or media ejection can interrupt the sequence of updates, which will leave the file system in an inconsistent state. If the inconsistent state is not corrected, the data being updated can be lost, and because of damage to the system information, subsequent file system operation may damage other files or directories on the media.
The FileX Fault Tolerant Module works by journaling steps required to update a file *before* these steps are applied to the file system. If the file update is successful, these log entries are removed. However, if the file update is interrupted, the log entries are stored on the media. Next time the media is mounted, FileX detects these log entries from the previous (unfinished) write operation. In such cases, FileX can recover from a failure by either rolling back the changes already made to the file system, or by reapplying the required changes to complete the previous operation. In this way, the FileX Fault Tolerant Module maintains file system integrity if the media loses power during an update operation.
> **Important:** *The FileX Fault Tolerant Module is not designed to prevent file system corruption caused by physical media corruption with valid data in it.*
> **Important:** *After the FileX Fault Tolerant module protects a media, the media must not be mounted by anything other than FileX with Fault Tolerant enabled. Doing so can cause the log entries in the file system to be inconsistent with system information on the media. If the FileX Fault Tolerant module attempts to process log entries after the media is updated by another file system, the recovery procedure may fail, leaving the entire file system in an unpredictable state.*
## Use of the Fault Tolerant Module
The FileX Fault Tolerant feature is available to all FAT file systems supported by FileX, including FAT12, FAT16, FAT32, and exFAT. To enable the fault tolerant feature, FileX must be built with the symbol **FX_ENABLE_FAULT_TOLERANT** defined. At run time, application starts fault tolerant service by calling ***fx_fault_tolerant_enable*** immediately after the call to ***fx_media_open***. After fault tolerant is enabled, all file write operations to the designated media are protected. By default the fault tolerant module is not enabled.
> **Important:** *Application needs to make sure the file system is not being accessed prior to ***fx_fault_tolerant_enable*** being called. If application writes data to the file system prior to fault tolerant enable, the write operation could corrupt the media if prior write operations were not completed, and the file system was not restored using fault tolerant log entries.*
## FileX Fault Tolerant Module Log
The FileX fault tolerant log takes up one logical cluster in flash. The index to the starting cluster number of that cluster is recorded in the boot sector of the media, with an offset specified by the symbol **FX_FAULT_TOLERANT_BOOT_INDEX**. By default this symbol is defined to be 116. This location is chosen because it is marked as reserved in FAT12/ 16/32 and exFAT specification.
Figure 5, "Log Structure Layout," shows the general layout of the log structure. The log structure contains three sections: Log Header, FAT Chain, and Log Entries.
> **Important:** *All multi-byte values stored in the log entries are in Little Endian format.*
![Log Structure Layout](./media/user-guide/log-structure-layout.png)
**Figure 5. Log Structure Layout**
The Log Header area contains information that describes the entire log structure and explains each field in detail.
**TABLE 8. Log Header Area**
|Field|Size(in bytes)|Description|
|-----|--------------|-----------|
|ID|4|Identifies a FileX Fault Tolerant Log structure. The log structure is considered invalid if the ID value is not 0x46544C52.|
|Total Size|2|Indicates the total size (in bytes) of the entire log structure.|
|Header Checksum|2|Checksum that converts the log header area. The log structure is considered invalid if the header fields fail the checksum verification.|
|Version Number|2|FileX Fault Tolerant major and minor version numbers.|
|Reserved|2|For future expansion.|
The Log Header area is followed by the FAT Chain Log area. Figure 9 contains information that describes how the FAT chain should be modified. This log area contains information on the clusters being allocated to a file, the clusters being removed from a file, and where the insertion/deletion should be and describes each field in the FAT Chain Log area.
**TABLE 9. FAT Chain Log Area**
|Field|Size(in bytes)|Description|
|-----|--------------|-----------|
|FAT Chain Log Checksum|2|Checksum of the entire FAT Chain Log area. The FAT Chain Log area is considered invalid if the it fails the checksum verification.|
|Flag|1|Valid flag values are:<br/>0x01 FAT Chain Valid<br />0x02 BITMAP is being used|
|Reserved|1|Reserved for future use|
|Insertion Point – Front|4|The cluster (that belongs to the original FAT chain) where the newly created chain is going to be attached to.|
|Head Cluster of New FAT Chain|4|The first cluster of the newly created FAT Chain|
|Head Cluster of Original FAT Chain|4|The first cluster of the portion of the original FAT Chain that is to be removed.|
|Insertion Point – Back|4|The original cluster where the newly created FAT chain joins at.|
|Next Deletion Point|4|This field assists the FAT chain cleanup procedure.|
The Log Entries Area contains log entries that describe the changes needed to recover from a failure. There are three types of log entry supported in the FileX fault tolerant module: FAT Log Entry; Directory Log Entry; and Bitmap Log Entry.
The following three figures and three tables describe these log entries in detail.
![FAT Log Entry](./media/user-guide/fat-log-entry.png)
**Figure 6. FAT Log Entry**
**TABLE 10. FAT Log Entry**
|Field|Size(in bytes)|Description|
|-----|--------------|-----------|
Type|2|Type of Entry, must be FX_FAULT_TOLERANT_FAT_LOG_TYPE|
|Size|2|Size of this entry|
|Cluster Number|4|Cluster number|
|Value|4|Value to be written into the FAT entry|
![Directory Log Entry](./media/user-guide/directory-log-entry.png)
**Figure 7. Directory Log Entry**
**TABLE 11. Directory Log Entry**
|Field|Size(in bytes)|Description|
|-----|--------------|-----------|
|Type|2|Type of Entry, must be FX_FAULT_TOLERANT_DIRECTORY_LOG_TYPE|
|Size|2|Size of this entry|
|Sector Offset|4|Offset (in bytes) into the sector where this directory is located.|
|Log Sector|4|The sector where the directory entry is located|
|Log Data|Variable|Content of the directory entry|
![Bitmap Log Entry](./media/user-guide/bitmap-log-entry.png)
**Figure 8. Bitmap Log Entry**
**TABLE 12. Bitmap Log Entry**
|Field|Size(in bytes)|Description|
|-----|--------------|-----------|
|Type|2|Type of Entry, must be FX_FAULT_TOLERANT_BITMAP_LOG_TYPE|
|Size|2|Size of this entry|
|Cluster Number|4|Cluster number|
|Value|4|Value to be written into the FAT entry|
## Fault Tolerant Protection
After the FileX Fault Tolerant Module starts, it first searches for an existing fault tolerant log file in the media. If a valid log file cannot be found, FileX considers the media unprotected. In this case FileX will create a fault tolerant log file on the media.
> **Important:** *FileX is not able to protect a file system if it was corrupted before the FileX Fault Tolerant Module starts.*
If a fault tolerant log file is located, FileX checks for existing log entries. A log file with no log entry indicates prior file operation was successful, and all log entries were removed. In this case the application can start using the file system with fault tolerant protection.
However if log entries are located, FileX needs to either complete the prior file operation, or revert the changes already applied to the file system, effectively undo the changes. In either case, after the log entries are applied to the file system, the file system is restored into a coherent state, and application can start using the file system again.
For media protected by FileX, during file update operation, the data portion is written directly to the media. As FileX writes data, it also records any changes needed to be applied to directory entries, FAT table. This information is recorded in the file tolerant log entries. This approach guarantees that updates to the file system occur after the data is written to the media. If the media is ejected during the data-write phase, crucial file system information has not been changed yet. Therefore the file system is not affected by the interruption.
After all the data is successfully written to the media, FileX then follows information in the log entries to applies the changes to system information, one entry at a time. After all the system information is committed to the media, the log entries are removed from the fault tolerant log. At this point, FileX completes the file update operation.
During file update operation, files are not updated in place. The fault tolerant module allocates a sector for the data to write the new data into, and then remove the sector that contains the data to be overwritten, updating related FAT entries to link the new sector into the chian. For situations in which partial data in a cluster needs to be modified, FileX always allocates new clusters, writes the entire data from the old clusters with updated data into the new clusters, then frees up the old clusters. This guarantees that if the file update is interrupted, the original file is intact. The application needs to be aware that under FileX fault tolerant protection, updating data in a file requires the media to have enough free space to hold new data before sectors with old data can be released. If the media doesn't have enough space to hold new data, the update operation fails.

28
rtos-docs/filex/index.md Normal file
View File

@@ -0,0 +1,28 @@
# FileX documentation
[Overview of FileX](overview-filex.md)
FileX user guide
- [About this guide](about-this-guide.md)
- [Ch. 1 - Introduction to FileX](chapter1.md)
- [Ch. 2 - Installation and use of FileX](chapter2.md)
- [Ch. 3 - Functional components of FileX](chapter3.md)
- [Ch. 4 - Description of FileX services](chapter4.md)
- [Ch. 5 - I/O drivers for FileX](chapter5.md)
- [Ch. 6 - FileX fault tolerant module](chapter6.md)
- [App. A - FileX services](appendix-a.md)
- [App. B - FileX constants](appendix-b.md)
- [App. C - FileX data types](appendix-c.md)
- [App. D - ASCII character codes](appendix-d.md)
[FileX repository](https://github.com/azure-rtos/filex)
[Eclipse ThreadX components](../../README.md)
- [ThreadX](../threadx/index.md)
- [ThreadX Modules](../threadx-modules/index.md)
- [NetX Duo](../netx-duo/index.md)
- [GUIX](../guix/index.md)
- [FileX](../filex/index.md)
- [LevelX](../levelx/index.md)
- [USBX](../usbx/index.md)
- [TraceX](../tracex/index.md)

BIN
rtos-docs/filex/media/overview-filex/cru-logo-certification.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

BIN
rtos-docs/filex/media/overview-filex/partener-logo-c-ru-us-2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 45 KiB

BIN
rtos-docs/filex/media/overview-filex/partener-logo-sgs-tuv-saar-2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 110 KiB

BIN
rtos-docs/filex/media/overview-filex/source-code-1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

BIN
rtos-docs/filex/media/user-guide/10ms-increment-fields.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
rtos-docs/filex/media/user-guide/ascii-character-codes-hex.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 79 KiB

BIN
rtos-docs/filex/media/user-guide/bitmap-log-entry.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.8 KiB

BIN
rtos-docs/filex/media/user-guide/c-ru-us-logo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.3 KiB

BIN
rtos-docs/filex/media/user-guide/directory-log-entry.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

BIN
rtos-docs/filex/media/user-guide/exfat-logical-sectors.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

BIN
rtos-docs/filex/media/user-guide/fat-16-file-example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

BIN
rtos-docs/filex/media/user-guide/fat-log-entry.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.8 KiB

BIN
rtos-docs/filex/media/user-guide/filex-media-logical-sector-view.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 46 KiB

BIN
rtos-docs/filex/media/user-guide/log-structure-layout.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

BIN
rtos-docs/filex/media/user-guide/sgs-tuv-saar-logo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
rtos-docs/filex/media/user-guide/system-information.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 59 KiB

BIN
rtos-docs/filex/media/user-guide/utc-offset-field.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.5 KiB

88
rtos-docs/filex/overview-filex.md Normal file
View File

@@ -0,0 +1,88 @@
---
title: Understand FileX
description: FileX is a high-performance, file allocation table (FAT)-compatible file system that's fully integrated with ThreadX and available for all supported processors. Like ThreadX, FileX is designed to have a small footprint and high performance, making it ideal for today's deeply embedded applications that require file management operations. FileX supports most physical media, including RAM, USBX, SD CARD, and NAND/NOR flash memories via LevelX.
---
# Overview of FileX
FileX embedded file system is Eclipse ThreadX's advanced, industrial grade solution for Eclipse Foundation FAT file formats, designed specifically for deeply embedded, real-time, and IoT applications. FileX supports all of Eclipse Foundation's file formats, including FAT12, FAT16, FAT32, and exFAT. FileX also offers optional fault tolerance and FLASH wear leveling via an add-on product called [LevelX](../levelx/index.md). All of this combined with a small footprint, fast execution, and superior ease-of-use, make FileX the ideal choice for the most demanding embedded IoT applications.
## API protocols
### Media Services
- FAT 12/16/32 and exFAT support
- Minimal 6KB FLASH, 2.5KB RAM
- Complete media access services
- Unlimited number of media instance
- Simple read/write logical sector driver interface
- Multiple partition support
- Logical sector cache
- FAT entry cache
- Optional fault tolerance support
- Deferred Secondary FAT update
- System-level Trace via TraceX
- Intuitive media access APIs, including:
- fx_media_open
- fx_media_close
- fx_media_format
- fx_media_space_available
### Directory Services
- Up to 256 byte paths
- Long and 8.3 directory names supported
- Directory create & delete
- Directory navigation and traversal
- Directory attributes management
- System-level Trace via TraceX
- Intuitive directory access APIs, including:
- fx_directory_create
- fx_directory_delete
- fx_directory_attributes_set
- fx_directory_attributes_read
- fx_directory_first_entry_find
- fx_directory_next_entry_find
### File Services
- Minimal 3.3KB FLASH
- Unlimited open files
- Read-only files can be opened multiple times
- Long and 8.3 directory names supported
- Contiguous file support
- Fast seek logic
- Pre-allocation of clusters
- File create, delete, and rename
- File read, write, and see
- File attributes management
- System-level Trace via TraceX
- Intuitive file access APIs, including:
- fx_file_create
- fx_file_delete
- fx_file_attributes_set
- fx_file_attributes_read
- fx_file_read
- fx_file_seek
- fx_file_write
## Advanced technology
FileX is advanced technology, including the following.
- FAT 12/16/32 and exFAT support
- Multiple partition support
- Automatic scaling
- Endian neutral
- Long file name and 8.3 support
- Optional fault tolerance support
- Logical sector cache
- FAT entry cache
- Pre-allocation of clusters
- Contiguous file support
- Optional performance metrics
- TraceX system analysis support
## NOR/NAND Wear Leveling (LevelX)
LevelX is Eclipse Foundation's NOR/NAND FLASH wear leveling product. LevelX can be used in conjunction with FileX or as a stand-alone, direct read/write FLASH sector library for the application.

48
rtos-docs/general/lts.md Normal file
View File

@@ -0,0 +1,48 @@
---
title: Product Support Policy
description: Eclipse ThreadX Product Support Policy.
---
# Product Support Policy
This document applies for Eclipse ThreadX components including ThreadX, NetX Duo, FileX, GUIX, USBX and LevelX.
## Version definitions
Eclipse ThreadX releases generally follow the guidelines defined by [Semantic Versioning](https://semver.org/). Given an Eclipse ThreadX version number **X.Y.Z** (e.g. 6.1.9):
* **X** increases for a **milestone release**. Currently Eclipse ThreadX components stay at version **6**.
* **Y** increases for a **feature release** when there is a major feature added (e.g. v6.**1**.0 introduced Eclipse ThreadX IoT Middleware).
* **Z** increases for a every three month **regular updates** or **patch** for critical bug fixes.
## Roadmap
Last updated: **2021/11**
![Roadmap 2021](./media/roadmap.png)
## Support policy
Eclipse ThreadX provides 60 months support for each milestone release (e.g. v6.x.x) and 24 months for each feature release (e.g. v6.1.x). The **Maintenance** or so called **LTS (Long-term-support)** period starts right after a new feature release is published. Eclipse ThreadX version 6.0.0 and all future releases will follow this support policy.
The entire life cycle of a certain feature release (e.g. v6.1.x) can be broken down into **Service** and **Maintenance** periods:
| **Period** | **Duration** | **Definition** |
| --- | --- | --- |
| Service | Subject to the actual development plan | New features and regular bug fixes |
| Maintenance (LTS) | 24 months after next feature release published | Critical and security bug fixes |
### Example
* Eclipse ThreadX v6.1.0 was released in 2020/10, it will be actively in development with bug fixes for the regular update version (e.g. v6.1.11 released in 2022/04).
* Users are always welcomed to update to the latest version during the Service period.
* When Eclipse ThreadX v6.2.0 is released. The latest v6.1.x will get into the Maintenance (LTS) period. We will keep backporting important bug fixes from v6.2.x to it. Until 24 months later, which v6.1.x will come to End Of Life.
The actual duration of each feature release may varies depending on the actual development plan. Please view the [Roadmap](#roadmap) section above for the recent feature release versions.
### Other notes
* Users are recommended starting a new project using release in Service period.
* Users are encouraged to upgrade all projects to a newer Eclipse ThreadX release before the support period finishes.
* For particular cases users cannot upgrade the projects, security / critical bug fixes can be applied to it with communication with Eclipse Foundation.
* Pre-release version (public preview, pre-release and etc.,) or feature marked as "Preview" are not covered by any support period.
* For prior releases to v6. The support is covered by ExpressLogic support contract.

BIN
rtos-docs/general/media/roadmap.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 70 KiB

20
rtos-docs/general/security-updates.md Normal file
View File

@@ -0,0 +1,20 @@
---
title: Security Updates
description: Eclipse ThreadX Security Updates.
---
# Security Updates
This table lists all [Common Vulnerabilities and Exposures (CVE)](https://cve.mitre.org/) and status for fixes in Eclipse ThreadX components.
For all security vulnerabilities, you can find the published list on the corresponding Eclipse ThreadX component repository.
| Release Date | CVE | Severity | Eclipse ThreadX Component | Affected Versions | Patched Versions
| - | - | - | - | - | - |
| 5/19/2022 | [CVE-2022-29246](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-29246) | High | USBX | < 6.1.11 | 6.1.11 |
| 5/17/2022 | [CVE-2022-29223](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-29223) | High | USBX | < 6.1.10 | 6.1.10 |
| 11/9/2021 | [CVE-2021-42323](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-42323) | High | USBX | < 6.1.9 | 6.1.9 |
| 11/9/2021 | [CVE-2021-42304](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-42304) | High | USBX | < 6.1.9 | 6.1.9 |
| 11/9/2021 | [CVE-2021-42303](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-42303) | High | USBX | < 6.1.9 | 6.1.9 |
| 11/9/2021 | [CVE-2021-42302](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-42302) | High | USBX | < 6.1.9 | 6.1.9 |
| 11/9/2021 | [CVE-2021-42301](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-42301) | High | USBX | < 6.1.9 | 6.1.9 |
| 11/9/2021 | [CVE-2021-26444](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-26444) | High | USBX | < 6.1.9 | 6.1.9 |

23
rtos-docs/guix/about-guix-studio.md Normal file
View File

@@ -0,0 +1,23 @@
---
title: GUIX Studio User Guide
description: This guide provides comprehensive information about GUIX Studio, the Microsoft Windows-based rapid UI development environment specifically designed for the GUIX runtime library from Eclipse Foundation.
---
# About This GUIX Studio User Guide
This guide provides comprehensive information about GUIX Studio, the Microsoft Windows-based rapid UI development environment specifically designed for the GUIX runtime library from Eclipse Foundation.
It is intended for the embedded real-time software developer using the ThreadX Real-Time Operating System (RTOS) and the GUIX UI run-time library. The developer should be familiar with standard ThreadX and GUIX concepts.
## Organization
- [**Chapter 1**](guix-studio-1.md) provides a basic overview of GUIX Studio and its relationship to real-time development.
- [**Chapter 2**](guix-studio-2.md) gives the basic steps to install and use GUIX Studio to analyze your application right out of the box.
- [**Chapter 3**](guix-studio-3.md) describes the main features of GUIX Studio.
- [**Chapter 4**](guix-studio-4.md) describes how to use GUIX Studio to create and manage your application resources.
- [**Chapter 5**](guix-studio-5.md) describes how to use the GUIX WYSIWYG screen designer.
- [**Chapter 6**](guix-studio-6.md) describes how your application will utilize the output files and API functions generated by GUIX Studio.
- [**Chapter 7**](guix-studio-7.md) describes how to configure screen flow
- [**Chapter 8**](guix-studio-8.md) describes the usage of command line tool
- [**Chapter 9**](guix-studio-9.md) describes a simple but complete UI application created by GUIX Studio.
- [**Chapter 10**](guix-studio-10.md) describes how to create an example project in GUIX Studio and execute the example on GUIX.
- [**Chapter 11**](guix-studio-11.md) describes the resource project file and its usage.

106
rtos-docs/guix/about-guix.md Normal file
View File

@@ -0,0 +1,106 @@
---
title: GUIX User Guide
description: This guide contains comprehensive information about GUIX, the high-performance GUI product from Eclipse Foundation.
---
# About GUIX User Guide
This guide contains comprehensive information about GUIX, the high-performance GUI product from Eclipse Foundation. It is intended for embedded real-time software developers familiar with basic GUI concepts, ThreadX, and the C programming language.
## Organization
[Chapter 1 - Introduction to GUIX](chapter-1.md)
[Chapter 2 - Installation and use of GUIX](chapter-2.md)
[Chapter 3 - Functional Overview of GUIX](chapter-3.md)
[Chapter 4 - Description of GUIX Services](chapter-4.md)
[Chapter 5 - GUIX Display Drivers](chapter-5.md)
[GUIX Example](guix-example.md)
[Appendix A - GUIX Color Definitions](appendix-a.md)
[Appendix B - GUIX Color Formats](appendix-b.md)
[Appendix C - GUIX Widget Styles](appendix-c.md)
[Appendix D - GUIX Brush, Canvas and Gradient Attributes](appendix-d.md)
[Appendix E - GUIX Event Description](appendix-e.md)
[Appendix F - GUIX RTOS Binding Services](appendix-f.md)
[Appendix G - GUIX Font Structure](appendix-g.md)
[Appendix H - GUIX Build-Time Configuration flags](appendix-h.md)
[Appendix I - GUIX Information Structures](appendix-i.md)
[Appendix J - Canvas Partial Frame Buffer Feature](appendix-j.md)
## Guide Conventions
*Italics* - Typeface denotes book titles, emphasizes important words, and indicates variables.
**Boldface** - Typeface denotes file names, key words, and further emphasizes important words and variables.
> **Important:** Information symbols draw attention to important or additional information that could affect performance or function.
## GUIX Data Types
In addition to the custom GUIX control structure data types, there are several special data types that are used in GUIX service call interfaces. These special data types map directly to data types of the underlying C compiler. This is done to ensure portability between different C compilers. The exact implementation is inherited from ThreadX and can be found in the ***tx_port.h*** file included in the ThreadX distribution.
The following is a list of GUIX service call data types and their associated meanings:
| Data type | Description |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **UINT** | Basic unsigned integer. This type is mapped to the most convenient unsigned data type. |
| **INT** | Basic signed integer. This type is mapped to the most convenient signed data type. |
| **ULONG** | Unsigned long type. This type must support 32-bit unsigned data. |
| **VOID** | Almost always equivalent to the compiler's void type. |
| **GX_CHAR** | Most often typedefed as the compiler defined char type. |
| **GX_BYTE** | 8-bit signed type. |
| **GX_UBYTE** | 8-bit unsigned type. |
| **GX_VALUE** | 16 or 32 bit signed type. Defined as needed for best performance on the target system. |
| **GX_FIXED_VAL** | Fixed point numeric data type. |
| **GX_RESOURCE_ID** | Unsigned long type. |
| **GX_COLOR** | Unsigned long type. |
| **GX_STRING** | Structure containing GX_CHAR \*gx_string_ptr and UINT gx_string_length. |
| **GX_POINT** | Structure containing gx_point_x and gx_point_y. |
| **GX_RECTANGLE** | Structure containing gx_rectangle_left, gx_rectangle_top, gx_rectangle_right, and gx_rectangle_bottom fields. |
| **GX_GLYPH** | Structure containing glyph metrics. |
| **GX_FONT** | Structure containing font metrics. |
| **GX_BRUSH** | Structure containing brush metrics. |
**GX_PIXELMAP** | Structure containing pixelmap metrics.
Additional data types are used within the GUIX source. They are located in either the ***tx_port.h*** or ***gx_port.h*** files.
## Troubleshooting
For troubleshooting, capture the following information:
1. A detailed description of the problem, including frequency of occurrence and whether it can be reliably reproduced.
2. A detailed description of any changes to the application and/or GUIX that preceded the problem.
3. The contents of the _tx_version_id and _gx_version_id strings found in the ***tx_port.h*** and ***gx_port.h*** files of your distribution. These strings will provide valuable Information regarding your run-time environment.
4. The contents in RAM of the following ULONG variables:
**_tx_build_options**
**_gx_system_build_options**
These variables will give information on how your ThreadX and GUIX libraries were built.
5. The contents in RAM of the following ULONG variables:
**_gx_system_last_error**
**_gx_system_error_count**
These variables keep track of internal system errors in GUIX. If the _gx_system_error_count is greater than one, please set a breakpoint on the function return in the _gx_system_error_process function and find the value of _gx_system_last_error at this point. This will yield the first internal GUIX system error.
6. A trace buffer captured immediately after the problem was detected. This is accomplished by building the ThreadX and GUIX libraries with TX_ENABLE_EVENT_TRACE and calling tx_trace_enable with the trace buffer information.
7. The GUIX Studio project you are using, if applicable, or at a minimum a small project sufficient to demonstrate the deficiency.

61
rtos-docs/guix/appendix-a.md Normal file
View File

@@ -0,0 +1,61 @@
---
title: Appendix A - GUIX Color Definitions
description: Learn about the GUIX color definitions.
---
# Appendix A - GUIX Color Definitions
__**Pre-defined color values**__
| Color | Value |
| -------------------------------- | --------------- |
| GX_COLOR_BLACK | 0xff000000 |
| GX_COLOR_RED | 0xffb80000 |
| GX_COLOR_GREEN | 0xff00bc00 |
| GX_COLOR_BROWN | 0xffb8bc00 |
| GX_COLOR_BLUE | 0xff0000b8 |
| GX_COLOR_MAGENTA | 0xffb800b8 |
| GX_COLOR_CYAN | 0xff00bcb8 |
| GX_COLOR_LIGHTGRAY | 0xffc0c0c0 |
| GX_COLOR_DARKGRAY | 0xff808080 |
| GX_COLOR_LIGHTRED | 0xffff0000 |
| GX_COLOR_LIGHTGREEN | 0xff00ff00 |
| GX_COLOR_YELLOW | 0xffffff00 |
| GX_COLOR_LIGHTBLUE | 0xff0000ff |
| GX_COLOR_LIGHTMAGENTA | 0xffff00ff |
| GX_COLOR_LIGHTCYAN | 0xff00ffff |
| GX_COLOR_WHITE | 0xffffffff |
__**Pre-defined color IDs**__
| Color | Value |
|---------------------------------- | ---- |
| GX_COLOR_ID_CANVAS | 0 |
| GX_COLOR_ID_WIDGET_FILL | 1 |
| GX_COLOR_ID_WINDOW_FILL | 2 |
| GX_COLOR_ID_DEFAULT_BORDER | 3 |
| GX_COLOR_ID_WINDOW_BORDER | 4 |
| GX_COLOR_ID_TEXT | 5 |
| GX_COLOR_ID_SELECTED_TEXT | 6 |
| GX_COLOR_ID_SELECTED_FILL | 7 |
| GX_COLOR_ID_SHADOW | 8 |
| GX_COLOR_ID_SHINE | 9 |
| GX_COLOR_ID_BUTTON_BORDER | 10 |
| GX_COLOR_ID_BUTTON_UPPER | 11 |
| GX_COLOR_ID_BUTTON_LOWER | 12 |
| GX_COLOR_ID_BUTTON_TEXT | 13 |
| GX_COLOR_ID_SCROLL_FILL | 14 |
| GX_COLOR_ID_SCROLL_BUTTON | 15 |
| GX_COLOR_ID_TEXT_INPUT_TEXT | 16 |
| GX_COLOR_ID_TEXT_INPUT_FILL | 17 |
| GX_COLOR_ID_SLIDER_TICK | 18 |
| GX_COLOR_ID_SLIDER_GROOVE_TOP | 19 |
| GX_COLOR_ID_SLIDER_GROOVE_BOTTOM | 20 |
| GX_COLOR_ID_SLIDER_NEEDLE_OUTLINE | 21 |
| GX_COLOR_ID_SLIDER_NEEDLE_FILL | 22 |
| GX_COLOR_ID_SLIDER_NEEDLE_LINE1 | 23 |
| GX_COLOR_ID_SLIDER_NEEDLE_LINE2 | 24 |
| GX_COLOR_ID_DISABLED_TEXT | 25 |
| GX_COLOR_ID_DISABLED_FILL | 26 |
| GX_COLOR_ID_READONLY_TEXT | 27 |
| GX_COLOR_ID_READONLY_FILL | 28 |

34
rtos-docs/guix/appendix-b.md Normal file
View File

@@ -0,0 +1,34 @@
---
title: Appendix B - GUIX Color Formats
description: Learn about the GUIX color formats.
---
# Appendix B - GUIX Color Formats
| Color | Value |
|------------------------------------ | ----- |
| GX_COLOR_FORMAT_MONOCHROME | 1 |
| GX_COLOR_FORMAT_MONOCHROME_INVERTED | 2 |
| GX_COLOR_FORMAT_2BIT_4GRAY | 3 |
| GX_COLOR_FORMAT_2BIT_GRAY_INVERTED | 4 |
| GX_COLOR_FORMAT_4BIT_GRAY | 5 |
| GX_COLOR_FORMAT_4BIT_GRAY_INVERTED | 6 |
| GX_COLOR_FORMAT_4BIT_VGA | 7 |
| GX_COLOR_FORMAT_8BIT_GRAY | 8 |
| GX_COLOR_FORMAT_8BIT_GRAY_INVERTED | 9 |
| GX_COLOR_FORMAT_8BIT_PALETTE | 10 |
| GX_COLOR_FORMAT_8BIT_PACKED_PIXEL | 11 |
| GX_COLOR_FORMAT_15BIT_BGR | 12 |
| GX_COLOR_FORMAT_15BIT_RGB | 13 |
| GX_COLOR_FORMAT_16BIT_RGB | 14 |
| GX_COLOR_FORMAT_16BIT_ARGB | 15 |
| GX_COLOR_FORMAT_16BIT_BGRA | 16 |
| GX_COLOR_FORMAT_16BIT_BGR | 17 |
| GX_COLOR_FORMAT_24BIT_RGB | 18 |
| GX_COLOR_FORMAT_24BIT_BGR | 19 |
| GX_COLOR_FORMAT_24BIT_XRGB | 20 |
| GX_COLOR_FORMAT_24BIT_BGRX | 21 |
| GX_COLOR_FORMAT_32BIT_ARGB | 22 |
| GX_COLOR_FORMAT_32BIT_RGBA | 23 |
| GX_COLOR_FORMAT_32BIT_ABGR | 24 |
| GX_COLOR_FORMAT_32BIT_BGRA | 25 |

262
rtos-docs/guix/appendix-c.md Normal file
View File

@@ -0,0 +1,262 @@
---
title: Appendix C - GUIX Widget Styles
description: Learn about the GUIX widget styles.
---
# Appendix C - GUIX Widget Styles
__***General Styles (Used with most widget types):***__
**GX_STYLE_BORDER_NONE**
- Value: 0x00000000
- Description: Use this style to draw a widget with no border.
**GX_STYLE_BORDER_RAISED**
- Value: 0x00000001
- Description: Draw widget with a raised border.
**GX_STYLE_BORDER_RECESSED**
- Value: 0x00000002
- Description: Draw widget with a recessed border.
**GX_STYLE_BORDER_THIN**
- Value: 0x00000004
- Description: Draw a one-pixel width border.
**GX_STYLE_BORDER_THICK**
- Value: 0x00000008
- Description: Draw widget with a thick border.
**GX_STYLE_BORDER_MASK**
- Value: 0x0000000f
- Description: Mask value used to test only the style fields of the widget style member.
**GX_STYLE_TRANSPARENT**
- Value: 0x10000000
- Description: Create a widget that is at least partially transparent. This style should be used when a widget does not draw itself fully opaque, including widgets that draw a semi-transparent pixelmap as the widget background. This style flag informs GUIX that the widget parent must be drawn to refresh the widget background area.
**GX_STYLE_DRAW_SELECTED**
- Value: 0x20000000
- Description: Specify that the widget should be drawn using selected state colors and fonts. Different widget types use the DRAW_SELECTED style in different ways to indicate the widget is
currently selected.
**GX_STYLE_ENABLED**
- Value: 0x40000000
- Description: Mark the widget as enabled, which allows the widget to accept user input events and generate output signals.
**GX_STYLE_DYNAMICALLY_ALLOCATED**
- Value: 0x80000000
- Description: Indicates the widget control block memory is dynamically allocated using the gx_system_memory_allocator service when the widget is created, and the control block memory is freed if the widget is destroyed.
**GX_STYLE_USE_LOCAL_ALPHA**
- Value: 0x01000000
- Description: Instructs GUIX drawing functions to use the local widget alpha value when drawing the widget. This flag is normally used by the internal GUIX logic to implement widget fading
animations.
__***Text Alignment Styles (styles applied to all widgets that draw text):***__
**GX_STYLE_TEXT_LEFT**
- Value: 0x00001000
- Description: Text is drawn left-aligned within the widget client area.
**GX_STYLE_TEXT_RIGHT**
- Value: 0x00002000
- Description: Text is drawn right-aligned within the widget client
area.
**GX_STYLE_TEXT_CENTER**
- Value: 0x00004000
- Description: Text is drawn center-aligned within the widget client area.
**GX_STYLE_TEXT_COPY**
- Value: 0x00008000
- Description: By default, widgets that draw text keep only a pointer to the text which is passed in by the application. For statically defined text that is defined within the string table, there is no reason for the widget to make a private copy of the text assigned. However, if the text assigned to a widget is created dynamically using functions like sprint() or gx_utility_ltoa, then it is often convenient to tell the widget to keep it's own private copy of any text assigned. This allows the application to use automatic or temporary variables when defining the text string, when the application would otherwise be required to define statically defined character arrays for each text widget that is using dynamically defined text. When this style flag is set, the widget will use the gx_system_memory_allocator function to dynamically allocate the memory block needed to hold a private copy of the assigned string. Therefore using this style flag is predicated on the application defining memory_allocator and memory_deallocator functions. GX_STYLE_TEXT_COPY should not be cleared after it has been set, and doing so will cause unpredictable results.
__***Button Styles (apply only to GUIX button widget types):***__
**GX_STYLE_BUTTON_PUSHED**
- Value 0x00000010
- Description: Indicates the button is in the pushed or selected state.
**GX_STYLE_BUTTON_TOGGLE**
- Value 0x00000020
- Description: Button will switch status between pushed and unpushed on every click event. This style is commonly used with "checkbox" style buttons.
**GX_STYLE_BUTTON_RADIO**
- Value 0x00000040
- Description: This style indicates the button will be exclusive, and deselect any button siblings when selected. This style is commonly used with "radio button" style buttons.
**GX_STYLE_BUTTON_EVENT_ON_PUSH**
- Value: 0x00000080
- Description: Indicates the button generates a click event when initially pushed. The default operation is to generate a click event when the button is released.
**GX_STYLE_BUTTON_REPEAT**
- Value 0x00000100
- Description: Indicates the button should send repeated click events to the button parent when the button is held in the pushed state.
__***List Styles (apply only to GUIX list widget types):***__
**GX_STYLE_CENTER_SELECTED**
- Value: 0x00000010
- Description: Reserved
**GX_STYLE_WRAP**
- Value 0x00000020
- Description: The list children wrap from start to end when the list is dragged or scrolled past the starting or ending list index.
**GX_STYLE_FLICKABLE**
- Value: 0x00000040
- Description: Reserved
__***Pixelmap Button and Icon Button Styles:***__
**GX_STYLE_HALIGN_CENTER**
- Value: 0x00010000
- Description: The button pixelmap should be center aligned within the button boundary on the horizontal axis.
**GX_STYLE_HALIGN_LEFT**
- Value: 0x00020000
- Description: The button pixelmap should be left aligned within the button boundary on the horizontal axis.
**GX_STYLE_HALIGN_RIGHT**
- Value 0x00040000
- Description: The button pixelmap should be right aligned within the button boundary on the horizontal axis.
**GX_STYLE_VALIGN_CENTER**
- Value 0x00080000
- Description: The button pixelmap should be center aligned within the button boundary on the vertical axis.
**GX_STYLE_VALIGN_TOP**
- Value: 0x00100000
- Description: The button pixelmap should be top aligned within the button boundary on the vertical axis.
**GX_STYLE_VALIGN_BOTTOM**
- Value: 0x00200000
- Description: The button pixelmap should be bottom aligned within the button boundary on the vertical horizontal axis.
__***Slider Styles (Apply only to GX_SLIDER and derived widget types):***__
**GX_STYLE_SHOW_NEEDLE**
- Value: 0x00000200
- Description: This style must be included for the slider to draw the needle indicator. This style can be disabled if the application wants to disable the slider needle or draw a custom needle indicator.
**GX_STYLE_SHOW_TICKMARKS**
- Value: 0x00000400
- Description: The slider widget will do software drawing of dashed tickmark lines when this style is enabled.
**GX_STYLE_SLIDER_VERTICAL**
- Value 0x00000800
- Description: Set this style flag to create a vertical slider, and clear this style flag to create a horizontal slider.
__***Sprite Styles (Applies only to GX_SPRITE widget types):***__
**GX_STYLE_SPRITE_AUTO**
- Value: 0x00000010
- Description: Indicates the sprite animation will run automatically when the sprite widget received the GX_EVENT_SHOW event.
**GX_STYLE_SPRITE_LOOP**
- Value: 0x00000020
- Description: With this style, the sprite widget will continuously loop through sprite animation frames until the sprite is stopped by the application.
__***Pixelmap Slider Styles:***__
**GX_STYLE_TILE_BACKGROUND**
- Value 0x00001000
- Description: The slider background image is tiled to fill the sprite bounding rectangle. This allows a small vertical or horizontal stripe image to be used to fill the slider background.
__***Additional Progress Bar Styles:***__
**GX_STYLE_PROGRESS_PERCENT**
- Value: 0x00000010
- Description: When this style is set, the progress bar will draw bar value as a percentage rather than a raw value. The text is centered in the progress bar bounding rectangle.
**GX_STYLE_PROGRESS_TEXT_DRAW**
- Value: 0x00000020
- Description: Draw the current progress bar value as decimal text centered within the progress bar.
**GX_STYLE_PROGRESS_VERTICAL**
- Value: 0x0000040
- Description: Indicate the progress is vertically oriented. The default is horizontal orientation.
**GX_STYLE_PROGRESS_SEGMENT_FILL**:
- **Value**: 0x00000100
- Description: The progress bar value is indicated with segmented filled rectangles, rather than a solid fill.
__***Additional Radial Progress Bar Styles:***__
**GX_STYLE_RADIAL_PROGRESS_ALIAS**
- Value: 0x00000200
- Description: Draw the radial progress bar using anti-aliased brush styles. This requires more CPU bandwidth but also produces a nicer appearance. For lower performance CPU targets, clearing this style flag will result in faster drawing speed.
**GX_STYLE_RADIAL_PROGRESS_ROUND**
- Value: 0x00000400
- Description: Use a round line end brush style when drawing the radial progress bar arc. The default is a square line end.
__***Additional Text Input Styles:***__
**GX_STYLE_ CURSOR_BLINK**
- Value: 0x00000040
- Description: The text input widget cursor will flash on and off rather than being steady.
**GX_STYLE_ CURSOR_ALWAYS**
- Value: 0x00000080
- Description. The text input widget cursor is normally only displayed when the widget owns input focus. This style flag will make the cursor always visible regardless of input focus.
**GX_STYLE_TEXT_INPUT_NOTIFY_ALL**
- Value: 0x00000100
- Description: With this style flag set the GX_EVENT_TEXT_EDITED event every time key down event is received by the text input widget.
__***Additional Window Styles:***__
**GX_STYLE_TILE_WALLPAPER**
- Value: 0x00040000
- Description: The window will tile any assigned wallpaper image to fill the window client rectangle.
**GX_STYLE_AUTO_HSCROLL**
- Value: 0x00100000
- Description: Reserved for future use.
**GX_STYLE_AUTO_VSCROLL**
- Value: 0x00200000
- Description: Reserved for future use.
__***Additional Menu Styles:***__
**GX_STYLE_MENU_EXPANDED**
- Value: 0x00000010
- Description: Accordion menu widget is initially in expanded state.
__***Additional Tree View Styles:***__
**GX_STYLE_TREE_VIEW_SHOW_ROOT_LINES**
- Value: 0x00000010
- Description: Tree view widget should draw lines from node icon to root tree node.
__***Additional Scrollbar Styles:***__
**GX_SCROLLBAR_BACKGROUND_TILE**
- Value: 0x00010000
- Description: Reserved for future use.
**GX_SCROLLBAR_RELATIVE_THUMB**
- Value: 0x00020000
- Description: The scrollbar thumb width (for a horizontal scroll bar) or height (for a vertical scroll bar) are calculated based on the ratio of the visible area of the parent window to the min and max scrollbar range.
**GX_SCROLLBAR_END_BUTTONS**
- Value: 0x00040000
- Description: The scrollbar automatically creates and attaches buttons at each end of the scrollbar region.
**GX_SCROLLBAR_VERTICAL**
- Value: 0x01000000
- Description: The scrollbar is vertically oriented.
**GX_SCROLLBAR_HORIZONTAL**
- Value: 0x02000000
- Description: The scrollbar is horizontally oriented.
__***Text Scroll Wheel Styles:***__
**GX_STYLE_TEXT_SCROLL_WHEEL_ROUND**
- Value: 0x00000200
- Description: The scroll wheel uses a Sinusoidal algorithm to make the scroll wheel appear to have a rounded shape. This style flag can add significant overhead to the performance of the scroll wheel widget, but can also give the wheel a 3D realistic appearance.

68
rtos-docs/guix/appendix-d.md Normal file
View File

@@ -0,0 +1,68 @@
---
title: Appendix D - GUIX Brush, Canvas and Gradient Attributes
description: Learn about the GUIX brush, canvas and gradient attributes.
---
# Appendix D - GUIX Brush, Canvas and Gradient Attributes
__**Brush Styles:**__
**GX_BRUSH_OUTLINE**
- Value: 0x0000
- Description: This brush style applies to shape drawing functions such as gx_canvas_rectangle_draw or gx_canvas_polygon_draw. This style indicates the shape should be outlined, in addition to optionally being filled. If the GX_BRUSH_OUTLINE style is set and the GX_BRUSH_SOLID_FILL is cleared, the shape is only outlined.
**GX_BRUSH_SOLID_FILL**
- Value: 0x0001
- Description: This brush style applies to shape drawing functions, and indicates that the requested shape should be filled with a solid color using the current brush fill color.
**GX_BRUSH_PIXELMAP_FILL**
- Value: 0x0002
- Description: This brush style applies to shape drawing functions, and indicates that the requested shape should be pattern filled with the current brush pixelmap.
**GX_BRUSH_ALIAS**
- Value: 0x0004
- Description: This brush style applies to all line drawing and shape outlines. If this flag is set, lines and outlines are drawing with the more accurate but also more time consuming anti-aliased drawing algorithms. This style flag is only used for 16-bpp color depths and higher.
**GX_BRUSH_UNDERLINE**
- Value: 0x0008
- Description: This flag applies to text drawing, and indicates that subsequent text drawn should be underlined.
**GX_BRUSH_ROUND**
- Value: 0x0010
- Description: This flag applies to line drawing, and indicates that line ends are drawn with a round or circular shape, rather than the default square shape.
__**Canvas Flags:**__
**GX_CANVAS_SIMPLE**
- Value: 0x01
- Description: A memory canvas which is used to off-screen drawing.
**GX_CANVAS_MANAGED**
- Value: 0x02
- Description: A canvas which automatically flushed to the active display, either as part of the composite building process or as part of the buffer toggle operation for single-canvas architectures.
**GX_CANVAS_VISIBLE**
- Value: 0x04
- Description: This flag can be used to turn on and off a canvas, without losing the canvas drawing contents.
**GX_CANVAS_MODIFIED**
- Value: 0x08
- Description: Reserved for future use.
**GX_CANVAS_COMPOSITE**
- Value: 0x20
- Description: This flag is used by the application when configuring a multiple-canvas system which will composite multiple managed canvases into the composite canvas, and the composite is the driven to the hardware frame buffer.
__**Gradient Types:**__
**GX_GRADIENT_TYPE_VERTICAL**
- Value: 0x01
- Description: Creates a vertical alphamap gradient.
**GX_GRADIENT_TYPE_ALPHA**
- Value: 0x02
- Description: Creates an alpha-map style gradient. This is currently the only gradient style supported.
**GX_GRADIENT_TYPE_MIRROR**
- Value: 0x04
- Description: This flag indicates that the gradient should peak at the center of the width/height range, and return to the starting value as it reaches the right/bottom edge. Without this style flag, the gradient will be a linear gradient from top-to-bottom or left-to-right, depending on the GX_GRADIENT_TYPE_VERTICAL flag.

254
rtos-docs/guix/appendix-e.md Normal file
View File

@@ -0,0 +1,254 @@
---
title: Appendix E - GUIX Event Description
description: Learn about the GUIX event description.
---
# Appendix E - GUIX Event Description
```c
GX_EVENT_TERMINATE
- Description: This event can be sent by the application to intentionally terminate the GUIX execution thread. This event will also cause a modally executing window to terminate modal execution and return GX_EVENT_TERMINATE. This event is used internally by the GUIX Win32 binding to terminate the GUIX application when the desktop window is closed.
- Payload: None
GX_EVENT_REDRAW
- Description: This event can be generated to force GUIX to redraw every root window (and all child windows/widgets. This event marks every root window as dirty, forcing a complete system redraw when the next canvas refresh operation occurs. This event is also used internally for desktop operation to force a GUIX canvas refresh when the desktop operating system requests a re-draw.
- Payload: None
GX_EVENT_SHOW
- Description: This event is internally generated whenever a widget is made visible, either by being attached to a visible widget or by invocation of the gx_widget_show() API. The event is received before the widget is drawn.
- Payload: None
GX_EVENT_HIDE
- Description: This event is internally generated whenever a widget is made hidden either by being detached from its parent or through invocation of the gx_widget_hide() API. The event is received before the widget is made hidden.
- Payload: None.
GX_EVENT_RESIZED
- Description: This event is generated when a widget is resized via the gx_widget_resize API. The event is only generated if the widget gx_widget_status member includes GX_STATUS_RESIZE_NOTIFY.
- Payload: None.
GX_EVENT_SLIDE
- Description: Reserved for future use.
- Payload: None.
GX_EVENT_FOCUS_GAINED
- Description: This event is internally generated when a widget receives input focus.
- Payload: None.
GX_EVENT_FOCUS_LOST
- Description: This event is internally generated when a widget loses input focus.
- Payload: None.
GX_EVENT_HORIZONTAL_SCROLL
- Description: This event is generated by a horizontal scrollbar to inform the parent window of a scrolling operation. The event can also be generated by the application to force a window to scroll it's child widgets.
- Payload: gx_event_intdata[0] contains the current scrollbar value.
gx_event_intdata[1] contains the previous scrollbar value.
GX_EVENT_VERTICAL_SCROLL
- Description: This event is generated by a vertical scrollbar to inform the parent window of a scrolling operation. The event can also be generated by the application to force a window to scroll it's child widgets.
- Payload: gx_event_intdata[0] contains the current scrollbar value.
gx_event_intdata[1] contains the previous scrollbar value.
GX_EVENT_TIMER
- Description: This event is sent to a timer owner to notify the owner of timer expiration.
- Payload: gx_event_timer_id contains the user-assigned timer id.
sgx_event_target contains a pointer to the timer owner.
GX_EVENT_PEN_DOWN
- Description: This event is generated by touch screen and mouse input drivers to indicate user pen-down (or left mouse button click) event.
- Payload: gx_event_pointdata.gx_point_x = pen x position in pixels
gx_event_pointdata.gx_point_y = pen y position in pixels
gx_event_display_handle = handle of the target display
GX_EVENT_PEN_UP
- Description: This event is generated by touch screen and mouse input drivers to indicate user pen-up (or left mouse button released) event.
- Payload: gx_event_pointdata.gx_point_x = pen x position in pixels
gx_event_pointdata.gx_point_y = pen y position in pixels
gx_event_display_handle = handle of the target display
GX_EVENT_PEN_MOVE
- Description: This event is generated by mouse input driver to indicate the mouse has been moved to a new location, but no buttons are pressed.
- Payload: gx_event_pointdata.gx_point_x = pen x position in pixels
gx_event_pointdata.gx_point_y = pen y position in pixels
gx_event_display_handle = handle of the target display
GX_EVENT_PEN_DRAG
- Description: This event is generated by mouse and touch input drivers to indicate the pen is being dragged across the screen, or the mouse is being moved while the left mouse button is pressed.
- Payload: gx_event_pointdata.gx_point_x = pen x position in pixels
gx_event_pointdata.gx_point_y = pen y position in pixels
gx_event_display_handle = handle of the target display
GX_EVENT_KEY_DOWN:
- Description: This event is generated by keyboard input drivers to indicate a keyboard key has been pressed.
- Payload: gx_event_ushortdata[0] holds the Unicode key value.
GX_EVENT_KEY_UP
- Description: This event is generated by keyboard input drivers to indicate a keyboard key has been released.
- Payload: gx_event_ushortdata[0] holds the Unicode key value.
GX_EVENT_CLOSE
- Description: This event can be sent to any GX_WINDOW derived widget to cause that window to detach from it's parent (i.e. become hidden). If the window is executing modally, it will exit the modal execution loop and return GX_EVENT_CLOSE.
- Payload: None.
GX_EVENT_DELETE
- Description: This event is sent to any widget when the _gx_widget_delete API is used. This event informs the widget that it is about to be deleted, allowing the widget to do an necessary cleanup or memory release
- Payload: gx_event_target points to the widget being deleted.
GX_EVENT_SLIDER_VALUE
- Description: This is a GX_SIGNAL event type generated by GX_SLIDER based child controls. It informs the slider parent that the slider has been manipulated by the user.
- Payload: gx_event_longdata holds the new slider value.
gx_event_sender holds the ID of the slider widget.
GX_EVENT_TOGGLE_ON
- Description: This is a GX_SIGNAL event type generated by checkbox style (i.e. toggle style) GX_BUTTON widgets. It informs the button parent that the checkbox has been changed to the checked state.
- Payload: gx_event_sender holds the ID of the button widget.
GX_EVENT_TOGGLE_OFF
- Description: This is a GX_SIGNAL event type generated by checkbox style (i.e. toggle style) GX_BUTTON widgets. It informs the button parent that the checkbox has been changed to the unchecked state.
- Payload: gx_event_sender holds the ID of the button widget.
GX_EVENT_RADIO_SELECT
- Description: This is a GX_SIGNAL event type generated by radio button style (i.e. exclusive style) GX_BUTTON widgets. It informs the button parent that the radio button has been changed to the on state.
- Payload: gx_event_sender holds the ID of the button widget.
GX_EVENT_RADIO_DESELECT
- Description: This is a GX_SIGNAL event type generated by radio button style (i.e. exclusive style) GX_BUTTON widgets. It informs the button parent that the radio button has been changed to the off state.
- Payload: gx_event_sender holds the ID of the button widget.
GX_EVENT_CLICKED
- Description: This is a GX_SIGNAL event type generated by all enabled widget types. This event informs the widget parent that the user has clicked on the child widget.
- Payload: gx_event_sender holds the ID of the widget.
GX_EVENT_LIST_SELECT
- Description: This is a GX_SIGNAL event type generated by all horizontal list, vertical list, scroll wheel, and drop-list style child widgets. This event informs the widget parent that the user has selected a new list entry.
- Payload: gx_event_sender holds the ID of the widget.
gx_event_longdata holds the new list selection index.
GX_EVENT_VERTICAL_FLICK
- Description: This event is generated internally when the pen is dragged and released while moving in a vertical direction. gx_scroll_wheel and gx_vertical_list widgets catch this event to implement animated flicking of the list.
- Payload: gx_event_intdata[0] holds the pen speed.
GX_EVENT_HORIZONTAL_FLICK
- Description: This event is generated internally when the pen is dragged and released while moving in a horizontal direction. gx_horizontal_list widgets catch this event to implement animated
flicking of the list.
- Payload: gx_event_intdata[0] holds the pen speed.
GX_EVENT_PARENT_SIZED
- Description: This event is generated internally when any GX_WINDOW derived widget type is resized using gx_widget_resize(). This allows child widgets like scroll bars to resize themselves as need to fit within the new parent window dimensions.
- Payload: None
GX_EVENT_CLOSE_POPUP
- Description: This event is used internally to close the popup list that is owned by a drop down list widget
- Payload: None
GX_EVENT_ZOOM_IN
- Description: This event is generated by multi-touch touch input drivers to indicate a zoom-in gesture has been input by the user.
- Payload: None
GX_EVENT_ZOOM_OUT
- Description: This event is generated by multi-touch touch input drivers to indicate a zoom-out gesture has been input by the user. ]
- Payload: None
GX_EVENT_LANGUAGE_CHANGE
- Description: This event is generated and delivered to all visible widgets when the active language is changed by calling gx_display_active_langauge_set(). This allows text based widgets to retrieve the new string associated with the active language.
- Payload: None
GX_EVENT_RESOURCE_CHANGE
- Description: This event is generated and delivered to all visible widgets when the active theme is changed. This allows widgets using pixelmap and font resources to mark themselves dirty and redraw using the new theme.
- Payload: None
GX_EVENT_ANIMATION_COMPLETE
- Description: This event is generated when an animation being executed by the gx_animation_manager is completed
- Payload: gx_event_target is set to the animation_parent
gx_event_sender holds the animation id
GX_EVENT_SPRITE_COMPLETE
- Description: This GX_SIGNAL event is generated by gx_sprite widgets when the sprite animation sequence is completed.
- Payload: gx_event_sender holds the sprite widget id
GX_EVENT_TEXT_EDITED
- Description: This GX_SIGNAL event is generated by single line and multi line text input widgets when the text string is edited by the user.
- Payload: gx_event_sender holds the text input widget id
GX_EVENT_FOCUS_NEXT
- Description: This event can be generated by the application or by input driver(s) to move the widget input focus to the next widget in the widget focus list. When a gx_window type widget is made
visible, it automatically creates a linked list of child widgets that accept input focus. This event can be used to move focus from one child widget to the next.
- Payload: None.
GX_EVENT_FOCUS_PREVIOUS
- Description: This event can be generated by the application or by input driver(s) to move the widget input focus to the previous widget in the widget focus list. When a gx_window type widget is made visible, it automatically creates a linked list of child widgets that accept input focus. This event can be used to move focus from one child widget to the previous widget.
- Payload: None.
GX_EVENT_FOCUS_GAIN_NOTIFY
- Description: This GX_SIGNAL style event can be generated by a child widgets when they gain input focus. In order for a child widget to generate this signal, the child widget must have a non-zero ID and it must have the GX_STATUS_NOTIFY_ON_GAIN_FOCUS status flag set.
- Payload: gx_event_sender holds the child widget ID.
GX_EVENT_SELECT
- Description: This event can be generated by the application to place a button in the selected or pushed state.
- Payload: None.
GX_EVENT_DESELECT
- Description: This event can be generated by the application to place a button in the non selected or not pushed state.
- Payload: None.
GX_EVENT_PROGRESS_VALUE
- Description: This is a GX_SIGNAL type event generated by progress_bar type widgets when the progress bar value is changed.
- Payload: gx_event_longdata holds the new progress bar value.
GX_EVENT_TOUCH_CALIBRATION_COMPLETE
- Description: This event is sent by the generic resistive touch screen input driver when the touch screen calibration sequence is completed. This notifies the application that the normal screen display can begin or resume after a calibration sequence has been performed.
- Payload: None.
GX_EVENT_INPUT_RELEASE
- Description: This event is a command telling any widget that has captured the user input (touch, keypad) to release it. This command event is used by the screen drag animation event handler to force child widgets to release an input capture, but can also be generated by the application.
- Payload: None.
GX_EVENT_TREE_SELECT
- Description: This event is generated by gx_tree_view widgets when a tree node is selected by the user.
- Payload: gx_event_sender contains the tree widget ID.
gx_event_longdata holds the ID of the selected tree node.
GX_EVENT_STYLE_CHANGED
- Description: This event is generated when a widget style is changed using gx_widget_style_add() or gx_widget_style_remove() APIs. This allows the target widget to redraw if required by the style change.
- Payload: gx_event_ulongdata holds the previous widget style flags.
gx_event_target points at the modified widget.
GX_EVENT_CLIENT_UPDATED
- Description: This event is generated when the client area of a window is modified by the addition or removal of non-client children, such as the addition or removal of a scroll bar.
- Payload: None.
GX_EVENT_CUT
- Description: This event is generated by input device drivers to command a text input widget to cut the selected text to the GUIX clipboard.
- Payload: None.
GX_EVENT_COPY
- Description: This event is generated by input device drivers to command a text input widget to copy the selected text to the GUIX clipboard.
- Payload: None.
GX_EVENT_PASTE
- Description: This event is generated by input device drivers to command a text input widget to paste the selected text to the GUIX clipboard.
- Payload: None.
GX_EVENT_MARK_NEXT
- Description: This event is generated by input device drivers to command a text input widget to mark the next character in the input string.
- Payload: None.
GX_EVENT_MARK_PREVIOUS
- Description: This event is generated by input device drivers to command a text input widget to mark the previous character in the input string.
- Payload: None.
GX_EVENT_MARK_UP
- Description: This event is generated by input device drivers to command a text input widget to mark the previous row of characters in the input string.
- Payload: None.
GX_EVENT_MARK_DOWN
- Description: This event is generated by input device drivers to command a text input widget to mark the following row of characters in the input string.
- Payload: None.
GX_EVENT_MARK_END
- Description: This event is generated by input device drivers to command a text input widget to move the end marker to the end of the input string.
- Payload: None.
GX_EVENT_MARK_HOME
- Description: This event is generated by input device drivers to command a text input widget to move the start marker to the beginning of the input string.
- Payload: None.
```

81
rtos-docs/guix/appendix-f.md Normal file
View File

@@ -0,0 +1,81 @@
---
title: Appendix F - GUIX RTOS Binding Services
description: Learn about GUIX RTOS binding services.
---
# Appendix F - GUIX RTOS Binding Services
GUIX requires thread or tasking services, mutex, event queue, and timing services providing by the underlying RTOS. By default GUIX is configured to utilize the ThreadX real time operating system to provide these services. To port GUIX to another operating system, the developer should # define the pre-processor directive GX_DISABLE_THREADX_BINDING and rebuild the GUIX library to remove the ThreadX dependencies. In addition, the developer will need to provide the following macro
definitions and supporting functions. Examples of these macro definitions and supporting functions can be found in the files gx_system_rtos_bind.h and gx_system_rtos_bind.c, which provide an
example generic rtos integration.
System Integration macros:
**GX_RTOS_BINDING_INITIALIZE**
This macro is invoked during system initialization. The macro should be defined to call any function needed to prepare your rtos system services or rtos resources prior to use. This is the binding's opportunity to prepare the rtos resources that GUIX will use.
**GX_SYSTEM_THREAD_START**
This macro is invoked when the GUIX task or thread should start executing. This macro should be defined to call a function which will start the GUIX thread running. The entry point to the GUIX thread is passed to the called function. The signature of the called function must be
**UINT *function_name*(VOID (thread_entry_point)(VOID));**
This function should return GX_SUCCESS if the thread is successfully started, or GX_FAILURE.
**GX_EVENT_PUSH**
This macro is invoked to push an event into the FIFO event queue used by GUIX. When porting to a new rtos, it is your responsibility to implement this event queue in a thread-safe manner. GX_EVENT structures must be copied into this queue and copied out of this queue, i.e. a queue of GX_EVENT pointers will not work, since GUIX events can be automatic variables from the view of the event producer. The signature of the function called by this macro must be:
**UINT *function_name* (GX_EVENT *event_ptr);**
This function should return GX_SUCCESS if the event is pushed into the event queue, otherwise it should return GX_FAILURE.
**GX_EVENT_POP**
This macro is invoked to remove the head (oldest) event from the GUIX event queue and copy it into the requested location. This function must be able to optionally block or wait for an event if no events are currently in the event queue. The signature of the function invoked by this macro must be
UINT function_name(GX_EVENT *put_event, GX_BOOL wait)
If the wait parameter == GX_TRUE, the function should not return until an event is provided. If the wait parameter is GX_FALSE, the function should return immediately with or without an event.
If an event is retrieved from the queue, it should copied into the put_event location and the return status is GX_SUCCESS. Otherwise the return status should be GX_FAILURE.
**GX_EVENT_FOLD**
This macro is invoked by GUIX to fold an event into the FIFO event queue. Folding an event means that if an event of the same type already exists in the queue, that entry is update to contain the payload of the new event. If an existing event of the same type is not found in the queue, a new event is pushed into the queue.
For bindings that cannot implement the event fold feature, it is acceptable to simply invoke the GX_EVENT_PUSH.
**GX_TIMER_START**
This macro is invoked when GUIX needs to receive periodic timer input. This macro should invoke a service that starts the low-level RTOS periodic timer service. If the RTOS timer service cannot be easily stopped and started, it is acceptable but less efficient to leave this service running at all times.
When the low-level RTOS timer service periodically expires, the binding must call the GUIX system function _gx_system_timer_expiration(0); Calling this function periodically is what drives the high-level GUIX timer widget timer services.
**GX_TIMER_STOP**
This macro is invoked when GUIX no longer needs a periodic timer (i.e. there are no active GUIX timers running). If the RTOS timer service cannot be easily stopped and started, it is acceptable but less efficient to leave this service running at all times and define this
macro to do nothing.
**GX_SYSTEM_MUTEX_LOCK**
This macro is invoked by GUIX during critical code sections to prevent another task from pre-empting and modifying common data structures, potentially causing corruption. This macro should call a function that implements the suitable RTOS resource locking service.
If you never utilize any GUIX API services outside of the GUIX thread, you can define this macro to do nothing.
**GX_SYSTEM_MUTEX_UNLOCK**
This macro is invoked at the end of critical code sections, and should unlock the GUIX resource using the suitable underlying RTOS service. If you never utilize any GUIX API services outside of the GUIX thread, you can define this macro to do nothing.
**GX_SYSTEM_TIME_GET**
This macro should call a function that returns the current system time is "system ticks", which is usually the number of low-level timer interrupts that have occurred since system startup. This service is used to calculate touch event pen speed for touch input gestures. The signature of the function invoked by this macro must be:
**ULONG *function_name*(VOID);**
**GX_CURRENT_THREAD**
This macro is invoked to identify the currently executing thread. The service called by this macro must return a void *, meaning that the data type used by your operating system to identify the current execution thread must be cast to a void * to be returned to GUIX.
A complete example of a generic RTOS binding is implemented in the files gx_system_rtos_bind.h and gx_system_rtos_bind.c

71
rtos-docs/guix/appendix-g.md Normal file
View File

@@ -0,0 +1,71 @@
---
title: Appendix G - GUIX Font Structure
description: Learn about the GUIX font structure.
---
# Appendix G - GUIX Font Structure
GUIX fonts are normally produced by the GUIX Studio application, and font glyphs are rendered by the GUIX display driver. The application software need only specify the font and colors that each text display widget should use. The GUIX font data structures are documented here for completeness, and to enable developers to create their own methods for generating or converting other fonts into the GUIX font format.
Each GUIX font starts with a GX_FONT structure. The GX_FONT structure defines global font parameters, such as the character included within the font and the line height of the font. The GX_FONT structure points at an array of GX_GLYPH structures. Each GX_GLYPH structure defines
the width, height, and baseline offset of one specific character glyph. The GX_GLYPH structure also points to the actual glyph bitmap data (which may be NULL for whitespace characters).
The **GX_FONT** structure, contained in gx_api.h, is declared as follows:
```c
typedef struct GX_FONT_STRUCT
{
GX_UBYTE gx_font_format
GX_UBYTE gx_font_prespace
GX_UBYTE gx_font_postspace
GX_UBYTE gx_font_line_height
GX_UBYTE gx_font_baseline
USHORT gx_font_first_glyph
USHORT gx_font_last_glyph
GX_CONST GX_GLYPH *gx_font_glyphs
const struct GX_FONT_STRUCT *gx_font_next_page
} GX_FONT;
```
The *gx_font_format* field defines the font bits-per-pixel and other flags, as defined in the gx_api.h header file.
The *gx_font_prespace* defines the pixel space to skip above each line of text in a multi-line text display.
The *gx_font_postspace* field defines the pixel space to skip below each line of text in a multi-line text display.
The *gx_font_line_height* field defines the height of the tallest glyph in the font.
The *gx_font_baseline* field defines the distance, in pixels, from the top row of glyph pixels to the font baseline.
The *gx_font_first_glyph* field defines the first Unicode character encoding included in this font page.
The *gx_font_last_glyph* field defines the last Unicode character encoding included in this font page.
The *gx_font_glyphs* pointer points to an array of GX_GLYPH structures. This array must be equal in size to the number of characters contained on this font page, i.e (*gx_font_last_glyph* – *gx_font_first_glyph*) + 1.
The *gx_font_next_page* member is used for multiple page fonts. Multiple page fonts are used for extended character sets and to optimize the size of the GX_GLYPH structure arrays. If all of the characters of the font are contained within one font page, or if this is the last page of the font in question, the *gx_font_next_page* member is set to GX_NULL.
As noted above, the **GX_FONT** structure above contains a pointer to an array of GX_GLYPHS structures. There must be one GX_GLYPH structure for each character on the font page. The **GX_GLYPH** structure is defined as:
```c
typedef struct GX_GLYPH_STRUCT
{
GX_CONST GX_UBYTE *gx_glyph_map;
GX_BYTE gx_glyph_ascent;
GX_BYTE gx_glyph_descent;
GX_BYTE gx_glyph_advance;
GX_BYTE gx_glyph_leading;
GX_UBYTE gx_glyph_width;
GX_UBYTE gx_glyph_height;
} GX_GLYPH;
```
The gx_glyph_map pointer points to the glyph bitmap. This pointer may be GX_NULL for whitespace characters. The bitmap data is encoded as 1 bpp, 2 bpp, 4 bpp, or 8 bpp alpha values. For 1 bit data, a value of 1 indicates that the pixel should be written in the foreground color, and a value of 0 indicates that the pixel is transparent. For 8 bit data, the values range from 0 (fully transparent) to 255 (fully opaque). All intermediate values represent a blending value for anti-aliased fonts. The glyph bitmap data is always padded to full byte alignment for formats using less than 8bpp data values.
The *gx_glyph_ascent* and gx_glyph_descent values position the glyph vertically with respect to the font baseline.
The *gx_glyph_width* and gx_glyph_height values specify the size of the glyph bitmap data.
The *gx_glyph_advance* value specifies the pixel width to advance the drawing position after drawing the glyph (this may not be equal to the glyph width).
The *gx_glyph_leading* value specifies the pixels to advance in the x-direction prior to rendering the glyph.

152
rtos-docs/guix/appendix-h.md Normal file
View File

@@ -0,0 +1,152 @@
---
title: Appendix H - GUIX Build-Time Configuration flags
description: Learn about GUIX build-time configuration flags.
---
# Appendix H - GUIX Build-Time Configuration flags
GUIX support several conditional compilation options and configuration values. The default setting for these conditionals and configuration values can be overridden by pre-defining the value, either in your gx_user.h header file or on your compiler command line.
**GX_DISABLE_THREADX_BINDING**
- Default: Undefined
- Description: This conditional can be used to disable the default ThreadX RTOS binding. If you want to run GUIX with an RTOS other than ThreadX, you should #define GX_DISABLE_THREADX_BINDING and provide your own RTOS binding services.
**GX_SYSTEM_TIMER_MS**
- Default: 20
- Description: This value defines the desired GUIX timer interval or precision.
**TX_TIMER_TICKS_PER_SECOND**
- Default: 100
- Description: This value defines the number of TX timer interrupt frequencies. Since the default ThreadX interval timer is 10 ms, this value defaults to a 100-Hz frequency.
**GX_DISABLE_MULTITHREAD_SUPPORT**
- Default: Not defined
- Description: This compile-time conditional can be used to disable the GUIX API support for multiple threads invoking the GUIX API concurrently. If only one application thread will ever utilize the GUIX API, you should define this flag to reduce the system overhead associated with protecting critical code sections.
**GX_DISABLE_UTF8_SUPPORT**
- Default: Not Defined.
- Description: This compile-time conditional can be used to remove the GUIX internal support for UTF8 format string encoding. If you are using only character values M- 0xff in your application, turning on this #define will reduce the code size and overhead associated with supporting UTF8 format string encoding.
**GX_DISABLE_ARC_DRAWING_SUPPORT**
- Default: Not defined.
- Description: This conditional can be used to reduce the GUIX library code size and GX_DISPLAY structure size by removing support for the arc-drawing functions circle, arc, pie, and ellipse. These functions are not required by the default GUIX widget set.
**GX_DISABLE_SOFTWARE_DECODER_SUPPORT**
- Default: Not defined.
- Description: This conditional can be defined to remove the GUIX library runtime jpeg and png software decoder support. If your application does not require runtime decode of jpg or png files meaning your application does not use RAW format pixelmaps produced by Studio and does not read image files from an external filesystem, you can turn on this #define to reduce the GUIX library footprint.
**GX_DISABLE_BINARY_RESOURCE_SUPPORT**
- Default: Not defined
- Description: This conditional can be used to remove the GUIX library support for loading binary resource data. Binary resources can be used to do runtime binding of resource data with your GUIX application. If you are using only C source code format resource files, you can define this conditional to reduce your GUIX library footprint.
**GX_DISABLE_BRUSH_ALPHA_SUPPORT**
- Default: Not defined.
- Description: When running at 16 bpp and higher color depths, GUIX optionally supports drawing non-arc graphics, pixelmaps, and fonts with an alpha value defined by the drawing context brush. Supporting this drawing mode introduces a small runtime overhead and library footprint increase, which can be eliminated by defining this flag if you do not require alpha-blending drawing support. Note that pixelmaps with alpha channel, anti-aliased fonts, and other anti-aliasing drawing modes are still supported regardless of this conditional setting.
**GX_DISABLE_THREADX_TIMER_SOURCE**
- Default: Not defined.
- Description: This conditional can be used to disable the ThreadX timer source. You should define GX_DISABLE_THREADX_TIMER_SOURCE if you want to use a different timer source.
**GX_ENABLE_ARM_HELIUM**
- Default: Not defined.
- Description: This conditional can be used to enable ARM Helium instructions for JPEG decoding, resulting in enhanced performance.
**GX_ENABLE_CANVAS_PARTIAL_FRAME_BUFFER**
- Default: Not defined.
- Description: This conditional can be used to enable partial frame buffer support for canvas. When this conditional is defined, you are able to define a canvas buffer that is smaller than the canvas size. This is useful when the system has limited memory.
**GX_CANVAS_REFRESH_DIRECTION_HORIZONTAL**
- Default: Not defined.
- Description: This conditional is used when canvas partial frame buffer feature is enabled. This conditional can be used to enable horizontal refresh direction for canvas, specifically from left to right.
**GX_CANVAS_REFRESH_DIRECTION_VERTICAL**
- Default: Not defined.
- Description: This conditional is used when canvas partial frame buffer feature is enabled. This conditional can be used to enable vertical refresh direction for canvas, specifically from top to bottom.
**GX_REPEAT_BUTTON_INITIAL_TICS**
- Default: 10.
- Description: If a button has style GX_STYLE_BUTTON_REPEAT, this value defines how long the button
waits before beginning to send repeated GX_EVENT_CLICKED events.
**GX_MAX_QUEUE_EVENTS**
- Default: 48.
- Description: Defines the size of the GUIX event queue in units of event structure entries. If the event queue overflows, events being pushed into the queue are discarded and GX_SYSTEM_ERROR is returned by the gx_system_event_send() function.
**GX_MAX_DIRTY_AREAS**
- Default: 64.
- Description: Defines the maximum number of unique dirty list entries that can be maintained by one canvas. When the dirty list overflows, GUIX will default to marking the canvas root window as dirty, which is less efficient than drawing individual child widgets.
**GX_MAX_CONTEXT_NESTING**
- Default: 8.
- Description: Defines the maximum nesting of the drawing context stack. This is equivalent to the maximum nesting of parent/child/child/child widgets within the UI definition.
**GX_MAX_INPUT_CAPTURE_NESTING**
- Default: 4.
- Description: Defines the size of the stack used to maintain the list of widgets that have captures the user input (mouse and keyboard).
**GX_SYSTEM_THREAD_PRIORITY**
- Default: 16.
- Description: Defines the priority of the GUIX thread created during gx_system_initialize().
**GX_SYSTEM_THREAD_TIMESLICE**
- Default: 10.
- Description: Defines the GUIX thread timeslice in terms of RTOS timer ticks. If other threads are defined with the same priority as the GUIX thread, this value determines how often those competing threads are granted CPU control.
**GX_CURSOR_BLINK_INTERVAL**
- Default: 20.
- Description: Defines the rate at which the input cursor blinks for text input widgets. This value is in terms of GUIX timer ticks, which by default is defines as 50 ms, so a value of 20 indicates that the input cursor blinks once per second.
**GX_MULTI_LINE_INDEX_CACHE_SIZE**
- Default: 32.
- Description: Defines the size of the list-start index cache maintained by the multi-line text view and multi-line text input widgets. This cache is used to accomplish fast vertical scrolling of multi line text widgets. For best performance, the cache size should be set greater than the number of visible rows of the largest multi line text widget defined by the application. For example, if the most visible rows for any text widget are 20 rows, the application might define a cache size
of 32 (the default), which allows GUIX to scroll vertically without recalculating all line start indexes.
**GX_MULTI_LINE_TEXT_BUTTON_MAX_LINES**
- Default: 4.
- Description: The multi-line text button control block maintains a pointer to each line of text to be displayed by the button. This value determines the number of text pointers needed by the worst case multi-line text button.
**GX_POLYGON_MAX_EDGE_NUM**
- Default: 10.
- Description: This value determines the most complex polygon that can be drawn by GUIX. The polygon drawing algorithm determines the lines needed to define the polygon edges, and this definition defines the maximum number of edges that can be supported.
**GX_NUMERIC_SCROLL_WHEEL_STRING_BUFFER_SIZE**
- Default: 16.
- Description: For a number scroll wheel, the scroll wheel widget converts integer values to ascii strings. This value determines the maximum length of the string required to display the assigned integer values.
**GX_DEFAULT_CIRCULAR_GAUGE_ANIMATION_DELAY**
- Default: 5.
- Description: Defines the number of GUIX timer ticks (50 ms) between updates of a circular gauge configured to animate the needle movement between last and current angular position.
**GX_NUMERIC_PROMPT_BUFFER_SIZE**
- Default: 16.
- Description: A numeric prompt allocates a buffer to convert an integer value assigned to the prompt to an ascii string. This definition defines the size of this character buffer.
**GX_ANIMATION_POOL_SIZE**
- Default: 6.
- Description: GUIX defines an animation pool from which animation information structures can be dynamically allocated and returned, using gx_system_animation_get and gx_system_animation_free()
APIs. This definition defines the size of this animation control block pool.
**GX_MOUSE_SUPPORT**
- Default: Not defined.
- Description: This definition enables support for mouse input. Software mouse requires that the display driver draw and track the mouse cursor, which adds extra overhead to the display driver. This definition should only be defined when a mouse (not a touch screen) must be supported.
**GX_HARDWARE_MOUSE_SUPPORT**
- Default: Not defined.
- Description: When this definition is defined, the GUIX display driver utilizes hardware mouse cursor drawing support. This reduces the memory required to capture the canvas memory beneath the mouse cursor and improves system performance for those hardware targets support a mouse overlay graphics layer.
**GX_FONT_KERNING_SUPPORT**
- Default: Not defined.
- Description: This definition can be defined to enable font kerning support. Font kerning improves glyph spacing for certain glyph combinations. This support adds a small amount of overhead to the
runtime string drawing functions, and also adds a small amount of size to the font data structures.
**GX_WIDGET_USER_DATA**
- Default: Not defined.
- Description: If defined, this adds a user-defined data field to the GX_WIDGET control block. This data field can be assigned using the properties view within GUIX Studio. This data field is ignored by GUIX internally, but can be used by application software for many purposes.
**GUIX_5_4_0_COMPATIBILITY**
- Default: Not defined.
- Description: Certain GUI APIs were modified after release 5.4.0 to add support for disabled text colors and to improve the accuracy of certain math functions by using fixed-point match parameters. These changes make GUIX library releases after 5.4.0 incompatible with previous releases. However, by turning on this #define, the library can be built such that the APIs fully compatible with releases <= 5.4.0, meaning that no changes are needed in existing applications to compile with the latest GUIX library release.
**GX_MAX_STRING_LENGTH**
- Default: 102400
- Description: Defines the maximum length of a string, which is used to test invalid strings. If the input string is exceeding the maximum string length, it will be regard as invalid.

426
rtos-docs/guix/appendix-i.md Normal file
View File

@@ -0,0 +1,426 @@
---
title: Appendix I - GUIX Information Structures
description: Learn about GUIX information structures.
---
# Appendix I - GUIX Information Structures
## GX_BIDI_TEXT_INFO
### Definition
```c
typedef struct GX_BIDI_TEXT_INFO_STRUCT
{
GX_STRING gx_bidi_text_info_text;
GX_FONT *gx_bidi_text_info_font;
GX_VALUE gx_bidi_text_info_display_width;
} GX_BIDI_TEXT_INFO;
```
| Members | Description |
| ---------------------------------- | ---------------------------------------------------------- |
| **gx_bidi_text_info_text** | Text for reordering |
| **gx_bidi_text_info_font** | Font used to display text, set it to GX_NULL if line breaking is not needed |
| **gx_bidi_text_info_display_width** | Available width for displaying, set it to -1 if line breaking is not needed |
## GX_BIDI_RESOLVED_TEXT_INFO
### Definition
```c
typedef struct GX_BIDI_RESOLVED_TEXT_INFO_STRUCT
{
GX_STRING *gx_bidi_resolved_text_info_text;
UINT gx_bidi_resolved_text_info_total_lines;
struct GX_BIDI_RESOLVED_TEXT_INFO_STRUCT *gx_bidi_resolved_text_info_next;
} GX_BIDI_RESOLVED_TEXT_INFO;
```
| Members | Description |
| ---------------------------------- | ---------------------------------------------------------- |
| **gx_bidi_resolved_text_info_text** | Pointer to the array of reordered bidi text |
| **gx_bidi_resolved_text_info_total_lines** | Total lines of resolved bidi text for one paragraph |
| **gx_bidi_resolved_text_info_next** | Resolved bidi text information for the next paragraph |
## GX_CIRCULAR_GAUGE_INFO
### Definition
```c
typedef struct GX_CIRCULAR_GAUGE_INFO_STRUCT
{
INT gx_circular_gauge_info_animation_steps;
INT gx_circular_gauge_info_animation_delay;
GX_VALUE gx_circular_gauge_info_needle_xpos;
GX_VALUE gx_circular_gauge_info_needle_ypos;
GX_VALUE gx_circular_gauge_info_needle_xcor;
GX_VALUE gx_circular_gauge_info_needle_ycor;
GX_RESOURCE_ID gx_circular_gauge_info_needle_pixelmap;
} GX_CIRCULAR_GAUGE_INFO;
```
| Members | Description |
| ------------------------------------------------ | -------------------------------------------- |
| **gx_circular_gauge_info_animation_steps** | Total steps the needle will travel through when moving from the current needle angle to a newly assigned needle angle |
| **gx_circular_gauge_info_animation_delay** | The number of GUIX clock ticks to delay between animation steps |
| **gx_circular_gauge_info_needle_xpos** | The distance from the left of the gauge widget to the center-of-rotation of the gauge needle |
| **gx_circular_gauge_info_needle_ypos** | The distance from the top of the gauge widget to the center-of-rotation of the gauge needle |
| **gx_circular_gauge_info_needle_xcor** | The distance from the left of the needle image to the center-of-rotation of the gauge needle |
| **gx_circular_gauge_info_needle_ycor** | The distance from the top of the needle image to the center-of-rotation of the gauge needle |
| **gx_circular_gauge_info_needle_pixelmap** | Resource ID of the pixelmap which will be used to draw the gauge needle. This image will be rotated as needed by the gauge widget to display the gauge needle in any position |
The diagram below illustrates the xpos, ypos, and xcor, ycor coordinates:
![Diagram of the Needle Y and X coordinates](./media/guix/image8.png)
## GX_LINE_CHART_INFO
### Definition
```c
typedef struct GX_LINE_CHART_INFO_STRUCT
{
INT gx_line_chart_min_val;
INT gx_line_chart_max_val;
INT *gx_line_chart_data;
GX_VALUE gx_line_left_margin;
GX_VALUE gx_line_top_margin;
GX_VALUE gx_line_right_margin;
GX_VALUE gx_line_bottom_margin;
GX_VALUE gx_line_chart_max_data_count;
GX_VALUE gx_line_chart_active_data_count;
GX_VALUE gx_line_chart_axis_line_width;
GX_VALUE gx_line_chart_data_line_width;
GX_RESOURCE_ID gx_line_chart_axis_color;
GX_RESOURCE_ID gx_line_chart_line_color;
} GX_LINE_CHART_INFO;
```
| Members | Description |
| ---------------------------------- | ---------------------------------------------------------- |
| **gx_line_chart_min_val** | The minimum data value, which is used to calculate scaling
| **gx_line_chart_max_val** | The maximum data value, which is used to calculate scaling |
| **gx_line_chart_data** | Pointer to an array of integer values. These are the integer values plotted by the line chart widget |
| **gx_line_\<side\>_margin** | The offset from the chart window outer bound to the actual chart rendering area. The chart axis and data line are always plotted within this inner boundary, which allows the application to draw labels and other information inside the chart window but outside the char graphing area |
| **gx_line_chart_max_data_count** | The number of data values which may be present. This parameter is used for calculating the x-axis scaling or interval for plotting data points. |
| **gx_line_active_data_count** | The number of data values that actually present in the data array. A line chart may be scaled to draw a maximum of 100 values (for example), but on any particular update a smaller number of data values may actually be present. |
| **gx_line_axis_line_width** | Width of the line used to draw the horizontal and vertical axis |
| **gx_line_data_line_width** | Width of the plotted data line |
| **gx_line_chart_axis_color** | Resource ID of the color used to draw the axis lines |
| **gx_line_chart_line_color** | Resource ID of the color used to draw the chart data line |
## GX_MOUSE_CURSOR_INFO
### Definition
```c
typedef struct GX_MOUSE_CURSOR_INFO_STRUCT
{
GX_RESOURCE_ID gx_mouse_cursor_image_id;
GX_VALUE gx_mouse_cursor_hotspot_x;
GX_VALUE gx_mouse_cursor_hotspot_y;
} GX_MOUSE_CURSOR_INFO;
```
| Members | Description |
| ---------------------------------- | ---------------------------------------------------------- |
| **gx_mouse_cursor_image_id** | Resource ID of the mouse image |
| **gx_mouse_cursor_hotspot_x** | The offset from the left of the mouse image to the mouse image hotspot |
| **gx_mouse_cursor_hotspot_y** | The offset from the top of the mouse image to the mouse image hotspot |
## GX_PEN_CONFIGURATION
### Definition
```c
typedef struct GX_PEN_CONFIGURATION_STRUCT
{
GX_FIXED_VAL gx_pen_configuration_min_drag_dist;
UINT gx_pen_configuration_max_pen_speed_ticks;
}GX_PEN_CONFIGURATION;
```
| Members | Description |
| -------------------------------------------- | ------------------------------------------------ |
| **gx_pen_configuration_min_drag_dist** | The minimum drag distance per GUIX timer tick to trigger an FLICK event. Call GX_FIXED_VAL_MAKE to make a fixed point data type value |
| **gx_pen_configuration_max_pen_speed_ticks** | The maximum drag speed in GUIX timer ticks to trigger an FLICK event |
## GX_PIXELMAP_SLIDER_INFO
### Definition
```c
typedef struct GX_PIXELMAP_SLIDER_INFO_STRUCT
{
GX_RESOURCE_ID gx_pixelmap_slider_info_lower_background_pixelmap;
GX_RESOURCE_ID gx_pixelmap_slider_info_upper_background_pixelmap;
GX_RESOURCE_ID gx_pixelmap_slider_info_needle_pixelmap;
} GX_PIXELMAP_SLIDER_INFO;
```
| Members | Description |
| ----------------------------------------------------- | ---------------------------------------- |
| **gx_pixelmap_slider_info_lower_background_pixelmap** | Resource ID of the pixelmap for filling the background before the needle. If upper background pixelmap is not set, it's used for filling background both before and after the needle |
| **gx_pixelmap_slider_info_upper_background_pixelmap** | Resource ID of the pixelmap for filling background after the needle |
| **gx_pixelmap_slider_info_needle_pixelmap** | Resource ID of the needle pixelmap |
## GX_PROGRESS_BAR_INFO
### **Definition**
```c
typedef struct GX_PROGRESS_BAR_INFO_STRUCT
{
INT gx_progress_bar_info_min_val;
INT gx_progress_bar_info_max_val;
INT gx_progress_bar_info_current_val;
GX_RESOURCE_ID gx_progress_bar_font_id;
GX_RESOURCE_ID gx_progress_bar_normal_text_color;
GX_RESOURCE_ID gx_progress_bar_selected_text_color;
GX_RESOURCE_ID gx_progress_bar_disabled_text_color;
GX_RESOURCE_ID gx_progress_bar_fill_pixelmap;
} GX_PROGRESS_BAR_INFO;
```
| Members | Description |
| -------------------------------------------- | ------------------------------------------------ |
| **gx_progress_bar_info_min_val** | Minimum reported value |
| **gx_progress_bar_info_max_val** | Maximum reported value |
| **gx_progress_bar_info_current_val** | Current value |
| **gx_progress_bar_info_font_id** | Resource ID of the font, used to draw the optional text value within the progress bar widget |
| **gx_progress_bar_normal_text_color** | Resource ID of the text color in normal state, used to define the optional text drawing within the progress bar widget |
| **gx_progress_bar_selected_text_color** | Resource ID of the text color when the widget gain focus, used to define the optional text drawing within the progress bar widget |
| **gx_progress_bar_disabled_text_color** | Resource ID of the text color when GX_STYLE_ENABLED is not active, used to define the optional text drawing within the progress bar widget |
| **gx_progress_bar_fill_pixelmap** | Resource ID of the pixelmap for background filling|
## GX_RADIAL_PROGRESS_BAR_INFO
### Definition
```c
typedef struct GX_RADIAL_PROGRESS_BAR_INFO_STRUCT
{
GX_VALUE gx_radial_progress_bar_info_xcenter;
GX_VALUE gx_radial_progress_bar_info_ycenter;
GX_VALUE gx_radial_progress_bar_info_radius;
GX_VALUE gx_radial_progress_bar_info_current_val;
GX_VALUE gx_radial_progress_bar_info_anchor_val;
GX_RESOURCE_ID gx_radial_progress_bar_info_font_id;
GX_RESOURCE_ID gx_radial_progress_bar_info_normal_text_color;
GX_RESOURCE_ID gx_radial_progress_bar_info_selected_text_color;
GX_RESOURCE_ID gx_radial_progress_bar_info_disabled_text_color;
GX_VALUE gx_radial_progress_bar_info_normal_brush_width;
GX_VALUE gx_radial_progress_bar_info_selected_brush_width;
GX_RESOURCE_ID gx_radial_progress_bar_info_normal_brush_color;
GX_RESOURCE_ID gx_radial_progress_bar_info_selected_brush_color;
} GX_RADIAL_PROGRESS_BAR_INFO;
```
| Members | Description |
| ------------------------------------------------- | -------------------------------------------- |
| **gx_radial_progress_bar_info_xcenter** | Widget position in x coordinate |
| **gx_radial_progress_bar_info_ycenter** | Widget position in y coordinate |
| **gx_radial_progress_bar_info_radius** | Radius of the progress circle |
| **gx_radial_progress_bar_info_current_val** | Current value, limited to the range [-360, 360], indicates the angular delta between the anchor position and the end point of the upper arc. Negative value causes the arc to be drawn in a clockwise direction starting at the anchor position. Positive value causes the arc to be drawn in a counter-clockwise direction starting at the anchor position. The application must scale the real-word value being indicated to assign an angular value to the progress bar widget |
| **gx_radial_progress_bar_anchor_val** | Starting angle of the upper progress arc. The value is defined in terms of integer degree with 0 degree pointing to the right and 90 degree indicating straight up position. |
| **gx_radial_progress_bar_font_id** | Resource ID of the font used to draw the optional text value within the progress bar widget |
| **gx_radial_progress_bar_normal_text_color** | Resource ID of the text color in normal state, used to define the optional text drawing within the progress bar widget |
| **gx_radial_progress_bar_selected_text_color** |Resource ID of the text color when widget gain focus, used to define the optional text drawing within the progress bar widget |
| **gx_radial_progress_bar_disabled_text_color** | Resource ID of the text color when GX_STYLE_ENABLED is not active, used to define the optional text drawing within the progress bar widget |
| **gx_radial_progress_bar_normal_brush_width** | Width of the lower progress circle |
| **gx_radial_progress_bar_selected_brush_width** | Width of the upper progress arc, the upper arc may be narrower, the same as, or wider than the lower circle |
| **gx_radial_progress_bar_normal_brush_color** | Resource ID of the color to fill lower progress circle |
| **gx_radial_progress_bar_selected_brush_color** | Resource ID of the color to fill upper progress arc |
## GX_RADIAL_SLIDER_INFO
### Definition
```c
typedef struct GX_RADIAL_SLIDER_INFO_STRUCT
{
GX_VALUE gx_radial_slider_info_xcenter;
GX_VALUE gx_radial_slider_info_ycenter;
USHORT gx_radial_slider_info_radius;
USHORT gx_radial_slider_info_track_width;
GX_VALUE gx_radial_slider_info_current_angle;
GX_VALUE gx_radial_slider_info_min_angle;
GX_VALUE gx_radial_slider_info_max_angle;
GX_VALUE *gx_radial_slider_info_angle_list;
USHORT gx_radial_slider_info_list_cont;
GX_RESOURCE_ID gx_radial_slider_info_background_pixelmap;
GX_RESOURCE_ID gx_radial_slider_info_needle_pixelmap;
} GX_RADIAL_SLIDER_INFO;
```
| Members | Description |
| --------------------------------------------- | ------------------------------------------------ |
**gx_radial_slider_info_xcenter** | Distance from the left of the slider widget to the center-of-rotation of the slider needle |
| **gx_radial_slider_info_ycenter** | Distance from the top of the slider widget to the center-of-rotation of the slider needle |
| **gx_radial_slider_info_radius** | Radius of the radial slider circle |
| **gx_radial_slider_info_track_width** | Width of radial slider track |
| **gx_radial_slider_info_current_angle** | Current slider angle |
| **gx_radial_slider_info_min_angle** | Minimum slider angle |
| **gx_radial_slider_info_max_angle** | Maximum slider angle |
| **gx_radial_slider_info_angle_list** | Angle value list, defines anchor angles, if set, slider angle can only be one of the defined anchor angles |
| **gx_radial_slider_info_list_count** | Number of anchor angles |
| **gx_radial_slider_info_background_pixelmap** | Resource ID of background pixelmap |
| **gx_radial_slider_info_needle_pixelmap** | Resource ID of needle pixelmap |
## GX_RECTANGLE
### Definition
```c
typedef struct GX_RECTANGLE_STRUCT
{
GX_VALUE gx_rectangle_left;
GX_VALUE gx_rectangle_top;
GX_VALUE gx_rectangle_right;
GX_VALUE gx_rectangle_bottom;
} GX_RECTANGLE;
```
| Members | Description |
| -------------------------------- | ------------------------|
| **gx_rectangle_left** | Left of the rectangle |
| **gx_rectangle_top** | Top of the rectangle |
| **gx_rectangle_right** | Right of the rectangle |
| **gx_rectangle_bottom** | Bottom of the rectangle |
## GX_RICH_TEXT_FONTS
### Definition
```c
typedef struct GX_RICH_TEXT_FONTS_STRUCT
{
GX_RESOURCE_ID gx_rich_text_fonts_normal_id;
GX_RESOURCE_ID gx_rich_text_fonts_bold_id;
GX_RESOURCE_ID gx_rich_text_fonts_italic_id;
GX_RESOURCE_ID gx_rich_text_fonts_bold_italic_id;
} GX_RICH_TEXT_FONTS;
```
| Members | Description |
| ---------------------------------- | ---------------------------------------------------------- |
| **gx_rich_text_fonts_normal_id** | Resource ID of normal text font |
| **gx_rich_text_fonts_bold_id** | Resource ID of bold text font |
| **gx_rich_text_fonts_italic_id** | Resource ID of italic text font |
| **gx_rich_text_fonts_bold_italic_id** | Resource ID of bold italic text font |
## GX_SCROLL_INFO
### **Definition**
```c
typedef struct GX_SCROLL_INFO_STRUCT
{
INT gx_scroll_value;
INT gx_scroll_minimum;
INT gx_scroll_maximum;
GX_VALUE gx_scroll_visible;
GX_VALUE gx_scroll_increment;
} GX_SCROLL_INFO;
```
| Members | Description |
| ----------------------- | ----------------------------- |
| **gx_scroll_value** | Current scroll position |
| **gx_scroll_minimum** | Minimum reported position |
| **gx_scroll_maximum** | Maximum reported position |
| **gx_scroll_visible** | Parent window visible range |
| **gx_scroll_increment** | Scrollbar minimum delta value |
## GX_SCROLLBAR_APPEARANCE
### Definition
```c
typedef struct GX_SCROLLBAR_APPEARANCE_STRUCT
{
GX_VALUE gx_scroll_width;
GX_VALUE gx_scroll_thumb_width;
GX_VALUE gx_scroll_thumb_travel_min;
GX_VALUE gx_scroll_thumb_travel_max;
GX_UBYTE gx_scroll_thumb_border_style;
GX_RESOURCE_ID gx_scroll_fill_pixelmap;
GX_RESOURCE_ID gx_scroll_thumb_pixelmap;
GX_RESOURCE_ID gx_scroll_up_pixelmap;
GX_RESOURCE_ID gx_scroll_down_pixelmap;
GX_RESOURCE_ID gx_scroll_thumb_color;
GX_RESOURCE_ID gx_scroll_thumb_border_color;
GX_RESOURCE_ID gx_scroll_button_color;
} GX_SCROLLBAR_APPEARANCE;
```
| Members | Description |
| ---------------------------------------- | ----------------------------------------------------- |
| **gx_scroll_width** | Width of the scrollbar widget, in pixels |
| **gx_scroll_thumb_width** | Width of the thumb button which slides on the scrollbar, in pixels. This value is usually some number of pixels less than the total scrollbar width |
| **gx_scroll_thumb_travel_min** | Offset from the end of scrollbar to minimum thumb button travel point. This limit can be used to prevent the thumb button from traveling to the very end of the scrollbar |
| **gx_scroll_thumb_travel_max** | Offset from the end of scrollbar to maximum thumb button travel point. This limit can be used to prevent the thumb button from traveling to the very end of the scrollbar |
| **gx_scroll_thumb_border_style** | Border styles of thumb button |
| **gx_scroll_fill_pixelmap** | Optional pixelmap ID. If this pixelmap ID is not zero, the scrollbar uses this pixelmap to draw the scrollbar background |
| **gx_scroll_thumb_pixelmap** | Optional pixelmap ID. If this pixelmap ID is not zero, the scrollbar thumb button uses this pixelmap to draw itself |
| **gx_scroll_up_pixelmap** | Optional pixelmap ID. If this pixelmap ID is not zero, the scrollbar uses this pixelmap ID to draw the scrollbar left/up end button |
| **gx_scroll_down_pixelmap** | Optional pixelmap ID. If this pixelmap ID is not zero, the scrollbar uses this pixelmap ID to draw the scrollbar right/down end button |
| **gx_scroll_thumb_color** | Resource ID of color used to fill thumb button |
| **gx_scroll_thumb_border_color** | Resource ID of color used to draw the border of thumb button |
| **gx_scroll_button_color** | Resource ID of color used to fill scrollbar end buttons |
## GX_SLIDER_INFO
### Definition
```c
typedef struct GX_SLIDER_INFO_STRUCT
{
INT gx_slider_info_min_val;
INT gx_slider_info_max_val;
INT gx_slider_info_current_val;
INT gx_slider_info_increment;
GX_VALUE gx_slider_info_min_travel;
GX_VALUE gx_slider_info_max_travel;
GX_VALUE gx_slider_info_needle_width;
GX_VALUE gx_slider_info_needle_height;
GX_VALUE gx_slider_info_needle_inset;
GX_VALUE gx_slider_info_needle_hotspot_offset;
} GX_SLIDER_INFO;
```
| Members | Description |
| --------------------------------------- | ------------------------------------------------------ |
| **gx_slider_info_min_val** | Minimum reported value |
| **gx_slider_info_max_val** | Maximum reported value |
| **gx_slider_info_current_value** | Current value |
| **gx_slider_info_min_travel** | Needle travel limit |
| **gx_slider_info_max_travel** | Needle travel limit |
| **gx_slider_info_needle_width** | Needle width in pixel |
| **gx_slider_info_needle_height** | Needle height in pixel |
|**gx_slider_info_needle_inset** | Needle draw position. If GX_STYLE_SLIDER_VERTICAL is set, used to specify the offset from the needle draw start position to the slider left. Else, used to specify the offset from the needle draw start position to the slider top. |
| **gx_slider_info_needle_hotspot_offset** | Needle hotpot_offset, used to specify the offset from the needle draw start position to the slider hotspot. |
## GX_SPRITE_FRAME
### Definition
```c
typedef struct GX_SPRITE_FRAME_STRUCT
{
GX_RESOURCE_ID gx_sprite_frame_pixelmap;
GX_VALUE gx_sprite_frame_x_offset;
GX_VALUE gx_sprite_frame_y_offset;
UINT gx_sprite_frame_delay;
UINT gx_sprite_frame_background_operation;
UCHAR gx_sprite_frame_alpha;
} GX_SPRITE_FRAME;
```
| Members | Description |
| ---------------------------------------- | ----------------------------------------------------- |
| **gx_sprite_frame_pixelmap** | Resource ID of the pixelmap to be displayed for this frame. The ID can be 0. |
| **gx_sprite_frame_x_offset** | Offset from the sprite widget left to display the pixelmap |
| **gx_sprite_frame_y_offset** | Offset from the sprite widget top to display the pixelmap |
| **gx_sprite_frame_delay** | Delay value, in GUIX timer ticks, after displaying this frame before advancing to the next sprite frame |
| **gx_sprite_frame_background_operation** | Define how the background should be erased. Possible values for this field are:<br />GX_SPRITE_BACKGROUND_NO_ACTION: No fill between frames<br />GX_SPRITE_BACKGROUND_SOLID_FILL: Redraw sprite background<br />GX_SPRITE_BACKGROUND_RESTORE: Restore previous pixelmap |
| **gx_sprite_frame_alpha** | Alpha value to be added to the displayed pixelmap. The value 255 specifies that no extra alpha value should be imposed. If the pixelmap includes an alpha channel, this alpha channel will be added to the frame alpha value. |

93
rtos-docs/guix/appendix-j.md Normal file
View File

@@ -0,0 +1,93 @@
---
title: Appendix D - Canvas Partial Frame Buffer Feature
description: Learn about the GUIX canvas partial frame buffer feature.
---
# Appendix J - Canvas Partial Frame Buffer Feature
The canvas partial frame buffer feature allows you to allocate a smaller portion of memory for the canvas buffer compared to the full canvas size. This is particularly advantageous for embedded systems with limited memory. This feature is disabled by default and only available for 565rgb color format without screen rotation. To enable this feature, you must define the configuration GX_ENABLE_CANVAS_PARTIAL_FRAME_BUFFER.
The minimum canvas memory size should be sufficient to accommodate a single line of pixels on the screen.
### Example to enable the canvas partial frame buffer feature
- Define the configuration GX_ENABLE_CANVAS_PARTIAL_FRAME_BUFFER.
- Uncheck "allocate canvas memory" in project configure dialog for your GUIX Studio project and generate output files.
- Call `gx_canvas_memory_define` to allocate canvas memory.
- Update your toggle function. The following example shows how to update the toggle function for the canvas partial frame buffer feature.
```
void hardware_16bpp_buffer_toggle(GX_CANVAS *canvas, GX_RECTANGLE *dirty)
{
GX_RECTANGLE Limit;
GX_RECTANGLE Copy;
INT y;
USHORT* pixel;
USHORT *memptr = (USHORT*)canvas -> gx_canvas_memory;
gx_utility_rectangle_define(&Limit, 0, 0,
BOARD_SCREEN_WIDTH - 1, BOARD_SCREEN_HEIGHT - 1);
if (gx_utility_rectangle_overlap_detect(&Limit, &canvas->gx_canvas_dirty_area, &Copy))
{
for(y = Copy.gx_rectangle_top; y <= Copy.gx_rectangle_bottom; y++)
{
pixel = memptr;
#if defined(GX_ENABLE_CANVAS_PARTIAL_FRAME_BUFFER)
pixel += (y - canvas->gx_canvas_memory_offset_y) * canvas->gx_canvas_memory_width;
pixel += (Copy.gx_rectangle_left - canvas->gx_canvas_memory_offset_x);
#else
pixel += y * BOARD_SCREEN_WIDTH;
pixel += Copy.gx_rectangle_left;
#endif
BSP_LCD_DrawRGBImage(Copy.gx_rectangle_left, y, Copy.gx_rectangle_right - Copy.gx_rectangle_left + 1, 1, (uint8_t *)pixel);
}
}
}
```
### Canvas Refresh Methods for Partial Frame Buffer Feature
GUIX manages the canvas dirty area using a linked list. By default, the canvas refreshes its dirty areas by iterating through the dirty list and refreshing each dirty area sequentially. This approach optimizes the utilization of available canvas memory. However, this method does not guarantee a specific refresh direction, which can make it challenging to effectively mitigate potential tearing effects.
![Figure 1.](./media/guix/canvas_refresh_default.png)
*Figure 1: Tearing Effect Example.*
Let's consider Figure 1 as an example to illustrate how tearing effect happens. In this scenario, the canvas exhibits two dirty areas labeled as "Dirty 1" and "Dirty 2." The red horizontal line represents the display refreshing line.
The canvas undertakes the task of refreshing the dirty areas in the sequence of "Dirty 1" followed by "Dirty 2." Assuming the display refreshes from top to bottom, the process unfolds as follows: When the display refreshes line 1, the canvas initiates the refreshing of its dirty area. By the time the display refresh reaches line 2, "Dirty 1" has been updated. When the display refresh advances to line 3, "Dirty 2" is updated as well.
However, upon reaching the bottom, only the updated portion of "Dirty 1" is displayed on the screen, while the updated portion of "Dirty 2" is yet to be displayed. This disparity between the two areas may cause the undesirable tearing effect.
To address the previously mentioned issues, two additional canvas refresh methods are made available. You can enable one of these methods using either of the following two definitions:
- GX_CANVAS_REFRESH_DIRECTION_VERTICAL
- GX_CANVAS_REFRESH_DIRECTION_HORIZONTAL
#### Canvas Refresh Direction: Vertical
When the canvas refresh direction is set to vertical, the canvas refreshes its dirty areas in the vertical direction.
![Figure 2.](./media/guix/canvas_refresh_vertical.png)
*Figure 2: Canvas Refreshing with Direction Set to Vertical.*
Figure 2 illustrates the canvas refreshing process with the direction set to vertical. In this configuration, a combined dirty area is calculated, encompassing both "Dirty 1" and "Dirty 2," represented by the dashed black rectangle. A mask window is employed, matching the width of the combined dirty area, with the total mask size matching the available canvas size. This mask window is moved vertically from the top to the bottom within the combined dirty area, updating the dirty area located within the mask window.
There can still be tearing effect in this refreshing method. To eliminate the tearing effect, additional work is necessary. For example, if the display refreshing speed is faster than the canvas refreshing speed, while the display refreshing pass the top of the combined refreshing area, the canvas can start refreshing, but the display won't show the updated content until the next refreshing pass. This can eliminate the possible tearing effect.
### Canvas Refresh Direction: Horizontal
When the canvas refresh direction is set to horizontal, the canvas refreshes its dirty areas in the horizontal direction.
![Figure 3.](./media/guix/canvas_refresh_horizontal.png)
*Figure 3: Canvas Refreshing with Direction Set to Horizontal.*
Figure 3 illustrates the canvas refreshing process with the direction set to horizontal. In this configuration, a combined dirty area is calculated, encompassing both "Dirty 1" and "Dirty 2," represented by the dashed black rectangle. A mask window is employed, matching the height of the combined dirty area, with the total mask size matching the available canvas size. This mask window is moved horizontally from the left to the right within the combined dirty area, updating the dirty area located within the mask window.
There can still be tearing effect in this refreshing method. To eliminate the tearing effect, additional work is required. For example, if the display refreshing speed is faster than the canvas refreshing speed, while the display refreshing pass the left of the combined refreshing area, the canvas can start refreshing, but the display won't show the updated content until the next refreshing pass. This eliminates the tearing effect.

185
rtos-docs/guix/chapter-1.md Normal file
View File

@@ -0,0 +1,185 @@
---
title: Chapter 1 - Introduction to GUIX
description: GUIX is a high-performance real-time implementation of a GUI designed exclusively for embedded ThreadX-based applications.
---
# Chapter 1 - Introduction to GUIX
GUIX is a high-performance real-time implementation of a graphical interface framework designed
exclusively for embedded ThreadX-based applications. This chapter
contains an introduction to GUIX and a description of its applications
and benefits.
## GUIX Feature Overview
Unlike many other GUI implementations, GUIX is designed to be versatile—easily scaling from small micro-controller-based applications to those that use powerful RISC and DSP processors. This is in sharp contrast to public domain or other commercial implementations originally intended for workstation environments but then squeezed into
embedded designs. An overview of GUIX features follows:
- Easy to use with host-based design tool GUIX Studio
- Win32 GUIX run-time environment for complete hosted prototyping
- Supports most processors supported by ThreadX
- Written exclusively in ANSI C
- Endian neutral
- Smallest, Fasted Embedded GUI
- Run-time configurable, number of objects, screen size, etc.
- Easy to write display driver interface
- Color (up to 32-bpp color depth), monochrome, and grayscale support
- Multilingual support via UTF8 string encoding and string resources
- Default free fonts and easy to add new fonts
- Multiple drawing Canvases supported, of various sizes
- Multiple displays of different sizes and color depths supported
- Screen Transition support (fade in, fade out, swipe, etc.)
- Touch Screen, Gesture, and Virtual Keyboard Support
- Bitmap compression
- Alpha Blending Support
- Dither Support
- Anti-Aliasing Support
- Skinning and Themes
- Canvas Blending
- Complete Window Management
- Parent/Child Relationship
- Dynamic creation, deletion, resizing, moving
- Separate event handling and drawing
- Z-order
- Clipping and views
- Extensive Set of Widgets
- Various button types, sliders, and dials
- Drop Down List
- Prompt
- Multi-Line text view
- Single and Multi-Line text input
- Numeric and Textual Scroll Wheels
- Windows and Scroll Bars
- Radial Progress Bar
- Sprite
### ANSI C Source Code
GUIX is written completely in ANSI C and is portable immediately to
virtually any processor architecture that has an ANSI C compiler and
ThreadX support. Although written in ANSI C, GUIX uses an object
oriented model and inheritance.
### Not A Black Box
Most distributions of GUIX include the complete C source code. This
eliminates the "black-box" problems that occur with many commercial GUI
implementations. By using GUIX, applications developers can see exactly
what the GUI is doing—there are no mysteries!
Having the source code also allows for application specific
modifications. Although not recommended, it is certainly beneficial to
have the ability to modify the GUI if it is required. These features are
especially comforting to developers accustomed to working with in-house
or public domain products. They expect to have source code and the
ability to modify it. GUIX is the ultimate GUI software for such
developers.
## Embedded GUI Applications
Embedded GUI applications are applications that have a user interface
requirement and execute on microprocessors hidden inside products such
as cellular phones, communication equipment, automotive engines, laser
printers, medical devices, and so forth. Such applications almost always
have some memory and performance constraints. Another distinction of
embedded GUI is that their software and hardware have a dedicated
purpose.
### Real-time GUI Software
Basically, GUI software that must perform its processing within an exact
period of time is called *real-time GUI* software, and when time
constraints are imposed on GUI applications, they are classified as
realtime applications. Embedded GUI applications are almost always
real-time because of their inherent interaction with the external world.
## GUIX Benefits
The primary benefits of using GUIX for embedded applications are
high-performance, feature rich, and very small memory requirements. GUIX
is also completely integrated with the high-performance, multitasking
ThreadX real-time operating system.
### Improved Responsiveness
The high-performance GUIX product enables applications to respond faster
than ever before. This is especially important for embedded applications
that either have a significant volume of visual information or strict
timing requirements on displaying such information.
### Software Maintenance
Using GUIX allows developers to easily partition the GUI aspects of
their embedded application. This partitioning makes the entire
development process easy and significantly enhances future software
maintenance.
### Increased Throughput
GUIX provides the highest-performance GUI available, which directly
transfers to the embedded application. GUIX applications are able to
process user interface information faster than non-GUIX applications!
### Processor Isolation
GUIX provides a robust, processor-independent interface between the
application and the underlying processor and display hardware. This
allows developers to concentrate on the high-level aspects of the user
interface rather than spending extra time dealing with display hardware
issues.
### Ease of Use
GUIX is designed with the application developer in mind. The GUIX
architecture and service call interface are easy to understand. As a
result, GUIX developers can quickly use its advanced features.
### Improve Time to Market
The powerful features of GUIX accelerate the software development
process. GUIX abstracts most processor and display hardware issues,
thereby removing these concerns from a majority of application user
interface implementation. This feature, coupled with the ease-of-use and
advanced feature set, results in a faster time to market!
### Protecting the Software Investment
GUIX is written exclusively in ANSI C and is fully integrated with the
ThreadX real-time operating system. This means GUIX applications are
instantly portable to all ThreadX supported processors. Better yet, a
completely new processor architecture can be supported with ThreadX in a
matter of weeks. As a result, using GUIX ensures the application's
migration path and protects the original development investment.

142
rtos-docs/guix/chapter-2.md Normal file
View File

@@ -0,0 +1,142 @@
---
title: Chapter 2 - Installation and Use of GUIX
description: This chapter contains a description of various issues related to installation, setup, and use of the high performance user interface product GUIX.
---
# Chapter 2 - Installation and Use of GUIX
This chapter contains a description of various issues related to
installation, setup, and use of the high performance user interface
product GUIX.
## Host Considerations
Embedded development is usually performed on Windows or Linux (Unix)
host computers. After the application is compiled, linked, and the
executable is generated on the host, it is downloaded to the target
hardware for execution.
Usually the target download is done from within the development tool's
debugger. After download, the debugger is responsible for providing
target execution control (go, halt, breakpoint, etc.) as well as access
to memory and processor registers.
Most development tool debuggers communicate with the target hardware via
on-chip debug (OCD) connections such as JTAG (IEEE 1149.1) and
Background Debug Mode (BDM). Debuggers also communicate with target
hardware through In-Circuit Emulation (ICE) connections. Both OCD and
ICE connections provide robust solutions with minimal intrusion on the
target resident software.
As for resources used on the host, the source code for GUXI is delivered
in ASCII format and requires approximately 30 Mbytes of space on the
host computer's hard disk.
## Target Considerations
GUIX requires between 5 KBytes and 80 Kbytes of Read-Only Memory (ROM)
on the target. Another 5 to 10KBytes of the target's Random Access Memory (RAM) are required for the GUIX thread stack and other global data structures.
In addition, GUIX requires the use of a ThreadX timer and a ThreadX
mutex object. These facilities are used for periodic processing needs
and thread protection inside GUIX.
## Product Distribution
GUIX can be obtained from our public source code repository at <https://github.com/azure-rtos/guix/>.
The following is a list of the important files common to most product distributions:
| Filename&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;| Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| gx_api.h | This C header file contains all system equates, data structures, and service prototypes. |
| gx_port.h | This C header file contains all target-specific and development tool-specific data definitions and structures. |
| gx.a (or gx.lib) | This is the binary version of the GUIX C library. This is normally built by compiling and archiving the provided GUIX library source files, however this library may be provided in pre-built form depending on your hardware target and license type. |
> **Important:** *All files are in lower-case, making it easy to convert the commands to Linux (Unix) development platforms.*
## GUIX Installation
GUIX is installed by cloning the GitHub repository to your local machine. The following is typical syntax for creating a clone of the GUIX repository on your PC:
```c
git clone https://github.com/azure-rtos/guix
```
Alternatively you can download a copy of the repository using the download button on the GitHub main page.
You will also find instructions for building the GUIX library on the front page of the online repository.
**Note:** *Application software needs access to the GUIX library file, usually called **gx.a** (or **gx.lib**), and the C include files **gx_api.h** and **gx_port.h**. This is accomplished either by setting the appropriate path for the development tools or by copying these files into the application development area.*
## Using GUIX
Using GUIX is easy. Basically, the application code must include ***gx_api.h*** during compilation and link with the GUIX library ***gx.a*** (or ***gx.lib**)*.
There are four easy steps required to build a GUIX
application:
| Steps | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Step&nbsp;1: | Include the ***gx_api.h*** file in all application files that use GUIX services or data structures. |
| Step&nbsp;2: | Initialize the GUIX system by calling ***gx_system_initialize*** from the ***tx_application_define*** function or an application thread. |
| Step&nbsp;3: | Create a display instance, create a canvas for the display, and create the root window and any other windows or widgets necessary. |
| Step&nbsp;4: | Compile application source and link with the GUIX runtime library ***gx.a*** (or ***gx.lib***). The resulting image can be downloaded to the target and executed! |
## Troubleshooting
Each GUIX port is delivered with a demonstration application that
executes on specific display hardware. The same basic demonstration is
delivered with all versions of GUIX. It is always a good idea to get the
demonstration system running first.
If the demonstration system does not run properly, perform the following
operations to narrow the problem:
1. Determine how much of the demonstration is running.
2. Increase the stack size of the GUIX thread by changing the
compile-time constant **GX_THREAD_STACK_SIZE** and recompiling
the GUIX library
3. Recompile the GUIX library with the appropriate debug options listed
in the configuration option section.
4. Examine the return status from all API calls.
5. Determine if there is an internal system error by setting a
breakpoint at the function ***_gx_system_error_process***. There
error code and caller should give clues as to what might be going
wrong.
6. Temporarily bypass any recent changes to see if the problem
disappears or changes.
## Configuration Options
There are several configuration options when building the GUIX library and the application using GUIX. These options are used to tune the library size and feature set to best fit your application requirements. For example, if your application will have only one thread utilizing the GUIX API services, the configuration flag **GX_DISABLE_MULTITHREAD_SUPPORT** should be defined to eliminate the overhead associated with protecting critical code sections from pre-emption by multiple threads. The various configuration flags can be defined in the application source, on the command line, or within the ***gx_user.h*** include file.
Whenever the GUIX library configuration flags are modified, it is
required to rebuild both the GUIX library and your application modules
for the configuration changes to take effect.
The complete list of configuration flags is documented in Appendix H:
GUIX Build-Time Configuration Flags.
## GUIX Version ID
The current version of GUIX is available to both the user and the
application software during runtime. The programmer can obtain the GUIX version from examination of the ***gx_port.h*** file. In addition, this file also contains a version history of the corresponding port Application software can obtain the GUIX version by examining the global string ***_gx_version_id*** in ***gx_port.h***.
Application software can also obtain release information from the
constants shown below defined in ***gx_api.h**.* These constants
identify the current product release by name and the product major and
minor version.
```C
#define __PRODUCT_GUIX__
#define __GUIX_MAJOR_VERSION__
#define __GUIX_MINOR_VERSION__
```

Some files were not shown because too many files have changed in this diff Show More