IPC@CHIP® RTOS-PPC – API Documentation

Header image

Main page


Command shell: File system commands


CD directory: Change the current working directory
Changes the current working directory in the command shell.
Example:
cd temp
Since:
SC2x3 V1.00


CHKDSK [drive letter] [/F]: Check disk integrity

This command checks a specified disk and displays a status report. The command line option /F can be used to repair certain types of faults detected on the drive.

Go here for more detailed information about this command.

When no drive is specified, as done in the first example below, the CHKDSK operation is done on the current working directory's drive.

CHKDSK can be invoked using the BIOS_ExecuteExt() API with results reported in a DiskStatS object allocated by the user.
Examples:
CHKDSK
CHKDSK B:
CHKDSK A: /F
Since:
SC2x3 V1.02
Changes:
SC2x3 V1.50: Check SD card first sector alignment.


EXTIDE [partitionDriveE partitionDriveF]: Install IDE/ATA driver

This command installs the built-in IDE/ATA disk driver. Connected CompactFlash cards or hard disks will be installed as external disk drives.

The driver will auto-detect the connected ATA disk devices. The driver will map ATA drive 0 to drive letter E: and ATA drive 1 to drive F:.

If the command is called without parameters, the first partition of the drive will be mounted. Optionally, the partition number (1-4) can be selected with command line arguments.
Example:
extide
extide 1 2          ; Install partition 1 on E:, partition 2 on F:
Since:
SC2x3 V1.00
Related:
External disk API


COPY filename1 filename2: Copy a file
Copy a file. The two file specifiers must be complete file names. Wildcards such as * or ? are not allowed.

This command will fail if the resulting overall full path length of the new file exceeds a maximum (see below). This full path includes the drive letter and back slashes in the count, e.g.:
A:\TEMP\MY_FILE.TXT
Each of the string length specifications here do not include in the count the required final string terminating NIL character.

The over all maximum path length is 259 characters. The names in each segment of the full path are limited to 255 characters maximum.

When BIOS_ExecuteExt() API is used to invoke this command, a progress indication and completion status is reported to the caller.
Example:
cd temp
Since:
SC2x3 V1.00


DEL filename: Delete a file
Delete a file or all files that match the wildcard.

Files which have the Read-only attribute set cannot be deleted.
Example:
del *.dat
Since:
SC2x3 V1.00
Related:
DIR command


DIR filename: List a direcory
List the directory entry or all entries that match the wildcard.

If no argument is given, *.* is assumed.

The file's attributes are shown with three letter designations. The letter is replaced by a dash, '-', when the respective attribute is not set. These three attributes are, from left to right:
  • A - Archive flag
  • R - Read-only file
  • S - System file

    Plus this 4th attribute letter will appear by hidden files exposed with the /H command line option
  • H - Hidden file
The DIR command by default does not list files that have the hidden attribute flag set. The /H option can be used to include the hidden files in the listing. The /H option is case insensitive and it may appear anywhere on the command line after the DIR (order not important).

The user is free to use the A and S flags as they please. These flags play no role inside the @CHIP-RTOS-PPC file system operation.

The read-only attribute will prevent files from being deleted so long as this flag is set.

Note that C language applications can control these attribute flags with the _dos_setfileattr() standard C-library function.

Following the long file names, the short 8.3 DOS alias name will be shown in paranthesis where applicable. Note that for very large directories with over 4000 files, this system will not generate any further short 8.3 DOS name aliases when files are created in order to avoid an excessively long file creation time.
Example:
  dir *.exe
  dir /H  *.exe
  DIR *.txt /h
  dir  /h
Since:
SC2x3 V1.00
Related:
DEL command


EDIT [filename]: Edit a text file
This command provides a simple text editer.
Example:
edit chip.ini
Since:
SC2x3 V1.00


EXTIDE [partitionDriveE partitionDriveF]: Install IDE/ATA driver

This command installs the built-in IDE/ATA disk driver. Connected CompactFlash cards or hard disks will be installed as external disk drives.

The driver will auto-detect the connected ATA disk devices. The driver will map ATA drive 0 to drive letter E: and ATA drive 1 to drive F:.

If the command is called without parameters, the first partition of the drive will be mounted. Optionally, the partition number (1-4) can be selected with command line arguments.
Example:
extide
extide 1 2          ; Install partition 1 on E:, partition 2 on F:
Since:
SC2x3 V1.00
Related:
External disk API


FORMAT drive [/C:n] [/O] [/PLP] [/R:n] [/Q] [/F:n]: Format a disk drive

All information on the drive will be lost !

Make sure that other tasks do not access the drive when formatting.

Command Line Options:

  • /C:n - Specifies 'n' sectors per cluster.
  • /E - Erase data sectors.
  • /F:n - Where 'n' is 16 or 32 to specify FAT16 or FAT32 formatting on external drives B: or D: and E: or F:
  • /O - Use old "Legacy" FTL method on A: flash drive for backwards compatibility with order @CHIP-RTOS-PPC versions.
  • /PLP - Power Loss Protection
  • /Q - Quiet, do not give the "Are you sure?" prompt.
  • /R:n - Specifies 'n' root directory entries (FAT12 or FAT16 only).

Comments

The @CHIP-RTOS-PPC file system supports FAT32, allowing large B:, D:, E: or F: drive volumes to be used. The file system automatically makes the determination whether to use FAT12, FAT16 or FAT32 based on the number of disk clusters to be managed. This decision will be influenced by cluster size (sectors per cluster).

The cluster size parameter /C: is optional. This parameter cannot be applied to the C: RAM drive, which automatically selects its own cluster size appropriate for the FAT12 file allocation table which is used. For the other drives, a specified cluster size must be one of following legal values:

     1, 2, 4, 8, 16, 32, 64

The default cluster size for the internal A: drive is 2 sectors per cluster. (The file system's sector size is 512 bytes.) The default cluster size for all other drives vary depending on the volume size. The system will attempt to preserve the external B: and D: drive's existing cluster size (assuming that the drive was already formatted) when no explicit cluster size has been specified at the FORMAT command. (This is done to preserve existing performance on SD drives.)

With parameter /R you can specify the number of root directory entries for FAT12 or FAT16 drive formats. Note that the actual number of root entries must be a multiple of 16, so your specified number of root entries will be rounded up if necessary to the nearest multiple of 16. The /R option for root directory entry count has no meaning for FAT32 volumes and will be ignored. (A FAT32 root directory has no particular limit on number of entries.) On external FAT16 drives, you may end up with more root directory entries than you had asked for if for cluster alignment purposes these sectors would have otherwise been scored as unused "reserved" sectors. The resulting number of root directory entries can be inspected with the CHKDSK command.

If the quiet mode parameter /Q is specified, the "Sure (Y/N) ?" confirmation check is skipped. Specify this if you call this command with the BIOS_Execute() or BIOS_ExecuteExt() API functions. When invoked by BIOS_ExecuteExt(), a progress feedback is provided to the calling program.

The default numbers of root directory entries are:

     128 entries on A: flash drive
     512 entries on B:, D:, E: and F: external drives (assuming FAT32 format is not used)
     32 entries on C: RAM drive

Note that long file names eat up additional directory entries according to name length as:

     number_of_extra_directory_entries = (strlen(filename) + 12) / 13 ;

The 8.3 DOS style file names require no additional directory entries provided that the file name is all upper case.

The /O option formats the flash drive in a manner compatible with earlier @CHIP-RTOS-PPC versions (before version 1.10). The method used in the Flash Translation Layer (FTL) was changed with @CHIP-RTOS-PPC version 1.10 to extend the flash memory life expectancy. The /O option defeats this optimization for backwards compatibility, and configures the A: drive to use the "Legacy" FTL method instead of the newer "Modulo" method. The FTL method currently in use can be seen with the FTLSTAT command.

The /PLP option specifies that the drive should be formatted to use Power Loss Protection. The file system's PLP mechanism prevents disk corruption in the event that system power is lost during file write activity. The /PLP option is not available on the C: RAM drive.

The CHKDSK command can be used to determine if a particular drive has been formatted with the /PLP option.

Command line options /F:32 or /F:16 for the external drives can be used to explicitly specify either FAT32 or FAT16 formats, respectively. Depending on a disk's sector count, either of these options may fail if an appropriate sectors per cluster count cannot be found, or if a sectors per cluster count specified with the /C: option does not suite the specified FAT16/FAT32 format. The /F: option is valid only on external drives B:, D:, E: and F:
Example:
 format A: /C:2
 format B: /C:4
 format B: /R:256
 format B: /F:32
Since:
SC2x3 V1.00
Changes:
SC2x3 V1.10: Add /PLP and /O options
Changes:
SC2x3 V1.50: Align SD card first data sector.
Related:
FTLSTAT command


FTLRECL: Reclaim sectors in flash translation layer
Reclaims all dirty sectors in the flash translation layer on drive A:.

The filesystem does an auto reclaim, if the free sectors reach a specific number (<5). A manual operated reclaim is not necessary.
Example:
ftlrecl
Since:
SC2x3 V1.00
Related:
FTLSTAT command


MD directory: Creates a direcotory
Creates a subdirectory.

This command will fail if the resulting overall full path length exceeds a maximum (see below). This full path includes the drive letter and back slashes in the count, e.g.:

     A:\TEMP\

Each of the string length specifications here do not include in the count the required final string terminating NIL character.

The over all maximum path length is 259 characters. The names in each segment of the full path are limited to 255 characters maximum.
Example:
md temp
Since:
SC2x3 V1.00


FTLSTAT: Display state of flash translation layer
Displays the state of the flash translation layer an A: drive. This includes counts for total number of free, dirty and valid sectors.

The flash translation layer provides the logic for the file system to access small virtual sectors (512 Byte) from larger physical flash sectors (>=64 kB). This is necessary, because only complete physical sectors can be erased. This layer also assures a wear leveling, so that data gets spread across the media.

The FTLSTAT command shows the state of the managed small virtual sectors. Valid sectors are sectors that have valid content. Free sectors are sectors that have all bits in the erased state. Dirty sectors are sectors that have been discarded or replaced. Dirty sectors are automatically reclaimed, if the free sector count reachs a low number (< 5). Reclamation means that all valid sectors in a physical block that has dirty sectors are copied to another physical block, before the whole physical block is erased to recover the dirty sectors.

This FTLSTAT command also lists the translation method that is in use. There are two such methods, designated "Modulo" and "Legacy". The newer "Modulo" method is preferable to the older "Legacy" method since the "Modulo" method will better spread the wear across the entire flash memory device as the drive's frequently changed FAT sectors are written, However the "Modulo" method is not compatible with older @CHIP-RTOS-PPC versions (before version 1.10). Disk formatted by earlier @CHIP-RTOS-PPC versions must be reformatted to take advantage of the preferred "Modulo" method.
Example:
ftlstat
Since:
SC2x3 V1.00
Changes:
SC2x3 V1.10: Show FTL method (Legacy/Modulo)
Related:
FTLRECL command


RD directory: Removes a directory
Removes a directory. This command cannot be executed on directories containing data.
Example:
rd temp
Since:
SC2x3 V1.00


REN oldpath newname: Rename a file/directory
Rename a file or directory specified by 'oldpath' to 'newname'.

Wildcards such as * or ? are not allowed in either of the file names. The command fails after no operation if a file or directory at the 'newname' already exists.

Files or directories which are in use by a task or program cannot be renamed or moved.

This command's functionality can be reached from within a program using the rename() standard C-Library function.

Files can be moved to another directory on the same drive by specifying a path with the new name. When no path is specified for the new name, the file or directory is given the new name at its existing location.

Similarly, directories can be moved provided that the destination is not a directory nested inside the directory that is being moved. (Such a move would not make any sense.) The new directory name can optionally be different from the original name.

The path that a file or directory is moved to must already exists. No new directories are created by REN along the way.

Before performing a directory move, the file system checks to assure that no file or directory will end up with a name which exceeds the 259 character limit on path string lengths. The REN operation fails with no operation performed if such a path name would result.

On drives with PLP formatting, the REN command executes atomically across a power loss event such that when the drive is installed after the power loss either none or all of the REN operation will be completed. This rule also applies to the directory move operation.

Note that a file or directory move operation is implemented without moving any actual disk data clusters. Only some directory node entries are edited, making the action more efficient than would be a file copy and deleting the old file(s) sequence.

When there are open files within a moved directory or its subdirectories, these files remain open and operational after the move.

If a task's current working directory is within subdirectories of a directory which is moved, then following this directory move, that task's current working directory will also have moved. For example, in the following experiment the console task's current working directory change from B:\Dir1\Subdir1 to B:\Dir2\MovedDir1\Subdir1 can be observed as a result of the directory move by REN.
    B:\>md Dir1
    B:\>md Dir2
    B:\>cd Dir1
    B:\Dir1\>md Subdir1
    B:\Dir1\>cd Subdir1
    B:\Dir1\Subdir1\>REN \Dir1 \Dir2\MovedDir1
    Renamed \Dir1 to \Dir2\MovedDir1
    B:\Dir2\MovedDir1\Subdir1\>
Examples:
     ... Simply rename a file
    REN  A:\subdir\readme.txt  newname.txt
      ... Move a file (you could also rename it here)
    REN  B:\Dir1\readme.txt  B:\Dir2\otherDir\readme.txt
      ... Move a directory named 'otherDir'
    REN  B:\Dir1\otherDir  B:\Dir2\otherDir
      ... Move and rename the directory 'otherDir' to 'movedDir'.
    REN  B:\Dir1\otherDir  B:\Dir2\movedDir
Since:
SC2x3 V1.10


TYPE filename: Type a file
Show contents of a file on the console.
Example:
type chip.ini
Since:
SC2x3 V1.00


XTRANS port s/r filename: File transfer: Send/Receive file with Xmodem.
Send/Receive file with XMODEM/CRC protocol. Possible devices are UART1, UART3 and USER.
Example:
xtrans UART1 r chip.ini         ;Receive CHIP.INI file over UART1
xtrans UART3 s test.txt         ;Send TEST.TXT file over UART3
Since:
SC2x3 V1.00





Top of page | Main page

Copyright © 2017 Beck IPC GmbH
Generated on Thu Jan 26 16:21:35 2017 by Doxygen 1.6.1