level-2s函数帮助文件(英文)

WriteLevel-2MATLABS-FunctionsAboutLevel-2MATLABS-FunctionsTheLevel-2MATLAB®S-functionAPIallowsyoutousetheMATLABlanguagetocreatecustomblockswithmultipleinputandoutputportsandcapableofhandlinganytypeofsignalproducedbyaSimulink®model,includingmatrixandframesignalsofanydatatype.TheLevel-2MATLABS-functionAPIcorrespondscloselytotheAPIforcreatingCMEXS-functions.MuchofthedocumentationforcreatingCMEXS-functionsappliesalsotoLevel-2MATLABS-functions.Toavoidduplication,thissectionfocusesonprovidinginformationthatisspecifictowritingLevel-2MATLABS-functions.ALevel-2MATLABS-functionisMATLABfunctionthatdefinesthepropertiesandbehaviorofaninstanceofaLevel-2MATLABS-FunctionblockthatreferencestheMATLABfunctioninaSimulinkmodel.TheMATLABfunctionitselfcomprisesasetofcallbackmethods(seeLevel-2MATLABS-FunctionCallbackMethods)thattheSimulinkengineinvokeswhenupdatingorsimulatingthemodel.ThecallbackmethodsperformtheactualworkofinitializingandcomputingtheoutputsoftheblockdefinedbytheS-function.Tofacilitatethesetasks,theenginepassesarun-timeobjecttothecallbackmethodsasanargument.Therun-timeobjecteffectivelyservesasaMATLABproxyfortheS-Functionblock,allowingthecallbackmethodstosetandaccesstheblockpropertiesduringsimulationormodelupdating.AboutRun-TimeObjectsWhentheSimulinkengineinvokesaLevel-2MATLABS-functioncallbackmethod,itpassesaninstanceoftheSimulink.MSFcnRunTimeBlockclasstothemethodasanargument.Thisinstance,knownastherun-timeobjectfortheS-Functionblock,servesthesamepurposeforLevel-2MATLABS-functioncallbackmethodsastheSimStructstructureservesforCMEXS-functioncallbackmethods.Theobjectenablesthemethodtoprovideandobtaininformationaboutvariouselementsoftheblockports,parameters,states,andworkvectors.Themethoddoesthisbygettingorsettingpropertiesorinvokingmethodsoftheblockrun-timeobject.SeethedocumentationfortheSimulink.MSFcnRunTimeBlockclassforinformationongettingandsettingrun-timeobjectpropertiesandinvokingrun-timeobjectmethods.Run-timeobjectsdonotsupportMATLABsparsematrices.Forexample,ifthevariableblockisarun-timeobject,thefollowinglineinaLevel-2MATLABS-functionproducesanerror:block.Outport(1).Data=speye(10);wherethespeyecommandformsasparseidentitymatrix.Note：OtherMATLABprogramsbesidesMATLABS-functionscanuserun-timeobjectstoobtaininformationaboutaMATLABS-functioninamodelthatissimulating.SeeAccessBlockDataDuringSimulationinUsingSimulinkformoreinformation.Level-2MATLABS-FunctionTemplateUsethebasicLevel-2MATLABS-functiontemplatemsfuntmpl_basic.mmsfuntmpl_basic.mtogetaheadstartoncreatinganewLevel-2MATLABS-function.ThetemplatecontainsskeletonimplementationsoftherequiredcallbackmethodsdefinedbytheLevel-2MATLABS-functionAPI.TowriteamorecomplicatedS-function,usetheannotatedtemplatemsfuntmpl.mmsfuntmpl.m.TocreateaMATLABS-function,makeacopyofthetemplateandeditthecopyasnecessarytoreflectthedesiredbehavioroftheS-functionyouarecreating.ThefollowingtwosectionsdescribethecontentsoftheMATLABcodetemplate.ThesectionExampleofWritingaLevel-2MATLABS-FunctiondescribeshowtowriteaLevel-2MATLABS-functionthatmodelsaunitdelay.Level-2MATLABS-FunctionCallbackMethodsTheLevel-2MATLABS-functionAPIdefinesthesignaturesandgeneralpurposesofthecallbackmethodsthatconstituteaLevel-2MATLABS-function.TheS-functionitselfprovidestheimplementationsofthesecallbackmethods.Theimplementationsinturndeterminetheblockattributes(e.g.,ports,parameters,andstates)andbehavior(e.g.,theblockoutputsasafunctionoftimeandtheblockinputs,states,andparameters).BycreatinganS-functionwithanappropriatesetofcallbackmethods,youcandefineablocktypethatmeetsthespecificrequirementsofyourapplication.ALevel-2MATLABS-functionmustincludethefollowingcallbackmethods:AsetupfunctiontoinitializethebasicS-functioncharacteristicsAnOutputsfunctiontocalculatetheS-functionoutputsYourS-functioncancontainothermethods,dependingontherequirementsoftheblockthattheS-functiondefines.ThemethodsdefinedbytheLevel-2MATLABS-functionAPIgenerallycorrespondtosimilarlynamedmethodsdefinedbytheCMEXS-functionAPI.Forinformationonwhenthesemethodsarecalledduringsimulation,seeProcessViewinSimulinkEngineInteractionwithCS-Functions.Forinstructionsonhowtoimplementeachcallbackmethod,seeWriteCallbackMethods.ThefollowingtablelistsalltheLevel-2MATLABS-functioncallbackmethodsandtheirCMEXcounterparts.Level-2MATLABMethodEquivalentCMEXMethodsetup(seeUsingthesetupMethod)mdlInitializeSizesCheckParametersmdlCheckParametersDerivativesmdlDerivativesDisablemdlDisableEnablemdlEnableInitializeConditionsmdlInitializeConditionsOutputsmdlOutputsPostPropagationSetupmdlSetWorkWidthsProcessParametersmdlProcessParametersProjectionmdlProjectionSetInputPortComplexSignalmdlSetInputPortComplexSignalSetInputPortDataTypemdlSetInputPortDataTypeSetInputPortDimensionsmdlSetInputPortDimensionInfoSetInputPortDimensionsModeFcnmdlSetInputPortDimensionsModeFcnSetInputPortSampleTimemdlSetInputPortSampleTimeSetInputPortSamplingModemdlSetInputPortFrameDataSetOutputPortComplexSignalmdlSetOutputPortComplexSignalSetOutputPortDataTypemdlSetOutputPortDataTypeSetOutputPortDimensionsmdlSetOutputPo