PTP Boot

Files CCore/inc/net/PTPBootBase.h CCore/src/net/PTPBootBase.cpp

Files CCore/inc/net/PTPBoot.h CCore/src/net/PTPBoot.cpp

PTP Boot is a PTP service with 3 functions. The service id is 4. Function ids are 1-3. This protocol is used for the remote boot. Abstract boot is a process, during which a group of boot sections are allocated and filled. Then the boot command is issued to start an execution from the given address (aka "entry point"). The most common example is an application boot, sections are placed in the target memory and filled with the application data and code.

const ServiceIdType ServiceId = 4 ;
   
const FunctionIdType FunctionId_Alloc = 1 ;
const FunctionIdType FunctionId_Write = 2 ;
const FunctionIdType FunctionId_Boot  = 3 ;

Protocol types and constants:

using AddressType = uint64 ;

using IndexType = uint32 ;

const unsigned DeltaWriteLen   =   24 ;
const unsigned MaxWriteDataLen = 1416 ; // MaxInfoLen-DeltaWriteLen

Function Alloc has the following input/output:

struct AllocInput
 {
  AddressType address;
  AddressType len;
 };
    
struct AllocOutput
 {
  IndexType index;
 }; 

This function allocates a boot section at the given address with the given length. Return value is the section index. Section is a continuous byte range.

Function Write has the following input/output:

struct WriteInput
 {
  IndexType index;
  AddressType off;
  LenType len : len<=MaxWriteDataLen ;
  uint8 data[len];
 };
    
struct WriteOutput
 {
 }; 

This function is used to fill a section. index is a previously allocated section index. off is a data offset inside the section. Then data follows.

Function Boot has the following input/output:

struct BootInput
 {
  AddressType entry_point;
  FlagType flags;
 };
    
struct BootOutput
 {
 }; 

This function completes the boot process. It specifies the entry point and boot flags. The meaning of the flags is implementation-defined.

The file txt/cpp/PTPBoot.txt.cpp contains this service definition.

The file net/PTPBootBase.h contains this service definition in C++ in the namespace PTPBoot.

PTP Boot classes

There are two PTP Boot classes: BootClient and BootInfo. They are located in the namespace PTPBoot. BootClient is a client part (host part), and BootInfo is a server part (target part). A target serves as a server in this case.

BootClient

This class can be used to perform PTPBoot operations via a PTP Client device.

class BootClient : NoCopy
 {
   ....

  public:
   
   // constructors
  
   explicit BootClient(StrLen ptp_dev_name,MSec timeout=DefaultTimeout,ulen max_packets=DefaultMaxPackets);
   
   ~BootClient();
   
   // methods
   
   IndexType alloc(AddressType address,AddressType len);
   
   void write(IndexType index,AddressType off,PtrLen<const uint8> data);
   
   void boot(AddressType entry_point,FlagType flags);
 };

The first constructor argument is a PTP ClientDevice object name. Others are the operations timeout and the packet count limit. All methods throw an exception in case of error.

alloc() allocates a section. The section index is returned.

write() fills a section with data. The data length is not limited for this method, it spawns as many write operations as necessary to do the job.

boot() completes the boot.

BootInfo

BootInfo is a Partial class, you must derive a class from it to use it.

class BootInfo : NoCopy
 {
   ....

  protected:
  
   class Sect : NoCopy
    {
      ....

     public: 
      
      AddressType getAddress() const;
      
      AddressType getLen() const;
      
      PtrLen<const uint8> getData() const;
    };
    
   DynArray<Sect> table;
   
   AddressType entry_point;
   FlagType flags;
   
  private:
   
   virtual void signal_complete()=0;
   
   virtual void wait_complete()=0;
  
  public:
  
   BootInfo();
   
   ~BootInfo();
   
   void get(StrLen ptp_server_name,MSec timeout=DefaultTimeout);
 };

Once a BootInfo object is created, you can start a remote boot process by the method get(). The first argument is a PTP ServerDevice object name. During the boot process all data are accumulated in the protected members. The second argument is used to wait for the completion of PTP transactions after the boot process is finished.

table is a section table, each section record has an address, a section length and data.

entry_point is the entry point.

flags is the boot flags.

wait_complete() is called inside the method get() to wait for the process completion. A derived class must block the execution in this method until the signal_complete() is called. You may use a semaphore for the waiting. In this case the wait_complete() method simply calls the semaphore method take().

signal_complete() is called asynchronously during the boot process. It should be used to stop waiting. If you are using a semaphore for the waiting, the signal_complete() method simply calls the semaphore method give().