developersguide:liveupdate
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
|
developersguide:liveupdate [2015/09/23 16:15] dcvmoole Page moved from private:liveupdate to developersguide:liveupdate |
developersguide:liveupdate [2015/11/15 01:51] dcvmoole [Setting up the system] don't merge my dashes dokuwiki. |
||
|---|---|---|---|
| Line 33: | Line 33: | ||
| ==== Setting up the system ==== | ==== Setting up the system ==== | ||
| - | We cover all the steps to set up a MINIX3 system that is ready for live update and rerandomization. For now, it requires crosscompilation as well as an additional build of the LLVM source code. The procedure is for x86 targets only. The current procedure is not quite ideal, but it is what we have right now, and it should work. | + | We cover all the steps to set up a MINIX3 system that is ready for live update and rerandomization. For now, it requires crosscompilation as well as an additional build of the LLVM source code. The procedure is for x86 targets only. The current procedure is not quite ideal, but it is what we have right now. |
| + | |||
| + | **Warning**: in fact, the current procedure has been tested only from **Linux** as host platforms, and may not work from other host platforms without minor or major changes to various scripts. See [[https://github.com/Stichting-MINIX-Research-Foundation/minix/issues/93|here]] for additional information on how to get things going from **FreeBSD**. Please feel free to open additional GitHub issues for other platforms and link to them from here. Also, please do keep in mind the current infrastructure is temporary, and will eventually be replaced by proper integration - see also the section on open issues later in this document. | ||
| After setting up an initial environment, the MINIX3 update cycle basically consists of four steps: obtaining or updating the MINIX3 source code, building the system, instrumenting the system services, and generating a bootable image. We will go through all steps in detail. At the end of this section, there is also a summary of the commands to issue. | After setting up an initial environment, the MINIX3 update cycle basically consists of four steps: obtaining or updating the MINIX3 source code, building the system, instrumenting the system services, and generating a bootable image. We will go through all steps in detail. At the end of this section, there is also a summary of the commands to issue. | ||
| + | |||
| + | <div center round important> | ||
| + | **Important**: due to side effects of an unrelated recent change, the instructions in this section currently do not work on the latest MINIX3 source tree. We are working on resolving this problem. In the meantime, for live update support, please check out git revision **b5400f9**, for example by issuing ''<nowiki>git reset --hard b5400f9</nowiki>'' after cloning the MINIX3 source tree. | ||
| + | </div> | ||
| All of the commands in this section are to be performed on the crosscompilation host system rather than on MINIX3. None of the commands, except the Linux-specific ''sudo apt-get'' example in the first subsection, require more than ordinary user privileges. | All of the commands in this section are to be performed on the crosscompilation host system rather than on MINIX3. None of the commands, except the Linux-specific ''sudo apt-get'' example in the first subsection, require more than ordinary user privileges. | ||
| Line 41: | Line 47: | ||
| === Setting up the environment === | === Setting up the environment === | ||
| - | The initial step is to set up a crosscompilation environment. General information about setting up a crosscompilation environment can be found on the [[private:crosscompiling|crosscompilation page]]. As one example, the reference platform used to test the instructions in this document was the developer desktop edition of Ubuntu 14.04, a.k.a. ''ubuntu-14.04.2-desktop-i386.iso'', with the following extra packages installed: | + | The initial step is to set up a crosscompilation environment. General information about setting up a crosscompilation environment can be found on the [[.:crosscompiling|crosscompilation page]]. As one example, the reference platform used to test the instructions in this document was the developer desktop edition of Ubuntu 14.04, a.k.a. ''ubuntu-14.04.2-desktop-i386.iso'', with the following extra packages installed: |
| $ sudo apt-get install curl clang binutils zlibc zlib1g zlib1g-dev libncurses-dev qemu-system-x86 | $ sudo apt-get install curl clang binutils zlibc zlib1g zlib1g-dev libncurses-dev qemu-system-x86 | ||
| Line 55: | Line 61: | ||
| === Obtaining or updating the MINIX3 source code === | === Obtaining or updating the MINIX3 source code === | ||
| - | The first real step is to fetch the MINIX3 source code. Other wiki pages cover this in more detail, but the simplest approach is to check out the sources from the main MINIX3 repository using [[private:usinggit|git]]: | + | The first real step is to fetch the MINIX3 source code. Other wiki pages cover this in more detail, but the simplest approach is to check out the sources from the main MINIX3 repository using [[.:usinggit|git]]: |
| $ cd /home/user/minix-liveupdate | $ cd /home/user/minix-liveupdate | ||
| Line 91: | Line 97: | ||
| After the first run, the ''configure.llvm'' will perform recompilation of only the parts of the source code that have changed, and should not take nearly as long to run as the first time. In case of unexpected problems when rebuilding, it may be necessary to throw away the previously generated objects and rebuild the MINIX3 source code in its entirety. This can be done by going to the top-level ''obj.i386'' directory and deleting all files and directories in there, except the ''tooldir.{yourplatform}'' subdirectory. Fully rebuilding the MINIX3 source code will take longer than an incremental rebuild, but since the crosscompilation toolchain is left as is, it will still be nowhere close as long as the first run. | After the first run, the ''configure.llvm'' will perform recompilation of only the parts of the source code that have changed, and should not take nearly as long to run as the first time. In case of unexpected problems when rebuilding, it may be necessary to throw away the previously generated objects and rebuild the MINIX3 source code in its entirety. This can be done by going to the top-level ''obj.i386'' directory and deleting all files and directories in there, except the ''tooldir.{yourplatform}'' subdirectory. Fully rebuilding the MINIX3 source code will take longer than an incremental rebuild, but since the crosscompilation toolchain is left as is, it will still be nowhere close as long as the first run. | ||
| - | As explained in more detail on the [[private:crosscompiling|crosscompilation page]], it is also possible to rebuild particular parts of the system without going through the entire "make build" process. This involves the use of the ''nbmake-i386'' tool and generally requires a good understanding of the compilation process. It may be worth mentioning that the first ''configure.llvm'' run saves the ''MKMAGIC'' value, so this variable need not be passed to ''nbmake-i386'' each time. We give one example of how to use nbmake-i386 in a later section. | + | As explained in more detail on the [[.:crosscompiling|crosscompilation page]], it is also possible to rebuild particular parts of the system without going through the entire "make build" process. This involves the use of the ''nbmake-i386'' tool and generally requires a good understanding of the compilation process. It may be worth mentioning that the first ''configure.llvm'' run saves the ''MKMAGIC'' value, so this variable need not be passed to ''nbmake-i386'' each time. We give one example of how to use nbmake-i386 in a later section. |
| === Rebuilding the instrumentation === | === Rebuilding the instrumentation === | ||
| Line 438: | Line 444: | ||
| - It does not suffer from specific state transfer issues. | - It does not suffer from specific state transfer issues. | ||
| - | The first three points are required for all services in any case, and are not specific to live update. These points are therefore covered better on other pages, in particular those on [[private:driverprogramming|programming device drivers on MINIX3]] and the [[private:sef|System Event Framework API]] (warning: currently outdated). We do explain the reason behind these three points in detail later on. | + | The first three points are required for all services in any case, and are not specific to live update. These points are therefore covered better on other pages, in particular those on [[.:driverprogramming|programming device drivers on MINIX3]] and the [[.:sef|System Event Framework API]] (warning: currently outdated). We do explain the reason behind these three points in detail later on. |
| Only the fourth point is specific to live update, and is relevant only to a small subset of services. This point is covered in more detail in the "State transfer in practice" section below. Specifically, as a service developer, you will want to verify that your new service does not suffer from potential issues with long-running memory grants, userspace threads, and physically unmovable memory. Then, you will want to test **self state transfer** on your service, and resolve any state transfer errors that come up. Only in these cases does the SEF live-update API (that is, the sef_*_lu_*(3) calls) become relevant. We do not elaborate on most of the SEF API in this document. | Only the fourth point is specific to live update, and is relevant only to a small subset of services. This point is covered in more detail in the "State transfer in practice" section below. Specifically, as a service developer, you will want to verify that your new service does not suffer from potential issues with long-running memory grants, userspace threads, and physically unmovable memory. Then, you will want to test **self state transfer** on your service, and resolve any state transfer errors that come up. Only in these cases does the SEF live-update API (that is, the sef_*_lu_*(3) calls) become relevant. We do not elaborate on most of the SEF API in this document. | ||
| Line 665: | Line 671: | ||
| * **ixfer**: Identity Transfer. This annotation will copy the data over as is, without performing analysis on the memory. As an example, the ixfer annotation can be used for pointer values that should not be analyzed as pointers, for instance because they are pointers into another address space. A practical example where it is used is a process table copied in from another service. Such process tables typically contain external pointers, which will be unused by the local service. Some other values may still be needed after state transfer, which is why ixfer is used rather than noxfer. | * **ixfer**: Identity Transfer. This annotation will copy the data over as is, without performing analysis on the memory. As an example, the ixfer annotation can be used for pointer values that should not be analyzed as pointers, for instance because they are pointers into another address space. A practical example where it is used is a process table copied in from another service. Such process tables typically contain external pointers, which will be unused by the local service. Some other values may still be needed after state transfer, which is why ixfer is used rather than noxfer. | ||
| * **cixfer**: Conditional Identity Transfer. This annotation will cause the state transfer framework to try to interpret and transfer the value as a pointer, and fall back to identity transfer if this fails. As an example, the cixfer annotation can be used for variables which may contain either a pointer or a number value which is never a valid pointer, making the variable effectively a union of the two types. A practical example where it is used is a callback value, which is of type ''void *'' but may be used to store a small integer as well. | * **cixfer**: Conditional Identity Transfer. This annotation will cause the state transfer framework to try to interpret and transfer the value as a pointer, and fall back to identity transfer if this fails. As an example, the cixfer annotation can be used for variables which may contain either a pointer or a number value which is never a valid pointer, making the variable effectively a union of the two types. A practical example where it is used is a callback value, which is of type ''void *'' but may be used to store a small integer as well. | ||
| - | * **pxfer**: Pointer Transfer. This annotation forces a non-pointer value to be interpreted as a pointer, and transferred accordingly. As an example, the pxfer annotation may be used when a pointer value is stored in an integer type. As of writing, this annotation is not used in practice. | + | * **pxfer**: Pointer Transfer. This annotation forces a value to be interpreted as a pointer, and transferred accordingly. As an example, the pxfer annotation may be used when a pointer value is stored in an integer type. The pxfer annotation may also be used for a union of (differently typed) pointers. Thus, in some cases, a union-of-structures can be split up into a union of non-pointers and one or more unions of pointers, marking the non-pointer union with ''ixfer'' and the pointer union(s) with ''pxfer''. This is indeed how ''pxfer'' is currently used in practice as well. |
| * **sxfer**: Structure Transfer. This annotation forces a union that consists of structures, to be interpreted as one single structure, and transferred accordingly. The annotation requires that the fields of the structures making up the union all line up. For example, if the first field of one structure in the union is an integer value, then the first field of all other structures in the union must be an integer value as well. If the second field is a pointer in one structure, it must be a pointer in all of them, etcetera. The sxfer annotation can be used to resolve state transfer issues with unions that consist of nearly-identical structures. The programmer must line up the structure's fields as appropriate when annotating the union as sxfer. | * **sxfer**: Structure Transfer. This annotation forces a union that consists of structures, to be interpreted as one single structure, and transferred accordingly. The annotation requires that the fields of the structures making up the union all line up. For example, if the first field of one structure in the union is an integer value, then the first field of all other structures in the union must be an integer value as well. If the second field is a pointer in one structure, it must be a pointer in all of them, etcetera. The sxfer annotation can be used to resolve state transfer issues with unions that consist of nearly-identical structures. The programmer must line up the structure's fields as appropriate when annotating the union as sxfer. | ||
developersguide/liveupdate.txt · Last modified: 2022/02/12 22:42 by stux
